Skip to content

Commit b6c93bf

Browse files
committed
add create a new device group in jobs
1 parent 2e7e942 commit b6c93bf

File tree

1 file changed

+47
-4
lines changed

1 file changed

+47
-4
lines changed

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

Lines changed: 47 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -232,15 +232,58 @@ Use the following request to retrieve the details of the devices in a job:
232232
PUT https://{your app subdomain}.azureiotcentral.com/api/jobs/job-006?api-version=1.2-preview
233233
```
234234

235-
The following request body requires the `group` of the device group that the job applies to. You can use the [get list of device groups](howto-manage-devices-with-rest-api.md#List-device-groups) REST API to get a list of the device groups in your application and use the required `group` from the response to create a new job.
235+
The request body requires the `group` of the device group that the job applies to.
236+
237+
Use the following request to create a new device group.
238+
239+
```http
240+
PUT https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=1.2-preview
241+
```
242+
243+
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
244+
245+
```json
246+
{
247+
"displayName": "Device group 1",
248+
"description": "Custom device group.",
249+
"filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
250+
"organizations": [
251+
"seattle"
252+
]
253+
}
254+
```
255+
256+
The request body has some required fields:
257+
258+
- `@displayName`: Display name of the device group.
259+
- `@filter`: Query defining which devices should be in this group.
260+
- `@etag`: ETag used to prevent conflict in device updates.
261+
- `description`: Short summary of device group.
262+
263+
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)
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+
You can now use the `id` value from the response to create a new job.
236280

237-
You can also [create a new device group](howto-manage-devices-with-rest-api.md#add-a-device-group) and use the value of the `ID` from the device group you created.
238281

239282
```json
240283
{
241284
"displayName": "Set target temperature",
242285
"description": "Set target temperature device property",
243-
"group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
286+
"group": "group1",
244287
"batch": {
245288
"type": "percentage",
246289
"value": 25
@@ -268,7 +311,7 @@ The response to this request looks like the following example. The initial job s
268311
"id": "job-006",
269312
"displayName": "Set target temperature",
270313
"description": "Set target temperature device property",
271-
"group": "833d7a7d-8f99-4e04-9e56-745806bdba6e",
314+
"group": "group1",
272315
"batch": {
273316
"type": "percentage",
274317
"value": 25

0 commit comments

Comments
 (0)