Query - Get Twins
Query an IoT Hub to retrieve information regarding device twins using a SQL-like language. See https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-query-language for more information. Pagination is supported. This returns information about device twins only.
POST https://fully-qualified-iothubname.azure-devices.net/devices/query?api-version=2021-04-12URI Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
|
api-version
|
query | True |
string |
Version of the Api. |
Request Header
| Name | Required | Type | Description |
|---|---|---|---|
| x-ms-continuation |
string |
The continuation token used to get the next page of results. |
|
| x-ms-max-item-count |
string |
The maximum number of items returned per page. The service may use a different value if the value specified is not acceptable. |
Request Body
| Name | Type | Description |
|---|---|---|
| query |
string |
The query string. |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK |
Twin[] |
OK. Headers
|
Definitions
| Name | Description |
|---|---|
|
Device |
The status of capabilities enabled on the device. |
|
Query |
The Json query request. |
| Twin |
The state information for a device or module. This is implicitly created and deleted when the corresponding device/ module identity is created or deleted in the IoT Hub. |
|
Twin |
The desired and reported properties of the twin. The maximum depth of the object is 10. |
| X509Thumbprint |
DeviceCapabilities
The status of capabilities enabled on the device.
| Name | Type | Description |
|---|---|---|
| iotEdge |
boolean |
The property that determines if the device is an edge device or not. |
QuerySpecification
The Json query request.
| Name | Type | Description |
|---|---|---|
| query |
string |
The query string. |
Twin
The state information for a device or module. This is implicitly created and deleted when the corresponding device/ module identity is created or deleted in the IoT Hub.
| Name | Type | Description |
|---|---|---|
| authenticationType |
enum:
|
The authentication type used by the device. |
| capabilities |
The status of capabilities enabled on the device. |
|
| cloudToDeviceMessageCount |
integer |
The number of cloud-to-device messages sent. |
| connectionState |
enum:
|
The connection state of the device. |
| deviceEtag |
string |
The string representing a ETag for the device, as per RFC7232. |
| deviceId |
string |
The unique identifier of the device in the identity registry of the IoT Hub. It is a case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars, and the following special characters {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
| deviceScope |
string |
The scope of the device. |
| etag |
string |
The string representing a ETag for the device twin, as per RFC7232. |
| lastActivityTime |
string |
The date and time when the device last connected or received or sent a message. The date and time is sepecified in ISO8601 datetime format in UTC, for example, 2015-01-28T16:24:48.789Z. This value is not updated if the device uses the HTTP/1 protocol to perform messaging operations. |
| moduleId |
string |
The unique identifier of the module in the identity registry of the IoT Hub. It is a case-sensitive string (up to 128 char long) of ASCII 7-bit alphanumeric chars, and the following special characters {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. |
| parentScopes |
string[] |
The scopes of the upper level edge devices if applicable. Only available for edge devices. |
| properties |
The desired and reported properties of the twin. |
|
| status |
enum:
|
The enabled status of the device. If disabled, the device cannot connect to the service. |
| statusReason |
string |
The reason for the current status of the device, if any. |
| statusUpdateTime |
string |
The date and time when the status of the device was last updated. |
| tags |
object |
The collection of key-value pairs read and written by the solution back end. They are not visible to device apps. They keys are UTF-8 encoded, case-sensitive and up-to 1KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), '.', '$' and space. The values are JSON objects, up-to 4KB in length. |
| version |
integer |
The version for the device twin including tags and desired properties |
| x509Thumbprint |
The X509 thumbprint of the device. |
TwinProperties
The desired and reported properties of the twin. The maximum depth of the object is 10.
| Name | Type | Description |
|---|---|---|
| desired |
object |
The collection of desired property key-value pairs. The keys are UTF-8 encoded, case-sensitive and up-to 1KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), '.', '$' and space. The desired porperty values are JSON objects, up-to 4KB in length. |
| reported |
object |
The collection of reported property key-value pairs. The keys are UTF-8 encoded, case-sensitive and up-to 1KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), '.', '$' and space. The reported property values are JSON objects, up-to 4KB in length. |
X509Thumbprint
| Name | Type | Description |
|---|---|---|
| primaryThumbprint |
string |
The X509 client certificate primary thumbprint. |
| secondaryThumbprint |
string |
The X509 client certificate secondary thumbprint. |