了解 IoT 中心的标识注册表

每个 IoT 中心都有一个标识注册表,存储允许连接到 IoT 中心的设备和模块的相关信息。 IoT 中心的标识注册表中必须先有设备或模块的条目,然后该设备或模块才能连接到 IoT 中心。 设备或模块还必须基于标识注册表中存储的凭据向 IoT 中心进行身份验证。

标识注册表中存储的设备或模块 ID 区分大小写。

概括地说,标识注册表是支持 REST 的设备或模块标识资源集合。 在此标识注册表中添加条目时,IoT 中心会创建一组每设备资源,如包含未送达云到设备消息的队列。

在需要时执行以下操作时可使用标识注册表:

  • 设置连接到 IoT 中心的设备或模块。
  • 控制每个设备/每个模块对中心的面向设备或模块的终结点的访问。

标识注册表操作

IoT 中心标识注册表公开以下操作:

  • 创建设备或模块标识
  • 更新设备或模块标识
  • 按 ID 检索设备或模块标识
  • 删除设备或模块标识
  • 最多列出 1000 个标识
  • 将设备标识导出到 Azure Blob 存储
  • 将设备标识从 Azure Blob 存储导入

上述所有操作均可以使用 RFC7232 中指定的乐观并发。

重要

如果要检索 IoT 中心标识注册表中的所有标识,唯一方法是使用导出功能。

IoT 中心标识注册表:

  • 不包含任何应用程序元数据。

重要

只将标识注册表用于设备管理和预配操作。 运行时的高吞吐量操作不应依赖于在标识注册表中执行操作。 例如,在发送命令前先检查设备的连接状态就是不支持的模式。 请务必检查标识注册表的限制速率以及设备检测信号模式。

禁用设备

可以通过更新标识注册表中标识的 状态 属性来禁用设备。 通常在两种情况下使用此属性:

  • 在预配协调过程中。 有关详细信息,请参阅设备预配

  • 出于任何原因认为设备遭到入侵或未经授权。

此功能不适用于模块。

导入和导出设备标识

可以使用 IoT 中心资源提供程序终结点上的异步操作,从 IoT 中心的标识注册表批量导出设备标识。 导出是长时间运行的作业,它使用客户提供的 blob 容器来保存从标识注册表读取的设备标识数据。

可以使用 IoT 中心资源提供程序终结点上的异步操作,向 IoT 中心的标识注册表批量导入设备标识。 导入是长时间运行的作业,它使用客户提供的 blob 容器中的数据,将设备标识数据写入标识注册表。

有关导入和导出 API 的详细信息,请参阅 IoT 中心资源提供程序 REST API。 若要了解有关如何运行导入和导出作业的详细信息,请参阅批量管理 IoT 中心的设备标识

设备标识也可以使用 REST API 或 IoT 中心服务 SDK 之一通过服务 API 从 IoT 中心导出和导入。

Device Provisioning

给定的 IoT 解决方案存储的设备数据取决于该解决方案的特定要求。 但是,解决方案必须至少存储设备标识和身份验证密钥。 Azure IoT 中心包含标识注册表,可以存储每个设备的值,例如 ID、身份验证密钥和状态代码。 解决方案可以使用其他 Azure 服务(例如表存储、Blob 存储或 Cosmos DB)来存储任何其他设备数据。

设备预配 是将初始设备数据添加到解决方案中存储中的过程。 要使新设备能够连接到中心,必须将新设备 ID 和密钥添加到 IoT 中心的标识注册表。 在预配过程中,可能需要初始化其他解决方案存储中的设备特定数据。 还可以使用 Azure IoT 中心设备预配服务实现无需人工干预,零接触实时预配到一个或多个 IoT 中心。 若要了解详细信息,请参阅预配服务文档

检测信号

IoT 中心标识注册表包含名为 connectionState 的字段。 开发和调试期间仅使用 connectionState 字段。 IoT 解决方案不应在运行时查询字段。 例如,不要在发送云到设备的消息或 SMS 之前查询 connectionState 字段以检查设备是否已连接。 我们建议订阅事件网格上的 设备已断开连接 事件以获取警报并监视设备连接状态。 使用此教程了解如何在 IoT 解决方案中集成 IoT 中心的设备已连接和设备已断开连接事件。

如果 IoT 解决方案需要知道设备是否已连接,则可实现 检测信号模式。 在检测信号模式下,设备每隔固定时间至少发送一次设备到云的消息(例如,每小时至少一次)。 因此,即使设备没有任何要发送的数据,仍会发送空的设备到云的消息(通常具有可供识别为检测信号的属性)。 在服务端,该解决方案维护着与每个设备收到的最后一个检测信号的映射。 如果解决方案未在预计时间内从设备收到检测信号消息,则它假定设备存在问题。

