You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -3,7 +3,7 @@ title: Tutorial - Use the REST API to manage an application
3
3
description: In this tutorial you use the REST API to create and manage an IoT Central application, add a device, and configure data export.
4
4
author: dominicbetts
5
5
ms.author: dobett
6
-
ms.date: 03/04/2024
6
+
ms.date: 08/20/2024
7
7
ms.topic: tutorial
8
8
ms.service: iot-central
9
9
ms.custom: devx-track-azurecli
@@ -29,106 +29,99 @@ In this tutorial, you learn how to:
29
29
30
30
To complete the steps in this tutorial, you need:
31
31
32
-
* An active Azure subscription. If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
32
+
- An active Azure subscription. If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
33
33
34
-
* An Android or iOS smartphone on which you're able to install a free app from one of the official app stores.
34
+
- An Android or iOS smartphone on which you're able to install a free app from one of the official app stores.
35
35
36
36
### Azure CLI
37
37
38
-
You use the Azure CLI to generate the bearer tokens that some of the REST APIs use for authorization.
38
+
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.
In this tutorial, you use [Postman](https://www.postman.com/downloads/) to make the REST API calls. If you prefer not to download and install Postman, you can use the online version. You can complete all the steps in the tutorial by using the free version of Postman.
45
-
46
-
The tutorial uses a predefined Postman collection that includes some scripts to help you complete the steps.
42
+
## Authorize the REST API
47
43
48
-
## Import the Postman collection
44
+
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:
49
45
50
-
To import the collection, open Postman and select **Import**. In the **Import** dialog, select **Link** and paste in the following [URL](https://raw.githubusercontent.com/Azure-Samples/iot-central-docs-samples/main/postman-collection/IoT%20Central%20REST%20tutorial.postman_collection.json), select **Continue**.
46
+
- 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.
47
+
- 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.
51
48
52
-
Your workspace now contains the **IoT Central REST tutorial** collection. This collection includes all the APIs you use in the tutorial.
49
+
Run the following Azure CLI commands to generate a bearer token that authorizes access to `https://apps.azureiotcentral.com`:
53
50
54
-
The collection uses variables to parameterize the REST API calls. To see the variables, select the `...` next to **IoT Central REST tutorial** and select **Edit**. Then select **Variables**. Many of the variables are either set automatically as you make the API calls or have preset values.
51
+
```azurecli
52
+
az account get-access-token --resource https://apps.azureiotcentral.com
53
+
```
55
54
56
-
## Authorize the REST API
55
+
> [!TIP]
56
+
> If you started a new instance of your shell, run `az login` again.
57
57
58
-
Before you can use the REST API, you must configure the authorization. The REST API calls in this tutorial use one of three authorization types:
58
+
Make a note of the `accessToken` value, you use it later in the tutorial.
59
59
60
-
* A bearer token that authorizes access to `https://management.azure.com`. You use this bearer token when you create and delete and IoT Central application. An IoT Central application is an Azure resource.
61
-
* 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.
62
-
* 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.
60
+
> [!NOTE]
61
+
> Bearer tokens expire after an hour. If they expire, run the same commands to generate new bearer tokens.
63
62
64
-
Assign values to the following variables in the Postman collection:
63
+
## Create a resource group
65
64
66
-
***bearerToken**: Run the following Azure CLI commands to generate a bearer token that authorizes access to `https://management.azure.com`:
65
+
Use the Azure cli to create a resource group that contains the IoT Central application you create in this tutorial:
67
66
68
-
```azurecli
69
-
az login
70
-
az account get-access-token --resource https://management.azure.com
71
-
```
67
+
```azurecli
68
+
az group create --name iot-central-rest-tutorial --location eastus
69
+
```
72
70
73
-
> [!TIP]
74
-
> You may need to run `az login` even if you're using the Cloud Shell.
71
+
## Create an IoT Central application
75
72
76
-
Copy the `accessToken` value into the **Current value** column for **bearerToken** in the collection variables.
73
+
Use the following command to generate an IoT Central application with a random name to use in this tutorial:
77
74
78
-
* **bearerTokenApp**: Run the following Azure CLI commands to generate a bearer token that authorizes access to `https://apps.azureiotcentral.com`:
75
+
```azurecli
76
+
appName=app-rest-$(date +%s)
79
77
80
-
```azurecli
81
-
az account get-access-token --resource https://apps.azureiotcentral.com
82
-
```
78
+
az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName
79
+
```
83
80
84
-
> [!TIP]
85
-
> If you started a new instance of your shell, run `az login` again.
81
+
Make a note of the application name, you use it later in this tutorial.
86
82
87
-
Copy the `accessToken` value into the **Current value** column for **bearerTokenApp** in the collection variables.
83
+
## Create the API tokens
88
84
89
-
* **subscriptionId**: Your subscription ID was included in the output from the two previous commands. Copy the `subscription` value into the **Current value** column for **subscriptionId** in the collection variables.
85
+
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:
90
86
91
-
:::image type="content" source="media/tutorial-use-rest-api/postman-variables.png" alt-text="Screenshot that shows the variables set manually in the Postman collection.":::
87
+
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:
92
88
93
-
Be sure to save the changes to the Postman collection.
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"}]}'
94
+
```
97
95
98
-
## Create an application
96
+
Make a note of the operator token the command returns, you use it later in the tutorial. The token looks like `SharedAccessSignature sr=2...`.
99
97
100
-
Use the control plane requests to create and manage IoT central applications. Use the following **PUT** request to create the application that you use in this tutorial. The request uses a bearer token to authorize and generates a random application name.
98
+
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:
101
99
102
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **Create an IoT central application** request.
103
-
1. Select **Send**.
104
-
1. Check the request succeeds. If it fails, verify that you entered the **bearerToken** and **subscriptionId** variable values in the Postman collection.
105
-
1. Select **Visualize** to see the URL of your new IoT Central application. Make a note of this URL, you need it later in this tutorial.
:::image type="content" source="media/tutorial-use-rest-api/visualize-tab.png" alt-text="Screenshot that shows the Visualize tab with the application URL in Postman.":::
104
+
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"}]}'
105
+
```
108
106
109
-
## Create the API tokens
110
-
111
-
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:
112
-
113
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **Create an operator token** request.
114
-
1. Select **Send**.
115
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **Create an admin token** request.
116
-
1. Select **Send**.
107
+
Make a note of the admin token the command returns, you use it later in the tutorial. The token looks like `SharedAccessSignature sr=2...`.
117
108
118
109
If you want to see these tokens in your IoT central application, open the application and navigate to **Security > Permissions > API tokens**.
119
110
120
-
> [!NOTE]
121
-
> A script in Postman automatically adds these API tokens to the list of collection variables for you.
122
-
123
111
## Register a device
124
112
125
113
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:
126
114
127
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **Add a device** request.
128
-
1. Select **Send**. In the response, notice that the device isn't provisioned.
129
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **Get device credentials** request.
130
-
1. Select **Send**.
131
-
1. The **Visualize** tab shows the **ID Scope** and **Primary key** values that the device needs to able to connect.
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}'
120
+
121
+
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"
122
+
```
123
+
124
+
Make a note of the `idScope` and `primaryKey` values the command returns, you use them later in the tutorial.
132
125
133
126
## Provision and connect a device
134
127
@@ -153,78 +146,64 @@ To connect the **IoT Plug and Play** app to your Iot Central application:
153
146
154
147
To verify the device is now provisioned, you can use the REST API:
155
148
156
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **Get a device** request.
157
-
1. Select **Send**. In the response, notice that the device is now provisioned. IoT Central also assigned a device template to the device based on the model ID sent by the device.
158
-
159
-
You can use the REST API to manage device templates in the application. For example, to view the device templates in the application:
160
-
161
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **List device templates** request.
162
-
1. Select **Send**.
163
-
164
-
## Query and control the device
165
-
166
-
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:
167
-
168
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **Run a query** request.
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:
153
+
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"
154
+
```
172
155
173
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **Get properties from a component** request.
174
-
1. Select **Send**.
175
-
176
-
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:
156
+
Make a note of the `template` value the command returns, you use it later in the tutorial.
177
157
178
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **Call command** request.
179
-
1. Select **Send**.
158
+
You can use the REST API to manage device templates in the application. For example, to view the device templates in the application:
You can use the REST API to configure and manage your IoT Central application. The following steps show you how to configure data export to send telemetry values to a webhook. To simplify the setup, this article uses a **RequestBin** webhook as the destination. **RequestBin** is a non-Microsoft service.
164
+
az rest --method get --uri https://$appName.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"
165
+
```
184
166
185
-
To create your test endpoint for the data export destination:
167
+
## Query and control the device
186
168
187
-
1. Navigate to [RequestBin](https://requestbin.com/).
188
-
1. Select **Create a RequestBin**.
189
-
1. Sign in with one of the available methods.
190
-
1. Copy the URL of your RequestBin endpoint.
191
-
1. In Postman, open the **IoT Central REST tutorial** collection and navigate to the collection variables.
192
-
1. Paste the URL of your RequestBin endpoint into the **Current value** column for **webHookURL** in the collection variables.
193
-
1. Save the changes.
169
+
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:
194
170
195
-
To configure the export destination in your IoT Central application by using the REST API:
deviceTemplateId=<the device template Id you made a note of previously>
175
+
q1='{"query": "SELECT $id as ID, $ts as timestamp, sensors.accelerometer FROM '
176
+
q2=' WHERE WITHIN_WINDOW(P1D) AND sensors.accelerometer <> NULL"}'
177
+
query="$q1 $deviceTemplateId $q2"
178
+
echo $query
196
179
197
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **Create a webhook export destination** request.
198
-
1. Select **Send**.
180
+
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"
181
+
```
199
182
200
-
To configure the export definition in your IoT Central application by using the REST API:
183
+
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:
201
184
202
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **Create a telemetry export definition** request.
203
-
1. Select **Send**. Notice that the status is **Not started**.
It might take a couple of minutes for the export to start. To check the status of the export by using the REST API:
189
+
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"
190
+
```
206
191
207
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **Get an export by ID** request.
208
-
1. Select **Send**. When the status is **healthy**, IoT Central is sending telemetry to your webhook.
192
+
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:
209
193
210
-
The app on your smartphone doesn't send telemetry unless the screen is on and the **IoT Plug and Play** app is visible.
When your smartphone app is sending telemetry, navigate to your RequestBin to view the exported telemetry.
198
+
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}'
199
+
```
213
200
214
201
## Clean up resources
215
202
216
-
If you've finished with the IoT Central application you used in this tutorial, you can use the REST API to delete it:
217
-
218
-
1. In Postman, open the **IoT Central REST tutorial** collection, and select the **Delete an IoT central application** request.
219
-
1. Select **Send**.
220
-
221
-
> [!TIP]
222
-
> This request uses a bearer token that you generated at the start of the tutorial. Bearer tokens expire after hour. You may need to generate a new bearer token that authorizes access to `https://apps.azureiotcentral.com`.
223
-
224
-
## Next steps
203
+
If you've finished with the IoT Central application you used in this tutorial, you can delete it:
225
204
226
-
<!-- TODO: Fix this -->
227
-
If you'd prefer to continue through the set of IoT Central tutorials and learn more about building an IoT Central solution, see:
205
+
```azurecli
206
+
appName=<the app name generated previously>
228
207
229
-
> [!div class="nextstepaction"]
230
-
> [Create a gateway device template](./tutorial-define-gateway-device-type.md)
208
+
az iot central app delete --name $appName --resource-group iot-central-rest-tutorial
0 commit comments