Skip to content

Commit 0794dc6

Browse files
tamarakhadertamarakhader
authored
Merge pull request #194246 from v-krishnag/restorgs
update device groups
2 parents ba4712f + 8823a9d commit 0794dc6

File tree

1 file changed

+155
-37
lines changed

1 file changed

+155
-37
lines changed

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

Lines changed: 155 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -194,43 +194,6 @@ The response to this request looks like the following example:
194194
}
195195
```
196196

197-
### List device groups
198-
199-
Use the following request to retrieve a list of device groups from your application:
200-
201-
```http
202-
GET https://{subdomain}.{baseDomain}/api/deviceGroups?api-version=1.1-preview
203-
```
204-
205-
The response to this request looks like the following example:
206-
207-
```json
208-
{
209-
"value": [
210-
{
211-
"id": "1dbb2610-04f5-47f8-81ca-ba38a24a6cf3",
212-
"displayName": "Thermostat - All devices",
213-
"organizations": [
214-
"seattle"
215-
]
216-
},
217-
{
218-
"id": "b37511ca-1beb-4781-ae09-c2d73c9104bf",
219-
"displayName": "Cascade 500 - All devices",
220-
"organizations": [
221-
"redmond"
222-
]
223-
},
224-
{
225-
"id": "788d08c6-2d11-4372-a994-71f63e108cef",
226-
"displayName": "RS40 Occupancy Sensor - All devices"
227-
}
228-
]
229-
}
230-
```
231-
232-
The organizations field is only used when an application has an organization hierarchy defined. To learn more about organizations, see [Manage IoT Central organizations](howto-edit-device-template.md)
233-
234197
### Use ODATA filters
235198

236199
You can use ODATA filters to filter the results returned by the list devices API.
@@ -430,6 +393,161 @@ The response to this request looks like the following example:
430393
}
431394
```
432395

396+
## Device groups
397+
398+
### Add a device group
399+
400+
Use the following request to create a new device group.
401+
402+
```http
403+
PUT https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=1.2-preview
404+
```
405+
406+
When you create a device group, you define a `filter` that selects the devices to add to the group. A `filter` identifies a device template and any properties to match. The following example creates device group that contains all devices associated with the "dtmi:modelDefinition:dtdlv2" template where the `provisioned` property is true
407+
408+
```json
409+
{
410+
"displayName": "Device group 1",
411+
"description": "Custom device group.",
412+
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
413+
"organizations": [
414+
"seattle"
415+
]
416+
}
417+
```
418+
419+
The request body has some required fields:
420+
421+
* `@displayName`: Display name of the device group.
422+
* `@filter`: Query defining which devices should be in this group.
423+
* `@etag`: ETag used to prevent conflict in device updates.
424+
* `description`: Short summary of device group.
425+
426+
The organizations field is only used when an application has an organization hierarchy defined. To learn more about organizations, see [Manage IoT Central organizations](howto-edit-device-template.md)
427+
428+
The response to this request looks like the following example:
429+
430+
```json
431+
{
432+
"id": "group1",
433+
"displayName": "Device group 1",
434+
"description": "Custom device group.",
435+
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
436+
"organizations": [
437+
"seattle"
438+
]
439+
}
440+
```
441+
442+
### Get a device group
443+
444+
Use the following request to retrieve details of a device group from your application:
445+
446+
```http
447+
GET https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=1.2-preview
448+
```
449+
450+
* deviceGroupId - Unique ID for the device group.
451+
452+
The response to this request looks like the following example:
453+
454+
```json
455+
{
456+
"id": "475cad48-b7ff-4a09-b51e-1a9021385453",
457+
"displayName": "DeviceGroupEntry1",
458+
"description": "This is a default device group containing all the devices for this particular Device Template.",
459+
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
460+
"organizations": [
461+
"seattle"
462+
]
463+
}
464+
```
465+
466+
### Update a device group
467+
468+
```http
469+
PATCH https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=1.2-preview
470+
```
471+
472+
The sample request body looks like the following example which updates the `displayName` of the device group:
473+
474+
```json
475+
{
476+
"displayName": "New group name"
477+
}
478+
479+
```
480+
481+
The response to this request looks like the following example:
482+
483+
```json
484+
{
485+
"id": "group1",
486+
"displayName": "New group name",
487+
"description": "Custom device group.",
488+
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
489+
"organizations": [
490+
"seattle"
491+
]
492+
}
493+
```
494+
495+
### Delete a device group
496+
497+
Use the following request to delete a device group:
498+
499+
```http
500+
DELETE https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=1.2-preview
501+
```
502+
503+
### List device groups
504+
505+
Use the following request to retrieve a list of device groups from your application:
506+
507+
```http
508+
GET https://{subdomain}.{baseDomain}/api/deviceGroups?api-version=1.2-preview
509+
```
510+
511+
The response to this request looks like the following example:
512+
513+
```json
514+
{
515+
"value": [
516+
{
517+
"id": "475cad48-b7ff-4a09-b51e-1a9021385453",
518+
"displayName": "DeviceGroupEntry1",
519+
"description": "This is a default device group containing all the devices for this particular Device Template.",
520+
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
521+
"organizations": [
522+
"seattle"
523+
]
524+
},
525+
{
526+
"id": "c2d5ae1d-2cb7-4f58-bf44-5e816aba0a0e",
527+
"displayName": "DeviceGroupEntry2",
528+
"description": "This is a default device group containing all the devices for this particular Device Template.",
529+
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model1\"",
530+
"organizations": [
531+
"redmond"
532+
]
533+
},
534+
{
535+
"id": "241ad72b-32aa-4216-aabe-91b240582c8d",
536+
"displayName": "DeviceGroupEntry3",
537+
"description": "This is a default device group containing all the devices for this particular Device Template.",
538+
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model2\" AND $simulated = true"
539+
},
540+
{
541+
"id": "group4",
542+
"displayName": "DeviceGroupEntry4",
543+
"description": "This is a default device group containing all the devices for this particular Device Template.",
544+
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model3\""
545+
}
546+
]
547+
}
548+
```
549+
550+
433551
## Next steps
434552

435553
Now that you've learned how to manage devices with the REST API, a suggested next step is to [How to control devices with rest api.](howto-control-devices-with-rest-api.md)

0 commit comments

Comments
 (0)