你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

IoT 中心终结点

项目
12/03/2024

Azure IoT 中心公开各种终结点以支持与之交互的设备和服务。

注意

本文中提到的某些功能（例如云到设备消息传递、设备孪生、设备管理）仅在 IoT 中心的标准层中提供。有关 IoT 中心基本层和标准/免费层的详细信息，请参阅选择适合你的解决方案的 IoT 中心层。

IoT 中心名称

可以在 Azure 门户的 IoT 中心的概述工作窗格中找到 IoT 中心的主机名。默认情况下，IoT 中心的 DNS 名称类似于以下示例：

{your iot hub name}.azure-devices.net

用于开发和管理的 IoT 中心终结点

Azure IoT 中心属于多租户服务，向各种执行组件公开功能。下图显示了 IoT 中心公开的各种终结点。

显示了内置 IoT 中心终结点列表的示意图。

以下列表对这些终结点进行了说明：

资源提供程序：Azure 资源管理器接口。此接口使 Azure 订阅所有者可以创建和删除 IoT 中心以及更新 IoT 中心属性。 IoT 中心属性可管理中心级别共享访问策略，而不是设备级别的访问控制以及云到设备和设备到云消息传送的功能选项。 IoT 中心资源提供程序还可让你导出设备标识。
设备标识管理：一组用于管理设备标识的 HTTPS REST 终结点（创建、检索、更新和删除）。设备标识用于设备身份验证和访问控制。
设备孪生管理：一组面向服务的 HTTPS REST 终结点，用于查询和更新设备孪生（更新标记和属性）。
作业管理：一组面向服务的 HTTPS REST 终结点，用于查询和管理作业。
设备终结点：标识注册表中每个设备的一组终结点。除非标明，否则这些终结点使用 MQTT v3.1.1、HTTPS 1.1 和 AMQP 1.0 协议进行公开。还可通过端口 443 上的 WebSocket 使用 AMQP 和 MQTT。这些设备终结点包括：
- 发送设备到云的消息
- 接收云到设备的消息
- 发起文件上传
- 检索和更新设备孪生属性（不支持 HTTPS）
- 接收直接方法请求（不支持 HTTPS）
服务终结点：一组终结点供解决方案后端用于与设备通信。除了一个例外，这些终结点只使用 AMQP 协议以及基于 WebSockets 的 AMQP 协议进行公开。直接方法调用终结点通过 HTTPS 协议进行公开。
- 接收设备到云的消息：此终结点是消息路由概念中讨论的内置终结点。后端服务可用它来读取由设备发送的设备到云的消息。除了此内置终结点外，还可以在 IoT 中心创建自定义终结点。
- 发送云到设备的消息和接收送达确认
- 接收文件上传通知
- 调用直接方法

Azure IoT 中心 SDK 一文介绍了访问这些终结点的各种方法。

所有 IoT 中心终结点都使用 TLS 协议，且绝不会在未加密/不安全的通道上公开任何终结点。

重要

使用 X.509 证书颁发机构 (CA) 身份验证的设备的以下功能尚未正式发布，必须启用预览模式：

HTTPS、基于 WebSocket 的 MQTT 和基于 WebSocket 的 AMQP 协议。
文件上传（所有协议）。

这些功能在使用 X.509 指纹身份验证的设备上已正式发布。若要了解有关使用 IoT 中心进行 X.509 身份验证的详细信息，请参阅支持的 X.509 证书。

消息路由的自定义终结点

可将 Azure 订阅中的现有 Azure 服务链接到充当消息路由终结点的 IoT 中心。这些终结点充当服务终结点，并用作消息路由的接收器。设备无法直接向这些终结点进行写入。有关消息路由的详细信息，请参阅使用 IoT 中心消息路由将设备到云消息发送到不同的终结点。

IoT 中心支持将以下 Azure 服务作为自定义终结点：

存储容器
事件中心
服务总线队列
服务总线主题
Cosmos DB

有关每个中心终结点的限制，请参阅配额和限制。

内置终结点

可以使用标准事件中心集成和 SDK 接收来自内置终结点（消息/事件）的设备到云的消息。在创建一个路由后，数据将停止流向内置终结点，除非创建了到该内置终结点的路由。即使未创建路由，也必须启用回退路由，以便将消息路由到内置终结点。如果使用门户或 CLI 创建中心，则默认情况下会启用回退。

Azure 存储作为路由终结点

有两个存储服务 IoT 中心可将消息路由到：Azure Blob 存储和 Azure Data Lake Storage Gen2 (ADLS Gen2) 帐户。这两个存储服务都使用 blob 作为其存储。若要使用 Azure Data Lake Gen2，存储帐户必须启用了分层命名空间。有关详细信息，请参阅创建与 Azure Data Lake Storage 配合使用的存储帐户。

