Overview

To illustrate the process, we will here create a new Data Connector that forwards all events to dweet.io, a free hosted service that fulfills the same role as a server. If you already have a hosted HTTPS POST endpoint set up, feel free to use that instead.

Prerequisites

• Service Account Creating, deleting, and interacting with Data Connectors require that your User or Service Account has been granted the role of Project Developer or higher.

Adding a New Data Connector

Data Connectors can be created using either the DT Studio interface or our REST API. For simplicity, most of the configurations will be left default in this example. For those interested in a more custom Data Connector, the Advanced Configurations page contains the explanations for the rest.

DT Studio

REST API

DT Studio

In DT Studio, navigate to your Project. In the left menu, locate Data Connectors and press Add Data Connector. This will open the Data Connector configuration menu.

Edit the following parameters.

• Display name Give the Data Connector some identifiable display name.

• Endpoint URL The URL to which the Data Connector will forward events. As we use dweet.io in this example, simply use an URL on the form https://dweet.io/dweet/for/<SOME_UNIQUE_NAME>.

Remember to save your Data Connector configuration at the bottom of the page.

REST API

Send a POST request to:

https://api.d21s.com/v2/projects/<PROJECT_ID>/dataconnectors

A request body with the following parameters is required.

{
    "type": "HTTP_PUSH",
    "httpConfig": {
        "url": "<ENDPOINT_URL>"
    }
}

A list of all available parameters can be found in our REST API Reference.

Example Usage

Using cURL with a Service Account for authentication, the following example creates a new Data Connector with a given name "new-dcon" and a dweet.io endpoint which can be monitored at https://dweet.io/follow/<SOME_UNIQUE_NAME>.

curl -X POST "https://api.d21s.com/v2/projects/<PROJECT_ID>/dataconnectors" \
    -u "<SERVICE_ACCOUNT_KEY_ID>":"<SERVICE_ACCOUNT_SECRET>" \
    -d '{"displayName": "new-dcon", "type": "HTTP_PUSH", "httpConfig": {"url": "https://dweet.io/dweet/for/<SOME_UNIQUE_NAME>"}}'

Test Your Data Connector

The simplest way of testing your connection is by forwarding an event in one of three ways.

• Wait for a sensor in the project to naturally emit an event by its Periodic Heartbeat.

• Touching a sensor to force an emitted event.

• Use the Sensor Emulator to emulate an emitted event.

When you are certain an event has been emitted, the Data Connector metrics will be iterated.

DT Studio

REST API

DT Studio

The metrics can be found under the same page on which your Data Connector was created.

REST API

Send a GET request to:

https://api.d21s.com/v2/projects/<PROJECT_ID>/dataconnectors/<DATACONNECTOR>:metrics

The response contains the metrics for the specified Data Connector over the last 3 hours.

{
  "metrics": {
    "successCount": 44,
    "errorCount": 0,
    "latency99p": "0.663s"
  }
}

Example

Using cURL with a Service Account for authentication, the following example requests the metrics for the specified Data Connector in the specified Project.

curl -X GET "https://api.d21s.com/v2/projects/<PROJECT_ID>/dataconnectors/<DATACONNECTOR_ID>:metrics" \
    --user "<SERVICE_ACCOUNT_KEY_ID>":"<SERVICE_ACCOUNT_SECRET>"

If the Error counter is iterated instead, this indicates that a status code other than 2xx has been returned.

• Verify that your Data Connector configuration, especially the Endpoint URL, is correct.

• View the logs on your endpoint which should contain the error. For dweet.io, navigate to your generated URL, now on the form https://dweet.io/follow/<SOME_UNIQUE_NAME>. Under the Raw tab, the event body should become visible as they are forwarded. Any errors will also be shown here.