使用 IoT 中心上传文件

项目
10/24/2023

在某些情况下，无法轻松地将设备数据映射到 IoT 中心接受的相对较小的设备到云消息。例如，发送视频等较大的媒体文件；或者，发送较大的遥测批处理，这些文件是通过间歇连接的设备上传的，或者已聚合和压缩，以节省带宽。

当你需要从设备上传大型文件时，仍可以借助 IoT 中心的安全性和可靠性。 IoT 中心本身不中转消息，但是它充当关联 Azure 存储帐户的调度程序。 IoT 中心还可以在设备完成文件上传时向后端服务提供通知。

如果需要帮助确定何时使用报告属性、设备到云消息或文件上传，请参阅设备到云通信指南。

重要

使用 X.509 证书颁发机构 (CA) 身份验证的设备上的文件上传功能为公共预览版，并且必须启用预览模式。这是在一同使用 X.509 指纹身份验证或 X.509 证书证明与 Azure 设备预配服务的设备上的正式发布版本。若要了解有关使用 IoT 中心进行 x.509 身份验证的详细信息，请参阅支持的 x.509 证书。

文件上传概述

IoT 中心通过在预先配置了该中心的 blob 容器和 Azure 存储帐户的每次上传基础上，为连接设备提供共享访问签名 (SAS) URI，来帮助从设备上传文件。使用 IoT 中心进行文件上传有三个部分：在 IoT 中心预配置 Azure 存储帐户和 blob 容器、从设备上传文件，以及（可选）就完成文件上传通知后端服务。

在使用文件上传功能前，必须先将 Azure 存储帐户和 Blob 容器与 IoT 中心关联。还可以配置设置，以控制 IoT 中心如何向 Azure 存储进行身份验证、IoT 中心分发给设备的 SAS URI 的生存时间 (TTL)，以及将文件上传通知发送到后端服务。有关详细信息，请参阅将 Azure 存储帐户与 IoT 中心关联。

设备按照三个步骤操作，将文件上传到关联的 blob 容器：

设备将通过 IoT 中心启动文件上传。它在请求中传递 blob 名称，并返回一个 SAS URI 和相关 ID。 SAS URI 包含 Azure 存储的 SAS 令牌，该令牌授予对 blob 容器中所请求的 blob 的设备读写权限。有关详细信息，请参阅设备：初始化文件上传。
设备使用 SAS URI 安全地调用 Azure blob 存储 API，以将文件上传到 blob 容器。有关详细信息，请参阅设备：使用 Azure 存储 API 上传文件。
文件上传完成后，设备会使用在启动上传时从 IoT 中心收到的相关 ID，通知 IoT 中心完成状态。有关详细信息，请参阅设备：通知 IoT 中心已完成文件上传。

后端服务可以在 IoT 中心的面向服务的文件上传通知终结点上订阅文件上传通知。如果已在 IoT 中心启用这些通知，每当设备通知中心已完成文件上传时，就会在此终结点上提供这些通知。服务可以使用这些通知来触发对 blob 数据的进一步处理。有关详细信息，请参阅服务：文件上传通知。

Azure IoT 设备和服务 SDK 完全支持文件上传。有关详细信息，请参阅使用 SDK 上传文件。

文件上传配额和限制

IoT 中心对它可以在给定时间段内启动的文件上传数量施加限制。阈值基于 IoT 中心的 SKU 和单位数。此外，每个设备一次最多只能上传 10 个并发活动文件。有关详细信息，请参阅 IoT 中心配额和限制。

将 Azure 存储帐户与 IoT 中心关联

必须将 Azure 存储帐户和 Blob 容器与 IoT 中心关联以使用文件上传功能。从 IoT 中心注册的设备上传的所有文件都将发送到此容器。若要在 IoT 中心配置存储帐户和 blob 容器，请参阅使用 Azure 门户配置 IoT 中心文件上传、使用 Azure CLI 配置 IoT 中心文件上传或使用 PowerShell 配置 IoT 中心文件上传。还可以使用 IoT 中心管理 API 以编程方式配置文件上传。

如果使用门户，则可以在配置过程中创建存储帐户和容器。否则，若要创建存储帐户，请参阅 Azure 存储文档中的创建存储帐户。拥有存储帐户后，可以在 Azure Blob 存储快速入门中了解如何创建 blob 容器。默认情况下，Azure IoT 中心使用基于密钥的身份验证来与 Azure 存储进行连接和授权。还可以配置用户分配的或系统分配的托管标识，以对 Azure IoT 中心向 Azure 存储进行身份验证。托管标识以安全的方式在 Microsoft Entra ID 中为 Azure 服务提供了一个自动托管标识。若要了解如何配置托管标识，请参阅 IoT 中心对托管标识的支持部分的使用托管标识配置文件上传。

