了解 IoT 中心的标识注册表

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

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

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

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

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

标识注册表操作

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

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

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

重要

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

IoT 中心标识注册表:

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

重要

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

注意

创建设备或模块标识后,可能需要几秒钟才能进行检索。 如果发生故障,请重试设备或模块标识的 get 操作。

禁用设备

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

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

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

    重要

    在使用基于证书的身份验证对设备进行身份验证时,IoT 中心不会检查证书吊销列表。 如果由于证书可能泄露,而需要阻止设备连接到 IoT 中心,则应在标识注册表中禁用该设备。

此功能不适用于模块。

有关详细信息,请参阅在 IoT 中心禁用或删除设备

导入和导出设备标识

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

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

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

此外,可使用服务 API 通过 REST API 或某个 IoT 中心服务 SDK 从 IoT 中心导出和导入设备标识。

Device Provisioning

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

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

设备和模块生命周期通知

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

设备标识属性

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

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

注意

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

其他参考资料

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

后续步骤

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

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