Receive data from connected objects by using the HTTPS protocol.

With this connector, your Products or IoT Platform (if any) can publish IoT data by invoking an HTTP endpoint.

Optionally, you can also specify an external HTTP endpoint to be invoked anytime an update (command execution, configuration parameter or firmware update) must be sent to the remote product. Note that, the DPS cannot establish an HTTP connection to the remote product, sending the data to the connected product will be the responsibility of the invoked service.

Servitly HTTP Endpoints

According to which environment you should target, you will need to choose the correct HTTP endpoint.

Environment	Base URL
AWS Production	https://data.servitly.com
AWS Asia Pacific Area Production	https://data-ap.servitly.com
Azure Production	https://data-az.servitly.com
AWS Sandbox	https://data-sandbox.servitly.com

How to send IoT Data

To send IoT data, the remote product or the IoT Platform must perform a POST to the following HTTP endpoint:

POST https://<BASE_URL>/data?assetId=<MAPPING_ASSET_ID>&path=<MAPPING_PATH>
Authorization Basic <AUTHORIZATION>
{
  "ts": 1689064634000,
  "data": {
     "foo": "bar",
     "baz": 123
  }
}

Where placeholders are:

BASE_URL: the HTTP connector base URL according to the target environment.
MAPPING_ASSET_ID: the Asset ID that has been specified in the mapping panel for a thing
MAPPING_ASSET_PATH: the message path, which is the concatenation of the path specified in the thing's mapping panel, and the path specified in the metric mapping panel
```
<THING_MAPPING_PATH>/<METRIC_MAPPING_PATH>  
```
AUTHORIZATION: the basic authorization header that uses the username and password specified on the thing, location, customer, or inherited from the tenant's default connector.

Optionally, you can also send multiple messages in the same request, this can be done by adding an array in the payload.

POST https://data.servitly.com/data?assetId=test-123&path=data
Authorization Basic <AUTHORIZATION>
[
  {"ts": 1689064634000, "data": {"temperature": 25.5}},
  {"ts": 1689066434000, "data": {"temperature": 25.3}},
  {"ts": 1689068234000, "data": {"temperature": 25.3}}
]

How to send remote updates

In the case of using an external IoT platform that exposes an API to be invoked to send updates to remote objects, the endpoint to be invoked to send update messages can be configured within the plugin. In the plugin you can configure the method, URL endpoint, request parameters and headers.

For any update made on the cloud side (command execution, configuration parameter update, firmware update), the JSON message is forwarded to the external endpoint as-is with in addition the topic field providing the update target (e.g. <THING_ASSET_ID>/<COMMAND_PATH>).

{
  "topic": "lamp-123/change-status",
  "data": {
        "powerOn": true
  }
}

Mapping Things

With the HTTP Connector plugin enabled and configured, now you can start mapping DPS registered things to this new connector.

Enter the DPS application.
Select a thing you want to map.
Switch to the Connection tab.
Select the HTTP Connector in the Connectors selection.
Provide the Username and Password if not inherited from the parent level.
Provide the Asset ID and if needed the Path.
Press Save and wait a few minutes for the new mapped object to be detected and data to start arriving.

Plugin Configuration

To enable this plugin, you need to:

Go to the Integrations / Plugins page.
Select the IoT Connectors category.
Locate the HTTP Connector card.
Click on the card switch to activate the plugin.
Configure the plugin properties and save.

Here is the list of all the properties that can be used in the plugin configuration.

PROPERTIES

Method

The method of the service endpoint to be used by the request.
Type: SELECTION | Optional

Endpoint URL

The URL of the remote service endpoint to be invoked.
Type: STRING | Optional

Query String Parameters

The list of additional parameters to be included to the query string.
Type: KEY_VALUE | Optional

Headers

The list of additional request headers.
Type: KEY_VALUE | Optional

Request Rate Limits

The HTTP connector endpoint can be invoked by using the same rate limit as the publishing rate limit of the thing.

For instance, given a limit of 3600 measures/hour at the single thing level, you have a total of 3600 API requests/hour that can be performed.

The rate limiter uses a refill policy allowing you to perform 60 request / minute, with an overdraft of 120 request for a few minutes.

In case you get the 429 response, you can inspect the "Retry-After" header to know how much time you have to wait before the next request.

Be careful, that if you include multiple messages in the same request, each message consumes a request.