文件上传须遵循 Azure 存储防火墙设置。根据身份验证配置，需要确保设备可以与 Azure 存储通信。

还有其他几个设置可控制文件上传和文件上传通知的行为。以下部分列出了所有可用的设置。某些设置可能不可用，具体取决于你是使用 Azure 门户、Azure CLI、PowerShell 还是管理 API 来配置文件上传。如果希望在文件上传完成时向后端服务发送通知，请确保设置 enableFileUploadNotifications 设置。

IoT 中心存储和身份验证设置

以下设置将存储帐户和容器与 IoT 中心关联起来，并控制中心如何向 Azure 存储进行身份验证。这些设置不会影响设备对 Azure 存储进行身份验证的方式。设备始终通过从 IoT 中心检索到的 SAS URI 中提供的 SAS 令牌进行身份验证。

属性	说明	范围和默认值
storageEndpoints.$default.authenticationType	控制 IoT 中心如何向 Azure 存储进行身份验证。	可能的值为 keyBased 和 identityBased。默认值：keyBased。
storageEndpoints.$default.connectionString	用于文件上传的 Azure 存储帐户的连接字符串。	默认值：空字符串。
storageEndpoints.$default.containerName	要将文件上传到的容器的名称。	默认值：空字符串。
storageEndpoints.$default.identity	用于基于标识的身份验证的托管标识。	可能的值为系统分配的托管标识的 `[system]`，或用户分配的托管标识的资源 ID。该值不用于基于密钥的身份验证。默认值：NULL。

文件上传设置

以下设置控制从设备上传文件。

属性	说明	范围和默认值
storageEndpoints.$default.ttlAsIso8601	IoT 中心生成的 SAS URI 的默认 TTL。	ISO_8601 间隔上限为 48 小时（下限为 1 分钟）。默认值：一小时。

文件上传通知设置

以下设置控制向后端服务发送的文件上传通知。

属性	说明	范围和默认值
enableFileUploadNotifications	控制是否将文件上传通知写入文件通知终结点。	布尔型。默认值：False。
fileNotifications.ttlAsIso8601	文件上传通知的默认 TTL。	ISO_8601 间隔上限为 48 小时（下限为 1 分钟）。默认值：一小时。
fileNotifications.lockDuration	文件上传通知队列的锁定持续时间。	5 到 300 秒。默认值：60 秒。
fileNotifications.maxDeliveryCount	文件上传通知队列的最大传递计数。	1 到 100。默认值：10。

使用 SDK 上传文件

以下操作指南提供了使用 Azure IoT 设备和服务 SDK 上传文件的完整分步说明。这些指南展示了如何使用 Azure 门户将存储帐户与 IoT 中心相关联。指南中还包含代码片段或参考示例，指导你完成上传过程。

操作指南	设备 SDK 示例	服务 SDK 示例
.NET	是	是
Java	是	是
Node.js	是	是
Python	是	否（不支持）

注意

C 设备 SDK 在设备客户端上使用单个调用来执行文件上传。有关详细信息，请参阅 IoTHubDeviceClient_UploadToBlobAsync() 和 IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync()。这些函数在单个调用中执行文件上传的所有方面：启动上传、将文件上传到 Azure 存储，以及完成后通知 IoT 中心。此交互意味着，除了设备用于与 IoT 中心通信的任何协议之外，设备还需要能够通过 HTTPS 与 Azure 存储通信，因为这些函数调用 Azure 存储 API。

设备：初始化文件上传

设备调用 Create File Upload SAS URI REST API 或其中一个设备 SDK 中的等效 API 来启动文件上传。

支持的协议：HTTPS
终结点：{iot hub}.azure-devices.cn/devices/{deviceId}/files
方法：POST

{
    "blobName":"myfile.txt"
}

属性	描述
blobName	要为其生成 SAS URI 的 blob 名称。

IoT 中心使用相关 ID 和 SAS URI 的元素进行响应，设备可以使用这些元素向 Azure 存储进行身份验证。此响应受目标 IoT 中心的限制和每设备上传限制的制约。

{
    "correlationId":"MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "hostName":"contosostorageaccount.blob.core.chinacloudapi.cn",
    "containerName":"device-upload-container",
    "blobName":"mydevice/myfile.txt",
    "sasToken":"?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw"
}

属性	描述
correlationId	设备在将文件上传完成通知发送到 IoT 中心时使用的标识符。
hostName	IoT 中心上配置的存储帐户的 Azure 存储帐户主机名
containerName	在 IoT 中心配置的 Blob 容器的名称。
blobName	blob 将存储在容器中的位置。该名称采用以下格式：`{device ID of the device making the request}/{blobName in the request}`
sasToken	一个 SAS 令牌，用于通过 Azure 存储授予对 blob 的读写访问权限。令牌由 IoT 中心生成并签名。

收到响应时，设备会执行以下操作：

