Tutorial: Use the REST API to manage an Azure IoT Central application

Alt
08/20/2024

This tutorial shows you how to use the Azure IoT Central REST API to create and interact with an IoT Central application. This tutorial uses the REST API to complete many of the steps you completed by using the Web UI in the quickstarts. These steps include using an app on your smartphone as an IoT device that connects to IoT Central.

In this tutorial, you learn how to:

Authorize the REST API.
Create an IoT Central application.
Add a device to your application.
Query and control the device.
Set up data export.
Delete an application.

Prerequisites

To complete the steps in this tutorial, you need:

An active Azure subscription. If you don't have an Azure subscription, create a free account before you begin.
An Android or iOS smartphone on which you're able to install a free app from one of the official app stores.

Azure CLI

You use the Azure CLI to make the REST API calls and to generate the bearer tokens that some of the REST APIs use for authorization.

Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
- If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
- When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
- Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Authorize the REST API

Before you can use the REST API, you must configure the authorization. The REST API calls in this tutorial use one of two authorization types:

A bearer token that authorizes access to https://apps.azureiotcentral.com. You use this bearer token to create the API tokens in the IoT Central application.
Administrator and operator API tokens that authorize access to capabilities in your IoT Central application. You use these tokens for most the API calls in this tutorial. These tokens only authorize access to one specific IoT Central application.

Run the following Azure CLI commands to generate a bearer token that authorizes access to https://apps.azureiotcentral.com:

az account get-access-token --resource https://apps.azureiotcentral.com

Tip

If you started a new instance of your shell, run az login again.

Make a note of the accessToken value, you use it later in the tutorial.

Note

Bearer tokens expire after an hour. If they expire, run the same commands to generate new bearer tokens.

Create a resource group

Use the Azure cli to create a resource group that contains the IoT Central application you create in this tutorial:

az group create --name iot-central-rest-tutorial --location eastus

Create an IoT Central application

Use the following command to generate an IoT Central application with a random name to use in this tutorial:

appName=app-rest-$(date +%s)

az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName

Make a note of the application name, you use it later in this tutorial.

Create the API tokens

Use the following data plane requests to create the application API tokens in your IoT Central application. Some of the requests in this tutorial require an API token with administrator permissions, but the majority can use operator permissions:

To create an operator token called operator-token by using the Azure CLI, run the following command. The role GUID is the ID of the operator role in all IoT Central applications:

appName=<the app name generated previously>
bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/operator-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ae2c9854-393b-4f97-8c42-479d70ce626e"}]}'

Make a note of the operator token the command returns, you use it later in the tutorial. The token looks like SharedAccessSignature sr=2....

To create an admin token called admin-token by using the Azure CLI, run the following command. The role GUID is the ID of the admin role in all IoT Central applications:

$appName=<the app name generated previously>
$bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/admin-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"}]}'

Make a note of the admin token the command returns, you use it later in the tutorial. The token looks like SharedAccessSignature sr=2....

If you want to see these tokens in your IoT central application, open the application and navigate to Security > Permissions > API tokens.

Register a device

You must register a device with IoT Central before it can connect. Use the following requests to register your device in your application and retrieve the device credentials. The first request creates a device with phone-001 as the device ID:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"displayName": "My phone app","simulated": false,"enabled": true}'

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/credentials?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Make a note of the idScope and primaryKey values the command returns, you use them later in the tutorial.

Provision and connect a device

To avoid the need to enter the device credentials manually on your smartphone, you can use a QR code generated by IoT central. The QR code encodes the device ID, ID scope, primary key. To display the QR code:

Open your IoT central application by using the application URL you made a note of previously.
In your IoT Central application, navigate to Devices > My phone app > Connect > QR code. Keep this page open until the device is connected.

Screenshot that shows the QR code you use to connect the device.

To simplify the setup, this article uses the IoT Plug and Play smartphone app as an IoT device. The app sends telemetry collected from the smartphone's sensors, responds to commands invoked from IoT Central, and reports property values to IoT Central.

Install the app on your smartphone from one of the app stores:

To connect the IoT Plug and Play app to your Iot Central application:

Open the IoT PnP app on your smartphone.
On the welcome page, select Scan QR code. Point the smartphone's camera at the QR code. Then wait for a few seconds while the connection is established.
On the telemetry page in the app, you can see the data the app is sending to IoT Central. On the logs page, you can see the device connecting and several initialization messages.

To verify the device is now provisioned, you can use the REST API:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Make a note of the template value the command returns, you use it later in the tutorial.

You can use the REST API to manage device templates in the application. For example, to view the device templates in the application:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Query and control the device

You can use the REST API to query telemetry from your devices. The following request returns the accelerometer data from all devices that share a specific device template ID:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
deviceTemplateId=<the device template Id you made a note of previously>
q1='{"query": "SELECT $id as ID, $ts as timestamp, sensors.accelerometer FROM '
q2=' WHERE WITHIN_WINDOW(P1D) AND sensors.accelerometer <> NULL"}'
query="$q1 $deviceTemplateId $q2"
echo $query

az rest --method post --uri https://$appName.azureiotcentral.com/api/query?api-version=2022-10-31-preview --headers Authorization="$operatorToken" "Content-Type=application/json" --body "$query"

You can use the REST API to read and set device properties. The following request returns all the property values from the Device Info component that the device implements:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/components/device_info/properties?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

You can use the REST API to call device commands. The following request calls a command that switches on your smartphone light on twice for three seconds. For the command to run, your smartphone screen must be on with the IoT Plug and Play app visible:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method post --uri https://$appName.azureiotcentral.com/api/devices/phone-001/commands/lightOn?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"duration": 3, "delay": 1, "pulses": 2}'

Clean up resources

If you've finished with the IoT Central application you used in this tutorial, you can delete it:

appName=<the app name generated previously>

az iot central app delete --name $appName --resource-group iot-central-rest-tutorial

Comhroinn trí