使用 IoT 中心上传文件

在许多情况下,你无法轻松地将设备发送的数据映射到 IoT 中心容易接受的相对较小的设备到云消息中。 例如:

  • 大图像文件
  • 视频文件
  • 以高频率采样的振动数据
  • 某种形式的预处理数据

当你需要从设备上传此类文件时,仍然可以使用 IoT 中心的安全性和可靠性。 IoT 中心本身不中转消息,而是充当关联的 Azure 存储帐户的调度程序。 设备请求来自 IoT 中心的存储令牌,该令牌特定于设备要上传的文件。 设备使用 SAS URI 将文件上传到存储空间,上传完成后,设备将完成通知发送到 IoT 中心。 IoT 中心检查文件上传是否已完成。

重要

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

何时使用

使用文件上传,发送间歇性连接的设备上传的媒体文件和大型遥测批文件(或者是压缩后的文件,以节省带宽)。 如果在使用报告属性、设备到云消息或文件上传方面有任何疑问,请参阅设备到云通信指南

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

你必须具有与 IoT 中心关联的 Azure 存储帐户。

若要了解如何使用门户创建存储帐户,请参阅创建存储帐户

也可使用 IoT 中心资源提供程序 REST API 以编程方式创建一个。

将 Azure 存储帐户与 IoT 中心相关联时,IoT 中心会生成一个 SAS URI。 设备可以使用此 SAS URI 安全地将文件上传到 Blob 容器。

创建容器

若要通过门户创建 blob 容器,请执行以下操作:

  1. 在存储帐户左窗格的“数据存储”下,选择“容器”。
  2. 在“容器”边栏选项卡中,选择“+ 容器”。
  3. 在打开的“新建容器”窗格中,为容器命名,然后选择“创建”。

在创建容器后,按照使用 Azure 门户配置文件上传中的说明进行操作。 确保有一个 Blob 容器与你的 IoT 中心关联并且文件通知已启用。

还可使用 IoT 中心资源提供程序 REST API 创建与 IoT 中心的存储关联的容器。

使用 SDK 上传文件

以下操作指南提供了以各种 SDK 语言上传文件的过程的完整演练。 这些指南展示了如何使用 Azure 门户将存储帐户与 IoT 中心相关联。 它们还包含了指导你完成上传过程的代码片段或引用了相关示例。

备注

Azure IoT SDK 自动处理检索共享访问签名 URI、上传文件以及通知 IoT 中心已完成上传等操作。 如果防火墙阻止访问 Blob 存储终结点,但允许访问 IoT 中心终结点,则文件上传过程将失败,并针对 IoT C# 设备 SDK 显示以下错误:

---> System.Net.Http.HttpRequestException: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond

若要使文件上传功能正常工作,设备必须能够访问 IoT 中心终结点和 Blob 存储终结点。

初始化文件上传 (REST)

你可以使用 REST API 而不是某个 SDK 来上传文件。 IoT 中心有一个终结点,专供设备在上传文件时请求用于存储的 SAS URI。 为了启动文件上传过程,设备会使用以下 JSON 正文向 {iot hub}.azure-devices.net/devices/{deviceId}/files 发送 POST 请求:

{
    "blobName": "{name of the file for which a SAS URI will be generated}"
}

IoT 中心返回以下数据,供设备用来上传文件:

{
    "correlationId": "somecorrelationid",
    "hostName": "yourstorageaccount.blob.core.chinacloudapi.cn",
    "containerName": "testcontainer",
    "blobName": "test-device1/image.jpg",
    "sasToken": "1234asdfSAStoken"
}

已弃用:使用 GET 初始化文件上传

备注

本部分介绍已弃用的功能,这些功能用于从 IoT 中心接收 SAS URI。 使用前面所述的 POST 方法。

IoT 中心有两个 REST 终结点支持文件上传,一个用于获取存储的 SAS URI,另一个用于通知 IoT 中心已完成上传。 设备通过在 {iot hub}.azure-devices.net/devices/{deviceId}/files/{filename} 向 IoT 中心发送 GET 来启动文件上传过程。 IoT 中心返回:

  • 特定于要上传的文件的 SAS URI。
  • 上传完成后要使用的相关 ID。

通知 IoT 中心已完成文件上传 (REST)

设备使用 Azure 存储 SDK 将文件上传到存储。 上传完成后,设备会使用以下 JSON 正文向 {iot hub}.azure-devices.cn/devices/{deviceId}/files/notifications 发送 POST 请求:

{
    "correlationId": "{correlation ID received from the initial request}",
    "isSuccess": bool,
    "statusCode": XXX,
    "statusDescription": "Description of status"
}

isSuccess 的值为布尔值,指示文件是否已成功上传。 statusCode 的状态代码表示将文件上传到存储时的状态,statusDescription 对应于 statusCode

参考主题:

以下参考主题详细介绍了如何从设备上传文件。

文件上传通知

(可选)当设备通知 IoT 中心某个上传完成后,IoT 中心将生成一条通知消息。 此消息包含文件的名称和存储位置。

终结点中所述,IoT 中心通过面向服务的终结点 (/messages/servicebound/fileuploadnotifications) 以消息的形式传递文件上传通知。 文件上传通知的接收语义与云到设备消息的接收语义相同,并且具有相同的消息生命周期。 从文件上传通知终结点检索到的每条消息都是具有以下属性的 JSON 记录:

属性 说明
EnqueuedTimeUtc 指示通知创建时间的时间戳。
DeviceId 上传文件的设备的 DeviceId
BlobUri 已上传文件的 URI。
BlobName 已上传文件的名称。
LastUpdatedTime 指示文件更新时间的时间戳。
BlobSizeInBytes 已上传文件的大小。

示例。 此示例显示文件上传通知消息的正文。

{
    "deviceId":"mydevice",
    "blobUri":"https://{storage account}.blob.core.chinacloudapi.cn/{container name}/mydevice/myfile.jpg",
    "blobName":"mydevice/myfile.jpg",
    "lastUpdatedTime":"2016-06-01T21:22:41+00:00",
    "blobSizeInBytes":1234,
    "enqueuedTimeUtc":"2016-06-01T21:22:43.7996883Z"
}

文件上传通知配置选项

每个 IoT 中心都具有针对文件上传通知的以下配置选项:

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

可以使用 Azure 门户、Azure CLI 或 PowerShell 在 IoT 中心设置这些属性。 若要了解如何操作,请参阅配置文件上传下的主题。

其他参考资料

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

后续步骤

现在,你已了解了如何使用 IoT 中心从设备上传文件,接下来可以根据兴趣查看以下 IoT 中心开发人员指南主题:

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