Skip to content

Commit 248acbd

Browse files
v-krishnagv-krishnag
committed
update device groups
1 parent 1b92a04 commit 248acbd

File tree

1 file changed

+155
-191
lines changed

1 file changed

+155
-191
lines changed

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

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

197-
### List device groups [1.1-preview]
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-
234-
## Device Groups
235-
236-
### Add a device group
237-
238-
Use the following request to create a new device group.
239-
240-
```http
241-
PUT https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=1.2-preview
242-
```
243-
244-
The following example shows a request body that adds a device group.
245-
246-
```json
247-
{
248-
"displayName": "Device group 1",
249-
"description": "Custom device group.",
250-
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
251-
"organizations": [
252-
"seattle"
253-
]
254-
}
255-
```
256-
257-
The request body has some required fields:
258-
259-
* `@displayName`: Display name of the device group.
260-
* `@filter`: Query defining which devices should be in this group.
261-
* `@etag`: ETag used to prevent conflict in device updates.
262-
* `description`: Short summary of device group.
263-
* `organizations` : List of organization IDs of the device group.
264-
265-
The response to this request looks like the following example:
266-
267-
```json
268-
{
269-
"id": "group1",
270-
"displayName": "Device group 1",
271-
"description": "Custom device group.",
272-
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
273-
"organizations": [
274-
"seattle"
275-
]
276-
}
277-
```
278-
279-
### Get a device group
280-
281-
Use the following request to retrieve details of a device group from your application:
282-
283-
```http
284-
GET https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=1.2-preview
285-
```
286-
287-
* deviceGroupId - Unique ID for the device group.
288-
289-
The response to this request looks like the following example:
290-
291-
```json
292-
{
293-
"id": "475cad48-b7ff-4a09-b51e-1a9021385453",
294-
"displayName": "DeviceGroupEntry1",
295-
"description": "This is a default device group containing all the devices for this particular Device Template.",
296-
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
297-
"organizations": [
298-
"seattle"
299-
]
300-
}
301-
```
302-
303-
### Update a device group
304-
305-
```http
306-
PATCH https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=1.2-preview
307-
```
308-
309-
The sample request body looks like the following example which updates the `displayName` of the device group:
310-
311-
```json
312-
{
313-
"displayName": "New group name"
314-
}
315-
316-
```
317-
318-
The response to this request looks like the following example:
319-
320-
```json
321-
{
322-
"id": "group1",
323-
"displayName": "New group name",
324-
"description": "Custom device group.",
325-
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
326-
"organizations": [
327-
"seattle"
328-
]
329-
}
330-
```
331-
332-
### Delete a device group
333-
334-
Use the following request to delete a device group:
335-
336-
```http
337-
DELETE https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=1.2-preview
338-
```
339-
340-
### List device groups
341-
342-
Use the following request to retrieve a list of device groups from your application:
343-
344-
```http
345-
GET https://{subdomain}.{baseDomain}/api/deviceGroups?api-version=1.2-preview
346-
```
347-
348-
The response to this request looks like the following example:
349-
350-
```json
351-
{
352-
"value": [
353-
{
354-
"id": "475cad48-b7ff-4a09-b51e-1a9021385453",
355-
"displayName": "DeviceGroupEntry1",
356-
"description": "This is a default device group containing all the devices for this particular Device Template.",
357-
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
358-
"organizations": [
359-
"seattle"
360-
]
361-
},
362-
{
363-
"id": "c2d5ae1d-2cb7-4f58-bf44-5e816aba0a0e",
364-
"displayName": "DeviceGroupEntry2",
365-
"description": "This is a default device group containing all the devices for this particular Device Template.",
366-
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model1\"",
367-
"organizations": [
368-
"redmond"
369-
]
370-
},
371-
{
372-
"id": "241ad72b-32aa-4216-aabe-91b240582c8d",
373-
"displayName": "DeviceGroupEntry3",
374-
"description": "This is a default device group containing all the devices for this particular Device Template.",
375-
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model2\" AND $simulated = true"
376-
},
377-
{
378-
"id": "group4",
379-
"displayName": "DeviceGroupEntry4",
380-
"description": "This is a default device group containing all the devices for this particular Device Template.",
381-
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:model3\""
382-
}
383-
]
384-
}
385-
```
386-
387-
388197
### Use ODATA filters
389198

390199
You can use ODATA filters to filter the results returned by the list devices API.
@@ -584,6 +393,161 @@ The response to this request looks like the following example:
584393
}
585394
```
586395

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+
587551
## Next steps
588552

589553
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)