更复杂的实现可包含来自 Azure MonitorAzure 资源运行状况的信息,用于识别尝试进行连接或通信但失败的设备。 若要了解详细信息,请参阅监视 IoT 中心检查 IoT 中心资源运行状况。 实施检测信号模式时,请务必查看 IoT 中心配额与限制

备注

如果 IoT 解决方案只使用连接状态来决定是否发送云到设备的消息,并且没有把消息广播到大量设备,则考虑使用更简单的较短到期时间模式。 此模式达到的效果与使用检测信号模式维护设备连接状态注册表达到的效果一样,而且更加有效。 如果请求消息确认,则 IoT 中心可以通知你哪些设备可以接收消息以及哪些设备不能接收。

设备和模块生命周期通知

创建或删除设备标识时,IoT 中心可通过发送生命周期通知来通知 IoT 解决方案。 为此,IoT 解决方案需要创建一个路由,并将“数据源”设置为等于 DeviceLifecycleEvents。 默认情况下,不会发送生命周期通知,即无此类路由预先存在。 通过使用等于 DeviceLifecycleEvents 的数据源创建路由,将同时为设备标识和模块标识发送生命周期事件;但是,消息内容会有所不同,具体取决于是为模块标识还是设备标识生成事件。 应注意的是,对于 IoT Edge 模块,模块标识创建流不同于其他模块的创建流,因此对于 IoT Edge 模块,仅当更新的 IoT Edge 模块标识的相应 IoT Edge 设备正在运行时才发送创建通知。 对于其他所有模块,只要在 IoT 中心端更新了模块标识,就发送生命周期通知。 通知消息包括属性和正文。

属性:消息系统属性以 $ 符号作为前缀。

设备的通知消息:

名称 Value
$content-type application/json
$iothub-enqueuedtime 发送通知的时间
$iothub-message-source deviceLifecycleEvents
$content-encoding utf-8
opType createDeviceIdentitydeleteDeviceIdentity
hubName IoT 中心的名称
deviceId 设备 ID
operationTimestamp ISO8601 操作时间戳
iothub-message-schema deviceLifecycleNotification

正文:本部分采用 JSON 格式,表示创建的设备标识的孪生。 例如,

{
    "deviceId":"11576-ailn-test-0-67333793211",
    "etag":"AAAAAAAAAAE=",
    "properties": {
        "desired": {
            "$metadata": {
                "$lastUpdated": "2016-02-30T16:24:48.789Z"
            },
            "$version": 1
        },
        "reported": {
            "$metadata": {
                "$lastUpdated": "2016-02-30T16:24:48.789Z"
            },
            "$version": 1
        }
    }
}

模块的通知消息:

名称 Value
$content-type application/json
$iothub-enqueuedtime 发送通知的时间
$iothub-message-source moduleLifecycleEvents
$content-encoding utf-8
opType createModuleIdentitydeleteModuleIdentity
hubName IoT 中心的名称
moduleId 模块 的 ID
operationTimestamp ISO8601 操作时间戳
iothub-message-schema moduleLifecycleNotification

正文:本部分采用 JSON 格式,表示创建的模块孪生的标识。 例如,

{
    "deviceId":"11576-ailn-test-0-67333793211",
    "moduleId":"tempSensor",
    "etag":"AAAAAAAAAAE=",
    "properties": {
        "desired": {
            "$metadata": {
                "$lastUpdated": "2016-02-30T16:24:48.789Z"
            },
            "$version": 1
        },
        "reported": {
            "$metadata": {
                "$lastUpdated": "2016-02-30T16:24:48.789Z"
            },
            "$version": 1
        }
    }
}

设备标识属性

设备识别表示为包含以下属性的 JSON 文档:

