You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -31,70 +31,70 @@ The IoT Hub identity registry exposes the following operations:
31
31
* Update identity
32
32
* Retrieve identity by ID
33
33
* Delete identity
34
-
* List up to 1000 identities
34
+
* List up to 1,000 identities
35
35
* Export identities to Azure blob storage
36
36
* Import identities from Azure blob storage
37
37
38
-
All these operations can use optimistic concurrency, as specified in [RFC7232](https://tools.ietf.org/html/rfc7232).
38
+
All these operations can use optimistic concurrency, as specified in [RFC 7232](https://tools.ietf.org/html/rfc7232).
39
39
40
40
An IoT Hub identity registry doesn't contain any application metadata.
41
41
42
42
> [!IMPORTANT]
43
-
> Only use the identity registry for device management and provisioning operations. High throughput operations at run time should not depend on performing operations in the identity registry. For example, checking the connection state of a device before sending a command is not a supported pattern. Make sure to check the [throttling rates](iot-hub-devguide-quotas-throttling.md) for the identity registry.
43
+
> Only use the identity registry for device management and provisioning operations. High throughput operations at run time shouldn't depend on performing operations in the identity registry. For example, checking the connection state of a device before sending a command isn't a supported pattern. Make sure to check the [throttling rates](iot-hub-devguide-quotas-throttling.md) for the identity registry.
44
44
45
45
> [!NOTE]
46
-
> It can take a few seconds for a device or module identity to be available for retrieval after creation. Please retry `get` operation of device or module identities in case of failures.
46
+
> It can take a few seconds for a device or module identity to be available for retrieval after creation. If failures occur, you can retry the `get` operation of device or module identities.
47
47
48
48
## Disable devices
49
49
50
50
You can disable devices by updating the **status** property of an identity in the identity registry. Typically, you use this property in two scenarios:
51
51
52
52
* During a provisioning orchestration process. For more information, see [Device Provisioning](iot-hub-devguide-identity-registry.md#device-provisioning).
53
53
54
-
* If you think a device is compromised or has become unauthorized for any reason.
54
+
* If you think a device is compromised or unauthorized for any reason.
55
55
56
56
>[!IMPORTANT]
57
57
>IoT Hub doesn't check certificate revocation lists when authenticating devices with certificate-based authentication. If you have a device that needs to be blocked from connecting to IoT Hub because of a potentially compromised certificate, you should disable the device in the identity registry.
58
58
59
59
This feature isn't available for modules.
60
60
61
-
For more information, see [Disable or delete a device in an IoT hub](./create-connect-device.md#disable-or-delete-a-device).
61
+
For more information, see the [Disable or delete a device](./create-connect-device.md#disable-or-delete-a-device) section of [Create and manage device identities](create-connect-device.md).
62
62
63
63
## Import and export device identities
64
64
65
65
The only way to retrieve all identities in an IoT hub's identity registry is to use the export functionality.
66
66
67
67
Use asynchronous operations on the [IoT Hub resource provider endpoint](iot-hub-devguide-endpoints.md) to import or export device identities in bulk from an IoT hub's identity registry. Imports and exports are long-running jobs that use a customer-supplied blob container.
68
68
69
-
For more information about the import and export APIs, see [IoT Hub resource provider REST APIs](/rest/api/iothub/iothubresource). To learn more about running import and export jobs, see [Bulk management of IoT Hub device identities](iot-hub-bulk-identity-mgmt.md).
69
+
For more information about the import and export APIs, see [IoT Hub Resource](/rest/api/iothub/iothubresource). To learn more about running import and export jobs, see [Import and export IoT Hub device identities in bulk](iot-hub-bulk-identity-mgmt.md).
70
70
71
-
Device identities can also be exported and imported from an IoT hub by using the Service API through either the [REST API](/rest/api/iothub/service/jobs/createimportexportjob) or one of the IoT Hub [Service SDKs](./iot-hub-devguide-sdks.md#azure-iot-hub-service-sdks).
71
+
Device identities can also be exported and imported from an IoT hub by using the Service API through either the [REST API](/rest/api/iothub/service/jobs/createimportexportjob) or one of the IoT Hub [service SDKs](./iot-hub-devguide-sdks.md#azure-iot-hub-service-sdks).
72
72
73
73
## Device provisioning
74
74
75
75
The device data that a given IoT solution stores depends on the specific requirements of that solution. But, as a minimum, a solution must store device identities and authentication keys. The IoT Hub identity registry can store values for each device such as IDs, authentication keys, and status codes. A solution can use other Azure services such as Table storage, Blob storage, or Azure Cosmos DB to store other device data.
76
76
77
-
*Device provisioning* is the process of adding the initial device data to the stores in your solution. To enable a new device to connect to your hub, you add a device ID and keys to the IoT Hub identity registry. As part of the provisioning process, you might need to initialize device-specific data in other solution stores. You can also use the Azure IoT Hub Device Provisioning Service to enable zero-touch, just-in-time provisioning to one or more IoT hubs. To learn more, see the [Device Provisioning Service documentation](../iot-dps/index.yml).
77
+
*Device provisioning* is the process of adding the initial device data to the stores in your solution. To enable a new device to connect to your hub, you add a device ID and keys to the IoT Hub identity registry. As part of the provisioning process, you might need to initialize device-specific data in other solution stores. You can also use the Azure IoT Hub Device Provisioning Service to enable zero-touch, just-in-time provisioning to one or more IoT hubs. For more information, see [Azure IoT Hub Device Provisioning Service Documentation](../iot-dps/index.yml).
78
78
79
79
## Device and module lifecycle notifications
80
80
81
-
IoT Hub can notify your IoT solution when a device identity is created or deleted by sending lifecycle notifications. To do so, your IoT solution needs to create a route and set the data source equal to *DeviceLifecycleEvents*. By default, no lifecycle notifications are sent, that is, no such routes pre-exist. By creating a route with data source equal to *DeviceLifecycleEvents*, lifecycle events are sent for both device identities and module identities. The message contents differ depending on whether the events are generated for module identities or device identities. To learn more about the properties and body returned in the notification message, see [Non-telemetry event schemas](iot-hub-non-telemetry-event-schema.md).
81
+
IoT Hub can notify your IoT solution when a device identity is created or deleted by sending lifecycle notifications. To do so, your IoT solution needs to create a route and set the data source equal to *DeviceLifecycleEvents*. By default, no lifecycle notifications are sent, that is, no such routes preexist. When you create a route with data source equal to *DeviceLifecycleEvents*, lifecycle events are sent for both device identities and module identities. The message contents differ depending on whether the events are generated for module identities or device identities. For more information about the properties and body returned in the notification message, see [Azure IoT Hub non-telemetry event schemas](iot-hub-non-telemetry-event-schema.md).
82
82
83
-
Notifications for module identity creation are different for IoT Edge modules than for other modules. For IoT Edge modules, the create notification is only sent if the corresponding IoT Edge device is running. For all other modules, lifecycle notifications are sent whenever the module identity is updated on the IoT Hub side.
83
+
Notifications for module identity creation are different for IoT Edge modules than for other modules. For IoT Edge modules, the creation notification is only sent if the corresponding IoT Edge device is running. For all other modules, lifecycle notifications are sent whenever the module identity is updated on the IoT Hub side.
84
84
85
85
## Device identity properties
86
86
87
87
Device identities are represented as JSON documents with the following properties:
88
88
89
89
| Property | Options | Description |
90
90
| --- | --- | --- |
91
-
| deviceId |required, read-only on updates |A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters plus certain special characters: `- . % _ * ? ! ( ) , : = @ $ '`. The special characters `+ #`are not supported. |
92
-
| generationId |required, read-only |An IoT Hub-generated, case-sensitive string up to 128 characters long. This value is used to distinguish devices with the same **deviceId**, when they have been deleted and re-created. |
93
-
| etag |required, read-only |A string representing a weak ETag for the device identity, as per [RFC7232](https://tools.ietf.org/html/rfc7232). |
94
-
| authentication |optional |A composite object containing authentication information and security materials. For more information, see [Authentication Mechanism](/rest/api/iothub/service/devices/get-identity#authenticationmechanism) in the REST API documentation. |
95
-
| capabilities | optional | The set of capabilities of the device. For example, whether the device is an edge device or not. For more information, see [Device Capabilities](/rest/api/iothub/service/devices/get-identity#devicecapabilities) in the REST API documentation. |
96
-
| deviceScope | optional | The scope of the device. In edge devices, auto generated and immutable. Deprecated in non-edge devices. However, in child (leaf) devices, set this property to the same value as the **parentScopes** property (the **deviceScope** of the parent device) for backward compatibility with previous versions of the API. For more information, see [IoT Edge as a gateway: Parent and child relationships](../iot-edge/iot-edge-as-gateway.md#parent-and-child-relationships).|
97
-
| parentScopes | optional | The scope of a child device's direct parent (the value of the **deviceScope** property of the parent device). In edge devices, the value is empty if the device has no parent. In non-edge devices, the property isn't present if the device has no parent. For more information, see [IoT Edge as a gateway: Parent and child relationships](../iot-edge/iot-edge-as-gateway.md#parent-and-child-relationships). |
91
+
| deviceId |required, read-only on updates |A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters plus certain special characters: `- . % _ * ? ! ( ) , : = @ $ '`. The special characters `+ #`aren't supported. |
92
+
| generationId |required, read-only |An IoT Hub-generated, case-sensitive string up to 128 characters long. This value is used to distinguish devices with the same **deviceId**, when they're deleted and re-created. |
93
+
| etag |required, read-only |A string representing a weak ETag for the device identity, as per [RFC 7232](https://tools.ietf.org/html/rfc7232). |
94
+
| authentication |optional |A composite object containing authentication information and security materials. For more information, see [AuthenticationMechanism](/rest/api/iothub/service/devices/get-identity#authenticationmechanism) in the REST API documentation. |
95
+
| capabilities | optional | The set of capabilities of the device. For example, whether the device is an edge device or not. For more information, see [DeviceCapabilities](/rest/api/iothub/service/devices/get-identity#devicecapabilities) in the REST API documentation. |
96
+
| deviceScope | optional | The scope of the device. In edge devices, auto generated and immutable. Deprecated in nonedge devices. However, in child (leaf) devices, set this property to the same value as the **parentScopes** property (the **deviceScope** of the parent device) for backward compatibility with previous versions of the API. For more information, see the [Parent and child relationships](../iot-edge/iot-edge-as-gateway.md#parent-and-child-relationships) section of [How an IoT Edge device can be used as a gateway](../iot-edge/iot-edge-as-gateway.md).|
97
+
| parentScopes | optional | The scope of a child device's direct parent (the value of the **deviceScope** property of the parent device). In edge devices, the value is empty if the device has no parent. In nonedge devices, the property isn't present if the device has no parent. For more information, see the [Parent and child relationships](../iot-edge/iot-edge-as-gateway.md#parent-and-child-relationships) section of [How an IoT Edge device can be used as a gateway](../iot-edge/iot-edge-as-gateway.md).|
98
98
| status |required |An access indicator. Can be `Enabled` or `Disabled`. If `Enabled`, the device is allowed to connect. If `Disabled`, the device can't access any device-facing endpoint. |
99
99
| statusReason |optional |A 128 character-long string that stores the reason for the device identity status. All UTF-8 characters are allowed. |
100
100
| statusUpdateTime |read-only |A temporal indicator, showing the date and time of the last status update. |
@@ -103,7 +103,7 @@ Device identities are represented as JSON documents with the following propertie
103
103
| lastActivityTime |read-only |A temporal indicator, showing the date and last time the device connected, received, or sent a message. This property is eventually consistent, but could be delayed up to 5 to 10 minutes. For this reason, it shouldn't be used in production scenarios. |
104
104
105
105
> [!NOTE]
106
-
> Connection state can only represent the IoT Hub view of the status of the connection. Updates to this state may be delayed, depending on network conditions and configurations.
106
+
> Connection state can only represent the IoT Hub view of the status of the connection. Updates to this state might be delayed, depending on network conditions and configurations.
107
107
108
108
## Module identity properties
109
109
@@ -112,10 +112,10 @@ Module identities are represented as JSON documents with the following propertie
112
112
| Property | Options | Description |
113
113
| --- | --- | --- |
114
114
| deviceId |required, read-only on updates |A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters plus certain special characters: `- . % _ * ? ! ( ) , : = @ $ '`. |
115
-
| moduleId |required, read-only on updates |A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters plus certain special characters: `- . % _ * ? ! ( ) , : = @ $ '`. The special characters `+ #`are not supported. |
116
-
| generationId |required, read-only |An IoT hub-generated, case-sensitive string up to 128 characters long. This value is used to distinguish devices with the same **deviceId**, when they've been deleted and re-created. |
117
-
| etag |required, read-only |A string representing a weak ETag for the device identity, as per [RFC7232](https://tools.ietf.org/html/rfc7232). |
118
-
| authentication |optional |A composite object containing authentication information and security materials. For more information, see [Authentication Mechanism](/rest/api/iothub/service/modules/get-identity#authenticationmechanism) in the REST API documentation. |
115
+
| moduleId |required, read-only on updates |A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters plus certain special characters: `- . % _ * ? ! ( ) , : = @ $ '`. The special characters `+ #`aren't supported. |
116
+
| generationId |required, read-only |An IoT hub-generated, case-sensitive string up to 128 characters long. This value is used to distinguish devices with the same **deviceId**, when they're deleted and re-created. |
117
+
| etag |required, read-only |A string representing a weak ETag for the device identity, as per [RFC 7232](https://tools.ietf.org/html/rfc7232). |
118
+
| authentication |optional |A composite object containing authentication information and security materials. For more information, see [AuthenticationMechanism](/rest/api/iothub/service/modules/get-identity#authenticationmechanism) in the REST API documentation. |
119
119
| managedBy | optional | Identifies who manages this module. For instance, this value is `IoT Edge` if the edge runtime owns this module. |
120
120
| cloudToDeviceMessageCount | read-only | The number of cloud-to-module messages currently queued to be sent to the module. |
121
121
| connectionState |read-only |A field indicating connection status: either `Connected` or `Disconnected`. This field represents the IoT Hub view of the device connection status. **Important**: This field should be used only for development/debugging purposes. The connection state is updated only for devices using MQTT or AMQP. Also, it's based on protocol-level pings (MQTT pings, or AMQP pings), and it can have a maximum delay of only 5 minutes. For these reasons, there can be false positives, such as disconnected devices reported as connected. |
@@ -126,12 +126,12 @@ Module identities are represented as JSON documents with the following propertie
126
126
127
127
*[IoT Hub endpoints](iot-hub-devguide-endpoints.md) describes the various endpoints that each IoT hub exposes for run-time and management operations.
128
128
129
-
*[Azure IoT device and service SDKs](iot-hub-devguide-sdks.md) lists the various language SDKs you can use when you develop both device and service apps that interact with IoT Hub.
129
+
*[Azure IoT Hub SDKs](iot-hub-devguide-sdks.md) lists the various language SDKs you can use when you develop both device and service apps that interact with IoT Hub.
130
130
131
-
*[IoT Hub query language](iot-hub-devguide-query-language.md) describes the query language you can use to retrieve information from IoT Hub about your device twins and jobs.
131
+
*[IoT Hub query language for device and module twins, jobs, and message routing](iot-hub-devguide-query-language.md) describes the query language you can use to retrieve information from IoT Hub about your device twins and jobs.
132
132
133
-
*[Use device twins to synchronize state and configurations](iot-hub-devguide-device-twins.md)
133
+
*[Understand and use device twins in IoT Hub](iot-hub-devguide-device-twins.md)
134
134
135
135
To explore using the IoT Hub Device Provisioning Service to enable zero-touch, just-in-time provisioning, see:
0 commit comments