保存相关 ID，以便在完成上传时将相关 ID 包含在发送给 IoT 中心的文件上传完成通知中。
使用其他属性为 Blob 构造 SAS URI，用于向 Azure 存储进行身份验证。 SAS URI 包含所请求 blob 的资源 URI 和 SAS 令牌。它采用以下形式：https://{hostName}/{containerName}/{blobName}{sasToken}（响应中的 sasToken 属性包含前导“?”字符。）不包括大括号。

例如，对于上述示例中返回的值，SAS URI 为 https://contosostorageaccount.blob.core.chinacloudapi.cn/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw

有关 SAS URI 和 SAS 令牌的详细信息，请参阅 Azure 存储文档中的创建服务 SAS。

设备：使用 Azure 存储 API 上传文件

设备使用 Azure Blob 存储 REST API 或等效的 Azure 存储 SDK API 将文件上传到 Azure 存储中的 blob。

支持的协议：HTTPS

以下示例演示用于创建或更新小型块 blob 的 Put Blob 请求。请注意，用于此请求的 URI 是上一部分中 IoT 中心返回的 SAS URI。 x-ms-blob-type 标头指示此请求适用于块 blob。如果请求成功，Azure 存储将返回 201 Created。

PUT https://contosostorageaccount.blob.core.chinacloudapi.cn/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw HTTP/1.1
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Host: contosostorageaccount.blob.core.chinacloudapi.cn
x-ms-blob-type: BlockBlob

hello world

使用 Azure 存储 API 不在本文讨论范围。除了本部分前面链接的 Azure Blob 存储 REST API 之外，还可以浏览以下文档来帮助你入门：

若要了解有关在 Azure 存储中使用 blob 的详细信息，请参阅 Azure Blob 存储文档。
有关使用 Azure 存储客户端 SDK 上传 blob 的信息，请参阅 Azure Blob 存储 API 参考。

设备：通知 IoT 中心已完成文件上传

完成文件上传时，设备会调用 Update File Upload Status REST API 或其中一个设备 SDK 中的等效 API。无论上传是成功还是失败，设备都应向 IoT 中心更新文件上传状态。

支持的协议：HTTPS
终结点：{iot hub}.azure-devices.cn/devices/{deviceId}/files/notifications
方法：POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}

属性	描述
correlationId	初始 SAS URI 请求中接收的相关 ID。
isSuccess	一个布尔值，指示文件上传是否成功。
statusCode	一个整数，表示文件上传的状态代码。通常为三位数；例如 200 或 201。
statusDescription	文件上传状态说明。

当它从设备收到文件上传完成通知时，IoT 中心将执行以下操作：

如果配置了文件上传通知，则触发到后端服务的文件上传通知。
释放与文件上传关联的资源。如果 IoT 中心未收到通知，则它将保留资源，直到与上传关联的 SAS URI 生存时间 (TTL) 过期。

服务：文件上传通知

如果在 IoT 中心启用了文件上传通知，则当从设备接收到文件上传完成的通知时，中心会为后端服务生成通知消息。 IoT 中心通过面向服务的终结点传送这些文件上传通知。文件上传通知的接收语义与云到设备消息的接收语义相同，并且具有相同的消息生命周期。服务 SDK 公开 API 来处理文件上传通知。

支持的协议：AMQP、AMQP-WS
终结点：{iot hub}.azure-devices.cn/messages/servicebound/fileuploadnotifications
方法 GET

从文件上传通知终结点检索到的每条消息都是 JSON 记录：

{
    "deviceId":"mydevice",
    "blobUri":"https://contosostorageaccount.blob.core.chinacloudapi.cn/device-upload-container/mydevice/myfile.txt",
    "blobName":"mydevice/myfile.txt",
    "lastUpdatedTime":"2021-07-31T00:26:50+00:00",
    "blobSizeInBytes":11,
    "enqueuedTimeUtc":"2021-07-31T00:26:51.5134008Z"
}

属性	说明
enqueuedTimeUtc	指示通知创建时间的时间戳。
deviceId	上传文件的设备的设备 ID。
blobUri	已上传文件的 URI。
blobName	已上传文件的名称。该名称采用以下格式：`{device ID of the device}/{name of the blob}`
lastUpdatedTime	指示文件更新时间的时间戳。
blobSizeInBytes	一个整数，表示上传文件的大小（以字节为单位）。

服务可以使用通知来管理上传。例如，它们可以触发自己对 blob 数据的处理，使用其他 Azure 服务触发 blob 数据处理，或记录文件上传通知以便以后查看。

后续步骤

文件上传操作指南
如何在 IoT 中心配置文件上传
如何在 IoT 中心配置托管标识
Azure Blob 存储文档
Azure IoT 设备和服务 SDK 列出了开发与 IoT 中心交互的设备和服务应用时可使用的各种语言 SDK。