Quickstart: Export data from an IoT Central application

Get started with IoT Central data export to integrate your IoT Central application with another cloud service such as Azure Data Explorer. Azure Data Explorer lets you store, query, and process the telemetry from devices such as the IoT Plug and Play smartphone app.

In this quickstart, you:

  • Use the data export feature in IoT Central to the telemetry from the smartphone app to an Azure Data Explorer database.
  • Use Azure Data Explorer to run queries on the telemetry.

Completing this quickstart incurs a small cost in your Azure account for the Azure Data Explorer instance. The first two devices in your IoT Central application are free.

Prerequisites

Install Azure services

Before you can export data from your IoT Central application, you need an Azure Data Explorer cluster and database. In this quickstart, you run a bash script in the Azure Cloud Shell to create and configure them.

The script completes the following steps:

  • Prompts you to sign in to your Azure subscription so that it can generate a bearer token to authenticate the REST API calls.
  • Creates an Azure Data Explorer cluster and database.
  • Creates a managed identity for your IoT Central application.
  • Configures the managed identity with permission to access the Azure Data Explorer database.
  • Adds a table to the database to store the incoming telemetry from IoT Central.

Run the following commands to download the script to your Azure Cloud Shell environment:

wget https://raw.githubusercontent.com/Azure-Samples/iot-central-docs-samples/main/quickstart-cde/createADX.sh
chmod u+x createADX.sh

Use the following command to run the script:

  • Replace CLUSTER_NAME with a unique name for your Azure Data Explorer cluster. The cluster name can contain only lowercase letters and numbers. The length of the cluster name must be between 4 and 22 characters.
  • Replace CENTRAL_URL_PREFIX with URL prefix you chose in the first quickstart for your IoT Central application.
  • When prompted, follow the instructions to sign in to your account. It's necessary for the script to sign in because it generates a bearer token to authenticate a REST API call.
./createADX.sh CLUSTER_NAME CENTRAL_URL_PREFIX

Important

This script can take 20 to 30 minutes to run.

Make a note of the Azure Data Explorer URL output by the script. You use this value later in the quickstart.

Configure data export

To configure the data export destination from IoT Central:

  1. Navigate to the Data export page in your IoT Central application.
  2. Select the Destinations tab and then Add a destination.
  3. Enter Azure Data Explorer as the destination name. Select Azure Data Explorer as the destination type.
  4. In Cluster URL, enter the Azure Data Explorer URL you made a note of previously.
  5. In Database name, enter phonedata.
  6. In Table name, enter acceleration.
  7. In Authorization, select System-assigned managed identity.
  8. Select Save.

To configure the data export:

  1. On the Data export page, select the Exports tab, and then Add an export.

  2. Enter Phone accelerometer as the export name.

  3. Select Telemetry as the type of data to export.

  4. Use the information in the following table to add two filters:

    Name Operator Value
    Device template Equals IoT Plug and Play mobile
    Sensors/Acceleration/X Exists N/A

    Make sure that the option to export the data if all of the conditions are true is set.

  5. Add Azure Data Explorer as a destination.

  6. Add a data transformation to the destination. Add the following query in the 2. Build transformation query field on the Data transformation page:

    import "iotc" as iotc;
    {
        Device: .device.id,
        EnqueuedTime: .enqueuedTime,
        X: .telemetry | iotc::find(.name == "accelerometer").value.x,
        Y: .telemetry | iotc::find(.name == "accelerometer").value.y,
        Z: .telemetry | iotc::find(.name == "accelerometer").value.z
    }
    

    Screenshot that shows the data transformation query for the export.

    If you want to see how the transformation works and experiment with the query, paste the following sample telemetry message into 1. Add your input message:

    {
      "messageProperties": {},
      "device": {
        "id": "8hltz8xa7n",
        "properties": {
          "reported": []
        },
        "approved": true,
        "types": [],
        "name": "8hltz8xa7n",
        "simulated": false,
        "provisioned": true,
        "modules": [],
        "templateId": "urn:modelDefinition:vlcd3zvzdm:y425jkkpqzeu",
        "templateName": "IoT Plug and Play mobile",
        "organizations": [],
        "cloudProperties": [],
        "blocked": false
      },
      "component": "sensors",
      "applicationId": "40a97c91-50cc-44f0-9f63-71386613facc",
      "messageSource": "telemetry",
      "telemetry": [
        {
          "id": "dtmi:azureiot:PhoneSensors:__accelerometer;1",
          "name": "accelerometer",
          "value": {
            "x": 0.09960123896598816,
            "y": 0.09541380405426025,
            "z": 9.907781600952148
          }
        }
      ],
      "enqueuedTime": "2021-11-12T10:01:30.588Z",
      "enrichments": {}
    }
    
  7. Save the transformation. Then save the data export definition.

Wait until the export status shows Healthy:

Screenshot that shows a running data export with the healthy status.

Query exported data

To query the exported telemetry:

  1. Use the Azure Data Explorer URL output by the script you ran previously to navigate to your Azure Data Explorer environment.

  2. Expand the cluster node and select the phonedata database. The scope of the query window changes to Scope:yourclustername.eastus/phonedata.

  3. In Azure Data Explorer, open a new tab and paste in the following Kusto query and then select Run to plot the accelerometer telemetry:

['acceleration'] 
    | project EnqueuedTime, Device, X, Y, Z
    | render timechart 

You may need to wait for several minutes to collect enough data. Try holding your phone in different orientations to see the telemetry values change:

Screenshot of the query results for the accelerometer telemetry.

Clean up resources

If you don't plan to complete any further IoT Central quickstarts or tutorials, you can delete your IoT Central application:

  1. In your IoT Central application, navigate to Application > Management.
  2. Select Delete and then confirm your action.

To remove the Azure Data Explorer instance from your subscription and avoid being billed unnecessarily, delete the IoTCentralExportData-rg resource group from the Azure portal or run the following command in the Azure Cloud Shell:

az group delete --name IoTCentralExportData-rg

Next steps

In this quickstart, you learned how to continuously export data from IoT Central to another Azure service.

Now that you know now to export your data, the suggested next step is to: