Creating a Line Graph showing device telemetry

Step 1: Get the list of devices

The user selects a device group, which implicitly defines the query to use to fetch the list of devices. See the Config UI API for more information.

Request

GET {IoT Hub manager endpoint}/devices?query={query}

Response

Content-Type: application/json; charset=utf-8

{
    Count: ...
    Items: [
        { device }, { device }, { device }, ...
    ]
    "$metadata": {
        $type: DevicesList;1
        $uri: {IoT Hub manager endpoint}/devices?query={query}
    }
}

Note that the content of the response might change over time, for instance when devices are added or removed, and when device properties change. For instance a query like "all devices with firmware 1.2" would return a different list over time. The UI decides whether to cache and reuse the query result, or whether to repeat the query to refresh the response.

Step 2: Get the devices telemetry

For a given period, the UI gets the telemetry from the Device Telemetry API. Telemetry messages might include multiple values, in which case the client decides which one to graph (see "telemetry type" UI dropdown). The telemetry messages are returned in chronological order.

Depending on the time range, the UI might want to reduce the amount of data received. For example, when showing a graph for a period of 1 month, the UI might need just one value every 6 hours to render the graph. The API supports a sampling parameter, to define the telemetry granularity. For instance with a sampling of 6 hour, the API will return up to four messages for each day in the time range. NOTE: the server side logic does not apply any average to the data though. See the API guidelines for more informaiton.

Request

Request with GET:

GET {Device Telemetry endpoint}/messages?from={time}&to={time}&sampling={duration}&devices=id1,id2,id3,...

Request with POST:

Content-Type: application/json; charset=utf-8

{
    From: {time}
    To: {time}
    Sampling: {duration}
    Devices: [ "id1", "id2", "id3", ..., "id 1000" ]
}

Response

Content-Type: application/json; charset=utf-8

{
    Count: ...
    Items: [
        {
            deviceid
            time
            value 1  // e.g. temperatue
            value 2  // e.g. humidity
            value N  // e.g. speed
            $metadata
        },
        {
            deviceid
            time
            value 1  // e.g. temperatue
            value 2  // e.g. humidity
            value N  // e.g. speed
            $metadata
        },
        ...
    ]
    "$metadata": {
        $type: MessagesList;1
        $uri: ...
    }
}