Query ingested telemetry data

  • Article

This article describes how to query ingested sensor data from Azure FarmBeats.

Ingesting data from Internet of Things (IoT) resources such as devices and sensors is a common scenario in FarmBeats. You create metadata for devices and sensors and then ingest the historical data to FarmBeats in a canonical format. Once the sensor data is available on FarmBeats Datahub, we can query the same to generate actionable insights or build models.

Important

Azure FarmBeats is retired. You can see the public announcement here.

We have built a new agriculture focused service, it's name is Azure Data Manager for Agriculture and it's now available as a preview service. For more information, see public documentation here or write to us at madma@microsoft.com.

Before you begin

Before you proceed with this article, ensure that FarmBeats is installed and sensor telemetry data from your IoT devices is ingested to FarmBeats.

To ingest sensor telemetry data, visit ingest historical telemetry data

Before you proceed, you also need to ensure you're familiar with FarmBeats REST APIs as you query ingested telemetry using the APIs. For more information on FarmBeats APIs, see FarmBeats REST APIs. Ensure that you are able to make API requests to your FarmBeats Datahub endpoint.

Query ingested sensor telemetry data

There are two ways to access and query telemetry data from FarmBeats:

  • API and
  • Time Series Insights (TSI).

Query using REST API

Follow the steps to query the ingested sensor telemetry data using FarmBeats REST APIs:

  1. Identify the sensor you're interested in. You can do so by making a GET request on /Sensor API.

Note

The id and the sensorModelId of the interested sensor object.

  1. Make a GET/{id} on /SensorModel API for the sensorModelId as noted in step 1. The "Sensor Model" has all the metadata and details about the ingested telemetry from the sensor. For example, Sensor Measure within the Sensor Model object has details about what measures is the sensor sending and in what types and units. For example,
{
    "name": "moist_soil_last <name of the sensor measure - this is what we will receive as part of the queried telemetry data>",
    "dataType": "Double <Data Type - eg. Double>",
    "type": "SoilMoisture <Type of measure eg. temperature, soil moisture etc.>",
    "unit": "Percentage <Unit of measure eg. Celsius, Percentage etc.>",
    "aggregationType": "None <either of None, Average, Maximum, Minimum, StandardDeviation>",
    "description": "<Description of the measure>"
}

Make a note of the response from the GET/{id} call for the Sensor Model.

  1. Do a POST call on /Telemetry API with the following input payload
{
  "sensorId": "<id of the sensor as noted in step 1>",
  "searchSpan": {
    "from": "<desired start timestamp in ISO 8601 format; default is UTC>",
    "to": "<desired end timestamp in ISO 8601 format; default is UTC>"
  },
  "filter": {
    "tsx": "string"
  },
  "projectedProperties": [
    {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  ]
}
  1. The response from the /Telemetry API looks something like this:
{
  "timestamps": [
    "2020-XX-XXT07:30:00Z",
    "2020-XX-XXT07:45:00Z"
  ],
  "properties": [
    {
      "values": [
        "<id of the sensor>",
        "<id of the sensor>"
      ],
      "name": "Id",
      "type": "String"
    },
    {
      "values": [
        2.1,
        2.2
      ],
      "name": "moist_soil_last <name of the SensorMeasure as defined in the SensorModel object>",
      "type": "Double <Data Type of the value - eg. Double>"
    }
  ]
}

In the above example response, the queried sensor telemetry gives data for two timestamps along with the measure name ("moist_soil_last") and values of the reported telemetry in the two timestamps. You need to refer to the associated Sensor Model (as described in step 2) to interpret the type and unit of the reported values.

Query using Azure Time Series Insights (TSI)

FarmBeats uses Azure Time Series Insights (TSI) to ingest, store, query, and visualize data at IoT scale, data that is highly contextualized and optimized for time series.

Telemetry data is received on an EventHub and then processed and pushed to a TSI environment within FarmBeats resource group. Data can then be directly queried from the TSI. For more information, see TSI documentation

Follow the steps to visualize data on TSI:

  1. Go to Azure Portal > FarmBeats DataHub resource group > select Time Series Insights environment (tsi-xxxx) > Data Access Policies. Add user with Reader or Contributor access.
  2. Go to the Overview page of Time Series Insights environment (tsi-xxxx) and select the Time Series Insights Explorer URL. You can now visualize the ingested telemetry.

Apart from storing, querying and visualization of telemetry, TSI also enables integration to a Power BI dashboard. For more information, see here

Next steps

After querying sensor data from your Azure FarmBeats instance, learn how to generate maps for your farms.