属性 选项 说明
deviceId 必需,更新时只读 ASCII 7 位字母数字字符 + 某些特殊字符(- . + % _ # * ? ! ( ) , : = @ $ ')的区分大小写字符串(最长为 128 个字符)。
generationId 必需,只读 IoT 中心生成的区分大小写字符串,最长为 128 个字符。 在删除并重新创建设备时,此值用于区分具有相同 deviceId 的设备。
etag 必需,只读 一个字符串,根据 RFC7232 表示设备标识的弱 ETag。
身份验证 可选 包含身份验证信息和安全材料的复合对象。 有关详细信息,请参阅 REST API 文档中的[身份验证机制]((https://docs.microsoft.com/rest/api/iothub/service/devices/get-identity#authenticationmechanism) 。
capabilities 可选 设备的功能集。 例如,设备是否是边缘设备。 有关详细信息,请参阅 REST API 文档中的[设备功能]((https://docs.microsoft.com/rest/api/iothub/service/devices/get-identity#devicecapabilities) 。
deviceScope 可选 设备的范围。 在边缘设备中自动生成且不可变。 在非边缘设备中已弃用。 但是,在子(叶)设备中,请将此属性设置为与 parentScopes 属性(父设备的 deviceScope)相同的值,以便与以前版本的 API 后向兼容。 有关详细信息,请参阅使用 IoT Edge 作为网关:父子关系
parentScopes 可选 子设备的直接父级的范围(父设备的 deviceScope 属性的值)。 在边缘设备中,如果设备没有父级,则该值为空。 在非边缘设备中,如果设备没有父级,则该属性不存在。 有关详细信息,请参阅使用 IoT Edge 作为网关:父子关系
状态 必填 访问指示器。 可以是 EnabledDisabled。 如果是 Enabled,则允许设备连接。 如果是 Disabled,则此设备无法访问任何面向设备的终结点。
statusReason 可选 128 个字符的字符串,用于存储设备标识状态的原因。 允许所有 UTF-8 字符。
statusUpdateTime 只读 临时指示器,显示上次状态更新的日期和时间。
connectionState 只读 指示连接状态的字段:ConnectedDisconnected。 此字段表示设备连接状态的 IoT 中心视图。 重要说明:此字段仅应当用于开发/调试目的。 仅使用 MQTT 或 AMQP 的设备才更新连接状态。 此外,它基于协议级别的 ping(MQTT ping 或 AMQP ping),并且最多只有 5 分钟的延迟。 出于这些原因,可能会发生误报,例如,将设备报告为已连接,但实际上已断开连接。
connectionStateUpdatedTime 只读 临时指示器,显示上次更新连接状态的日期和时间。
lastActivityTime 只读 临时指示器,显示设备上次连接、接收或发送消息的日期和时间。 此属性最终是一致的,但最多可延迟 5 到 10 分钟。 因此,不应在生产方案中使用它。

备注

连接状态只能表示连接状态的 IoT 中心视图。 根据网络状态和配置,可能会延迟此状态的更新。

备注

目前,设备 SDK 不支持在 deviceId 中使用 +# 字符。

模块标识属性

模块识别表示为包含以下属性的 JSON 文档:

属性 选项 说明
deviceId 必需,更新时只读 ASCII 7 位字母数字字符 + 某些特殊字符(- . + % _ # * ? ! ( ) , : = @ $ ')的区分大小写字符串(最长为 128 个字符)。
moduleId 必需,更新时只读 ASCII 7 位字母数字字符 + 某些特殊字符(- . + % _ # * ? ! ( ) , : = @ $ ')的区分大小写字符串(最长为 128 个字符)。
generationId 必需,只读 IoT 中心生成的区分大小写字符串,最长为 128 个字符。 在删除并重新创建设备时,此值用于区分具有相同 deviceId 的设备。
etag 必需,只读 一个字符串,根据 RFC7232 表示设备标识的弱 ETag。
身份验证 可选 包含身份验证信息和安全材料的复合对象。 有关详细信息,请参阅 REST API 文档中的[身份验证机制]((https://docs.microsoft.com/rest/api/iothub/service/modules/get-identity#authenticationmechanism) 。
managedBy 可选 标识管理此模块的人。 例如,如果 Edge 运行时拥有此模块,则此值为“IotEdge”。
cloudToDeviceMessageCount 只读 当前排队等待发送到模块的云到模块消息的数量。
connectionState 只读 指示连接状态的字段:ConnectedDisconnected。 此字段表示设备连接状态的 IoT 中心视图。 重要说明:此字段仅应当用于开发/调试目的。 仅使用 MQTT 或 AMQP 的设备才更新连接状态。 此外,它基于协议级别的 ping(MQTT ping 或 AMQP ping),并且最多只有 5 分钟的延迟。 出于这些原因,可能会发生误报,例如,将设备报告为已连接,但实际上已断开连接。
connectionStateUpdatedTime 只读 临时指示器,显示上次更新连接状态的日期和时间。
lastActivityTime 只读 临时指示器,显示设备上次连接、接收或发送消息的日期和时间。

备注

目前,设备 SDK 不支持在 deviceIdmoduleId 中使用 +# 字符。

其他参考资料

IoT 中心开发人员指南中的其他参考主题包括:

后续步骤

了解如何使用 IoT 中心标识注册表后,可以根据兴趣参阅以下 IoT 中心开发人员指南主题:

要尝试本文中介绍的一些概念,请参阅以下 IoT 中心教程:

若要了解如何使用 IoT 中心设备预配服务启用零接触实时预配,请参阅: