Skip to content

Commit 0c6a307

Browse files
dominicbettsdominicbetts
committed
Fix ODATA sections
1 parent c0b63ea commit 0c6a307

File tree

2 files changed

+81
-68
lines changed

2 files changed

+81
-68
lines changed

‎articles/iot-central/core/howto-manage-device-templates-with-rest-api.md

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ The IoT Central REST API lets you:
3737
* Get a list of the device templates in the application
3838
* Get a device template by ID
3939
* Delete a device template in your application
40+
* Filter the list of device templates in the application
4041

4142
## Add a device template
4243

@@ -984,16 +985,16 @@ The response to this request looks like the following example:
984985

985986
### Use ODATA filters
986987

987-
You can use ODATA filters to filter the results returned by the list device templates API.
988+
In the preview version of the API (`api-version=2022-10-31-preview`), you can use ODATA filters to filter and sort the results returned by the list device templates API.
988989

989-
### $top
990+
### maxpagesize
990991

991-
Use the **$top** filter to set the result size. The maximum returned result size is 100, and the default size is 25.
992+
Use the **maxpagesize** filter to set the result size. The maximum returned result size is 100, and the default size is 25.
992993

993994
Use the following request to retrieve the top 10 device templates from your application:
994995

995996
```http
996-
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-07-31&$top=10
997+
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&maxpagesize=10
997998
```
998999

9991000
The response to this request looks like the following example:
@@ -1045,17 +1046,17 @@ The response to this request looks like the following example:
10451046
"dtmi:dtdl:context;2"
10461047
]
10471048
},
1048-
...
1049+
// ...
10491050
],
1050-
"nextLink": "https://custom-12qmyn6sm0x.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31&%24top=1&%24skiptoken=%7B%22token%22%3A%22%2BRID%3A%7EJWYqAKZQKp20qCoAAAAACA%3D%3D%23RT%3A1%23TRC%3A1%23ISV%3A2%23IEO%3A65551%23QCF%3A4%22%2C%22range%22%3A%7B%22min%22%3A%2205C1DFFFFFFFFC%22%2C%22max%22%3A%22FF%22%7D%7D"
1051+
"nextLink": "https://{your app subdomain}.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31&%24top=1&%24skiptoken=%7B%22token%22%3A%22%2BRID%3A%7EJWYqAKZQKp20qCoAAAAACA%3D%3D%23RT%3A1%23TRC%3A1%23ISV%3A2%23IEO%3A65551%23QCF%3A4%22%2C%22range%22%3A%7B%22min%22%3A%2205C1DFFFFFFFFC%22%2C%22max%22%3A%22FF%22%7D%7D"
10511052
}
10521053
```
10531054

10541055
The response includes a **nextLink** value that you can use to retrieve the next page of results.
10551056

1056-
### $filter
1057+
### filter
10571058

1058-
Use **$filter** to create expressions that filter the list of device templates. The following table shows the comparison operators you can use:
1059+
Use **filter** to create expressions that filter the list of device templates. The following table shows the comparison operators you can use:
10591060

10601061
| Comparison Operator | Symbol | Example |
10611062
| -------------------- | ------ | ------------------------------ |
@@ -1066,34 +1067,33 @@ Use **$filter** to create expressions that filter the list of device templates.
10661067
| Greater than or equals | ge | `displayName ge 'template A'` |
10671068
| Greater than | gt | `displayName gt 'template B'` |
10681069

1069-
The following table shows the logic operators you can use in *$filter* expressions:
1070+
The following table shows the logic operators you can use in *filter* expressions:
10701071

10711072
| Logic Operator | Symbol | Example |
10721073
| -------------- | ------ | ------------------------------------------------------------------------------------ |
10731074
| AND | and | `'@id' eq 'dtmi:example:test;1' and capabilityModelId eq 'dtmi:example:test:model1;1'` |
10741075
| OR | or | `'@id' eq 'dtmi:example:test;1' or displayName ge 'template'` |
10751076

1076-
Currently, *$filter* works with the following device template fields:
1077+
Currently, *filter* works with the following device template fields:
10771078

10781079
| FieldName | Type | Description |
10791080
| ----------------- | ------ | ----------------------------------- |
10801081
| `@id` | string | Device template ID |
10811082
| `displayName` | string | Device template display name |
10821083
| `capabilityModelId` | string | Device template capability model ID |
10831084

1084-
**$filter supported functions:**
1085+
**filter supported functions:**
10851086

10861087
Currently, the only supported filter function for device template lists is the `contains` function:
10871088

10881089
```txt
1089-
$filter=contains(displayName, 'template1')
1090-
$filter=contains(displayName, 'template1) eq false
1090+
filter=contains(displayName, 'template1')
10911091
```
10921092

10931093
The following example shows how to retrieve all the device templates where the display name contains the string `thermostat`:
10941094

10951095
```http
1096-
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-07-31&$filter=contains(displayName, 'thermostat')
1096+
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')
10971097
```
10981098

10991099
The response to this request looks like the following example:
@@ -1171,19 +1171,19 @@ The response to this request looks like the following example:
11711171
}
11721172
```
11731173

1174-
### $orderby
1174+
### orderby
11751175

1176-
Use **$orderby** to sort the results. Currently, **$orderby** only lets you sort on **displayName**. By default, **$orderby** sorts in ascending order. Use **desc** to sort in descending order, for example:
1176+
Use **orderby** to sort the results. Currently, **orderby** only lets you sort on **displayName**. By default, **orderby** sorts in ascending order. Use **desc** to sort in descending order, for example:
11771177

11781178
```txt
1179-
$orderby=displayName
1180-
$orderby=displayName desc
1179+
orderby=displayName
1180+
orderby=displayName desc
11811181
```
11821182

11831183
The following example shows how to retrieve all the device templates where the result is sorted by `displayName`:
11841184

11851185
```http
1186-
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-07-31&$orderby=displayName
1186+
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&orderby=displayName
11871187
```
11881188

11891189
The response to this request looks like the following example:
@@ -1266,7 +1266,7 @@ You can also combine two or more filters.
12661266
The following example shows how to retrieve the top two device templates where the display name contains the string `thermostat`.
12671267

12681268
```http
1269-
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-07-31&$filter=contains(displayName, 'thermostat')&$top=2
1269+
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')&maxpagesize=2
12701270
```
12711271

12721272
The response to this request looks like the following example:

‎articles/iot-central/core/howto-manage-devices-with-rest-api.md

Lines changed: 61 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: How to use the IoT Central REST API to manage devices
33
description: How to use the IoT Central REST API to add devices in an application
44
author: dominicbetts
55
ms.author: dobett
6-
ms.date: 11/30/2022
6+
ms.date: 03/23/2023
77
ms.topic: how-to
88
ms.service: iot-central
99
services: iot-central
@@ -32,6 +32,7 @@ The IoT Central REST API lets you:
3232
* Get a device by ID
3333
* Get a device credential
3434
* Delete a device in your application
35+
* Filter the list of devices in the application
3536

3637
### Add a device
3738

@@ -203,16 +204,16 @@ If you're adding an IoT Edge device, you can use the API to assign an IoT Edge d
203204

204205
### Use ODATA filters
205206

206-
You can use ODATA filters to filter the results returned by the list devices API.
207+
In the preview version of the API (`api-version=2022-10-31-preview`), you can use ODATA filters to filter and sort the results returned by the list devices API.
207208

208-
### $top
209+
### maxpagesize
209210

210-
Use the **$top** to set the result size, the maximum returned result size is 100, the default size is 25.
211+
Use the **maxpagesize** to set the result size, the maximum returned result size is 100, the default size is 25.
211212

212213
Use the following request to retrieve a top 10 device from your application:
213214

214215
```http
215-
GET https://{your app subdomain}/api/devices?api-version=2022-07-31&$top=10
216+
GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&maxpagesize=10
216217
```
217218

218219
The response to this request looks like the following example:
@@ -240,33 +241,33 @@ The response to this request looks like the following example:
240241
},
241242
...
242243
],
243-
"nextLink": "https://custom-12qmyn6sm0x.azureiotcentral.com/api/devices?api-version=2022-07-31&%24top=1&%24skiptoken=%257B%2522token%2522%253A%2522%252BRID%253A%7EJWYqAOis7THQbBQAAAAAAg%253D%253D%2523RT%253A1%2523TRC%253A1%2523ISV%253A2%2523IEO%253A65551%2523QCF%253A4%2522%252C%2522range%2522%253A%257B%2522min%2522%253A%2522%2522%252C%2522max%2522%253A%252205C1D7F7591D44%2522%257D%257D"
244+
"nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-07-31&%24top=1&%24skiptoken=%257B%2522token%2522%253A%2522%252BRID%253A%7EJWYqAOis7THQbBQAAAAAAg%253D%253D%2523RT%253A1%2523TRC%253A1%2523ISV%253A2%2523IEO%253A65551%2523QCF%253A4%2522%252C%2522range%2522%253A%257B%2522min%2522%253A%2522%2522%252C%2522max%2522%253A%252205C1D7F7591D44%2522%257D%257D"
244245
}
245246
```
246247

247248
The response includes a **nextLink** value that you can use to retrieve the next page of results.
248249

249-
### $filter
250+
### filter
250251

251-
Use **$filter** to create expressions that filter the list of devices. The following table shows the comparison operators you can use:
252+
Use **filter** to create expressions that filter the list of devices. The following table shows the comparison operators you can use:
252253

253-
| Comparison Operator | Symbol | Example |
254-
| -------------------- | ------ | --------------------------------------- |
255-
| Equals | eq | `id eq 'device1' and scopes eq 'redmond'` |
256-
| Not Equals | ne | `Enabled ne true` |
257-
| Less than or equals | le | `contains(displayName, 'device1') le -1` |
258-
| Less than | lt | `contains(displayName, 'device1') lt 0` |
259-
| Greater than or equals | ge | `contains(displayName, 'device1') ge 0` |
260-
| Greater than | gt | `contains(displayName, 'device1') gt 0` |
254+
| Comparison Operator | Symbol | Example |
255+
|------------------------|--------|-------------------------------------------|
256+
| Equals | eq | `id eq 'device1' and scopes eq 'redmond'` |
257+
| Not Equals | ne | `Enabled ne true` |
258+
| Less than or equals | le | `id le '26whl7mure6'` |
259+
| Less than | lt | `id lt '26whl7mure6'` |
260+
| Greater than or equals | ge | `id ge '26whl7mure6'` |
261+
| Greater than | gt | `id gt '26whl7mure6'` |
261262

262-
The following table shows the logic operators you can use in *$filter* expressions:
263+
The following table shows the logic operators you can use in *filter* expressions:
263264

264265
| Logic Operator | Symbol | Example |
265266
| -------------- | ------ | ------------------------------------- |
266267
| AND | and | `id eq 'device1' and enabled eq true` |
267268
| OR | or | `id eq 'device1' or simulated eq false` |
268269

269-
Currently, *$filter* works with the following device fields:
270+
Currently, *filter* works with the following device fields:
270271

271272
| FieldName | Type | Description |
272273
| ----------- | ------- | ------------------------- |
@@ -278,18 +279,18 @@ Currently, *$filter* works with the following device fields:
278279
| `template` | string | Device template ID |
279280
| `scopes` | string | organization ID |
280281

281-
**$filter supported functions:**
282+
**filter supported functions:**
282283

283284
Currently, the only supported filter function for device lists is the `contains` function:
284285

285286
```http
286-
$filter=contains(displayName, 'device1') ge 0
287+
filter=contains(displayName, 'device1')
287288
```
288289

289290
The following example shows how to retrieve all the devices where the display name contains the string `thermostat`:
290291

291292
```http
292-
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-07-31&$filter=contains(displayName, 'thermostat')
293+
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'thermostat')
293294
```
294295

295296
The response to this request looks like the following example:
@@ -319,19 +320,19 @@ The response to this request looks like the following example:
319320
}
320321
```
321322

