Device Groups - Create

Service:

IoT Central

API Version:

2022-07-31

Create or update a device group.

PUT https://{subdomain}.{baseDomain}/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

URI Parameters

Name	In	Required	Type	Description
baseDomain	path	True	string	The base domain for all Azure IoT Central service requests.
deviceGroupId	path	True	string maxLength: 255 pattern: ^[a-zA-Z0-9_-]*$	Unique ID for the device group.
subdomain	path	True	string	The application subdomain.
api-version	query	True	string	The version of the API being called.

Request Body

Name	Required	Type	Description
displayName	True	string	Display name of the device group.
filter	True	string	Query defining which devices should be in this group, Query Language Reference.
description		string	Short summary of device group.
etag		string	ETag used to prevent conflict in device group updates.
organizations		string[]	List of organization IDs of the device group, only one organization is supported today, multiple organizations will be supported soon.

Responses

Name	Type	Description
200 OK	DeviceGroup	Success
Other Status Codes	Error	An error response received from the IoT Central Service. Headers x-ms-error-code: string

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Create device group

Sample request

HTTP

PUT https://appsubdomain.azureiotcentral.com/api/deviceGroups/group1?api-version=2022-07-31

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Sample response

Status code:

200

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Definitions

Name	Description
DeviceGroup	The device group definition.
Error	The response error definition.
ErrorDetails	The detail information of the error.

DeviceGroup

Object

The device group definition.

Name	Type	Description
description	string	Short summary of device group.
displayName	string	Display name of the device group.
etag	string	ETag used to prevent conflict in device group updates.
filter	string	Query defining which devices should be in this group, Query Language Reference.
id	string	Unique ID of the device group.
organizations	string[]	List of organization IDs of the device group, only one organization is supported today, multiple organizations will be supported soon.

Error

Object

The response error definition.

Name	Type	Description
error	ErrorDetails	Error details for current request.

ErrorDetails

Object

The detail information of the error.

Name	Type	Description
code	string	Error code.
message	string	Error message details.
requestId	string	Correlation Id for current request.
time	string (date-time-rfc1123)	The time that error request failed.