IoT 中心支持以 Apache Avro 格式和 JSON 格式将数据写入 Azure 存储。默认值为 AVRO。要使用 JSON 编码，请在消息系统属性中将 contentType 属性设置为“application/json”，将 contentEncoding 属性设置为“UTF-8”。这两个值都不区分大小写。如果未设置内容编码，则 IoT 中心将以 base 64 编码格式写入消息。

只有在配置 Blob 存储终结点时才能设置编码格式，不能编辑现有终结点的编码格式。

IoT 中心将在消息达到特定大小或在经过一定的时间后，对消息进行批处理并将数据写入存储。 IoT 中心默认为以下文件命名约定：{iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm}。可以使用任何文件命名约定，但必须使用所有列出的令牌。如果没有要写入的数据，IoT 中心会写入到一个空 Blob。

建议列出 blob 或文件，然后循环访问它们，以确保在未进行有关分区的任何假设的情况下读取所有 blob 或文件。在 Microsoft 发起的故障转移或 IoT 中心手动故障转移期间，分区范围可能发生变化。可以使用 List Blobs API 枚举 blob 列表，或使用 List ADLS Gen2 API 枚举文件列表。例如：

public void ListBlobsInContainer(string containerName, string iothub)
{
    var storageAccount = CloudStorageAccount(Microsoft.Azure.Storage.Auth.StorageCredentials storageCredentials, bool useHttps);
    var cloudBlobContainer = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
    if (cloudBlobContainer.Exists())
    {
        var results = cloudBlobContainer.ListBlobs(prefix: $"{iothub}/");
        foreach (IListBlobItem item in results)
        {
            Console.WriteLine(item.Uri);
        }
    }
}

服务总线队列和服务总线主题作为路由终结点

用作 IoT 中心终结点的服务总线队列和主题不能启用“会话”或“重复项检测”。如果启用了其中任一选项，该终结点将在 Azure 门户中显示为“无法访问”。

事件中心作为路由终结点

除了与事件中心兼容的内置终结点外，还可以将数据路由到事件中心类型的自定义终结点。

Azure Cosmos DB 作为路由终结点

可以将数据直接从 IoT 中心发送到 Azure Cosmos DB。 IoT 中心支持将内容以 JSON（如果在消息的 content-type 中进行了指定）格式或 Base64 编码二进制文件形式写入 Cosmos DB。

要支持大规模方案，可以为 Cosmos DB 终结点启用合成分区键。由于 Cosmos DB 是超大规模数据存储，因此写入到其中的所有数据/文档都必须包含一个表示逻辑分区的字段。每个逻辑分区的最大大小为 20 GB。可在“分区键名称”中指定分区键属性名称。分区键属性名称在容器级别定义，无法更新。

可以根据估计的数据量在“分区键模板”中指定一个模板来配置合成分区键值。例如，在制造方案中，逻辑分区可能会在一个月内达到 20 GB 的最大限制。在这种情况下，可以定义综合分区键，它是设备 ID 和月份的组合。生成的分区键值将自动添加到每个新 Cosmos DB 记录的分区键属性，确保每月为每个设备创建逻辑分区。

注意

如果使用系统分配的托管标识对 Cosmos DB 进行身份验证，则必须使用 Azure CLI 或 Azure PowerShell 将 Cosmos DB 内置数据参与者内置角色定义分配给该标识。 Azure 门户当前不支持针对 Cosmos DB 的角色分配。有关各种角色的详细信息，请参阅为 Azure Cosmos DB 配置基于角色的访问。若要了解如何通过 CLI 分配角色，请参阅管理 Azure Cosmos DB SQL 角色资源。

终结点运行状况

可以使用 REST API Get Endpoint Health 获取终结点的运行状况状态。我们建议使用与路由消息延迟相关的 IoT 中心路由指标来识别和调试终结点运行状况不佳或运行不正常时的错误，因为我们预计当终结点处于其中一种状态时，延迟会更高。若要详细了解如何使用 IoT 中心指标，请参阅监视 IoT 中心。

运行状况状态	说明
healthy	终结点按预期方式接受消息。
不正常	终结点未接受消息，IoT 中心正重试将消息发送到此终结点。
未知	IoT 中心尚未尝试将消息传递到此终结点。
已降级	终结点正在接受比预期慢的消息或正在从不正常状态恢复。
不活动	IoT 中心不再向此终结点传递消息。重新尝试将消息发送到此终结点时失败。

后续步骤

详细了解以下主题：

通过