322-
### $orderby
323+
### orderby
323324

324-
Use **$orderby** to sort the results. Currently, **$orderby** only lets you sort on **displayName**. By default, **$orderby** sorts in ascending order. Use **desc** to sort in descending order, for example:
325+
Use **orderby** to sort the results. Currently, **orderby** only lets you sort on **displayName**. By default, **orderby** sorts in ascending order. Use **desc** to sort in descending order, for example:
325326

326327
```http
327-
$orderby=displayName
328-
$orderby=displayName desc
328+
orderby=displayName
329+
orderby=displayName desc
329330
```
330331

331332
The following example shows how to retrieve all the device templates where the result is sorted by `displayName` :
332333

333334
```http
334-
GET https://{your app subdomain}/api/devices?api-version=2022-07-31&$orderby=displayName
335+
GET https://{your app subdomain}/api/devices?api-version=2022-10-31-preview&orderby=displayName
335336
```
336337

337338
The response to this request looks like the following example:
@@ -363,41 +364,53 @@ The response to this request looks like the following example:
363364

364365
You can also combine two or more filters.
365366

366-
The following example shows how to retrieve the top two devices where the display name contains the string `thermostat`.
367+
The following example shows how to retrieve the top three devices where the display name contains the string `Thermostat`.
367368

368369
```http
369-
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-07-31&$filter=contains(displayName, 'thermostat')&$top=2
370+
GET https://{your app subdomain}/api/deviceTemplates?api-version=2022-10-31-preview&filter=contains(displayName, 'Thermostat')&maxpagesize=3
370371
```
371372

372373
The response to this request looks like the following example:
373374

374375
```json
375376
{
376-
"value": [
377-
{
378-
"id": "5jcwskdwbm",
379-
"etag": "eyJoZWFkZXIiOiJcIjI0MDBlMDdjLTAwMDAtMDMwMC0wMDAwLTYxYjgxYmVlMDAwMFwiIn0",
380-
"displayName": "thermostat1",
381-
"simulated": false,
382-
"provisioned": false,
383-
"template": "dtmi:contoso:Thermostat;1",
384-
"enabled": true
385-
},
386-
{
387-
"id": "ccc",
388-
"etag": "eyJoZWFkZXIiOiJcIjI0MDAwYjdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDJjMDAwMFwiIn0",
389-
"displayName": "thermostat2",
390-
"simulated": true,
391-
"provisioned": true,
392-
"template": "dtmi:contoso:Thermostat;1",
393-
"enabled": true
394-
}
395-
]
377+
"value": [
378+
{
379+
"id": "1fpwlahp0zp",
380+
"displayName": "Thermostat - 1fpwlahp0zp",
381+
"simulated": false,
382+
"provisioned": false,
383+
"etag": "eyJwZ0luc3RhbmNlIjoiYTRjZGQyMjQtZjIxMi00MTI4LTkyMTMtZjcwMTBlZDhkOWQ0In0=",
384+
"template": "dtmi:contoso:mythermostattemplate;1",
385+
"enabled": true
386+
},
387+
{
388+
"id": "1yg0zvpz9un",
389+
"displayName": "Thermostat - 1yg0zvpz9un",
390+
"simulated": false,
391+
"provisioned": false,
392+
"etag": "eyJwZ0luc3RhbmNlIjoiZGQ1YTY4MDUtYzQxNS00ZTMxLTgxM2ItNTRiYjdiYWQ1MWQ2In0=",
393+
"template": "dtmi:contoso:mythermostattemplate;1",
394+
"enabled": true
395+
},
396+
{
397+
"id": "20cp9l96znn",
398+
"displayName": "Thermostat - 20cp9l96znn",
399+
"simulated": false,
400+
"provisioned": false,
401+
"etag": "eyJwZ0luc3RhbmNlIjoiNGUzNWM4OTItNDBmZi00OTcyLWExYjUtM2I4ZjU5NGZkODBmIn0=",
402+
"template": "dtmi:contoso:mythermostattemplate;1",
403+
"enabled": true
404+
}
405+
],
406+
"nextLink": "https://{your app subdomain}.azureiotcentral.com/api/devices?api-version=2022-10-31-preview&filter=contains%28displayName%2C+%27Thermostat%27%29&maxpagesize=3&$skiptoken=aHR0cHM6Ly9pb3RjLXByb2QtbG4taW5ma3YteWRtLnZhdWx0LmF6dXJlLm5ldC9zZWNyZXRzL2FwaS1lbmMta2V5LzY0MzZkOTY2ZWRjMjRmMDQ5YWM1NmYzMzFhYzIyZjZi%3AgWMDkfdpzBF0eYiYCGRdGQ%3D%3D%3ATVTgi5YVv%2FBfCd7Oos6ayrCIy9CaSUVu2ULktGQoHZDlaN7uPUa1OIuW0MCqT3spVXlSRQ9wgNFXsvb6mXMT3WWapcDB4QPynkI%2FE1Z8k7s3OWiBW3EQpdtit3JTCbj8qRNFkA%3D%3D%3Aq63Js0HL7OCq%2BkTQ19veqA%3D%3D"
396407
}
397408
```
398409

399410
## Device groups
400411

412+
You can create device groups in an IoT Central application to monitor aggregate data, to use with jobs, and to manage access. Device groups are defined by a filter that selects the devices to add to the group. You can create device groups in the IoT Central portal or by using the API.
413+
401414
### Add a device group
402415

403416
Use the following request to create a new device group.

0 commit comments

Comments
 (0)