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 type and cloud provider, you should use the correct HTTP endpoint.

AWS

AZURE

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://<BASE_URL>/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}}
]  

Instead of using JSON format, the HTTP connector also supports sending data in CSV format.

POST https://<BASE_URL>/data?assetId=<MAPPING_ASSET_ID>&path=<MAPPING_PATH>
Authorization Basic <AUTHORIZATION>
timestamp,foo,baz
1689064634000,bar,123
1689065756000,xyz,456 

This can help reduce the number of bytes sent in the case of a mobile connection.

GZIP Request Compression

Optionally, to reduce the network traffic, you can send requests by using the GZIP compression. It is enough to add the following header to the request, and compress the payload according to the GZIP protocol.

Content-Encoding:application/gzip

Note that to have an advantage in using GZIP compression, at least 5 measures must be added in the payload.

How to create Work Sessions

The manual work session creation can also be triggered by the HTTP connector. In cases where the machine has a limited connection (e.g. GSM), it is possible to take advantage of this function to create a work session to be saved directly to the work session history along with the relative measure data, all in one API call.

POST https://<BASE_URL>/data/workSessions?assetId=<MAPPING_ASSET_ID>&path=<MAPPING_PATH>
Authorization Basic <AUTHORIZATION>

payload
{
  "name": "DRILLING",
  "title": "Pile 001",
  "description": "Location 1234345, depth: -220m",
  "csvHeaderRow": 6
}

file
10101010101

The request must be a MULTIPART request containing:

• payload: the JSON document providing the information of the Work Session being created. This includes, the name of the Work Session Definition along the title and description of the Work Session instance.
  Optionally you can provide the csvHeaderRow, which represents the CSV row index (1-based) where the dataset header is present (e.g. timestamp,foo,baz).
• file: the CSV file containing all the measure data related to the Work Session.
  This file can also be a ZIP file containing a single CSV file. 

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.

1. Enter the DPS application.
2. Select a thing you want to map.
3. Switch to the Connection tab.
4. Select the HTTP Connector in the Connectors selection.
5. Provide the Username and Password if not inherited from the parent level.
6. Provide the Asset ID and if needed the Path.
7. 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:

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

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

Request Rate Limits

The HTTP connector endpoint can be invoked by using the same rate limit as the publishing rate limit of the thing. Connected products can publish data with a limited rate, for more details refer to the Publishing Rate Limit article. 

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.