使用 IoT 中心上传文件

IoT 中心终结点一文中详述,设备可以通过面向设备的终结点 (/devices/{deviceId}/files) 发送通知以启动文件上传。 当设备通知 IoT 中心已完成某个上传时,IoT 中心会通过面向服务的终结点 (/messages/servicebound/filenotifications) 发送文件上传通知消息。

IoT 中心本身不中转消息,而是充当关联 Azure 存储帐户的调度程序。 设备请求来自 IoT 中心的存储令牌,该令牌特定于设备要上传的文件。 设备使用 SAS URI 将文件上传到存储,上传完成后,设备将完成通知发送到 IoT 中心。 IoT 中心检查文件上传是否已完成,然后将文件上传通知消息添加到面向服务的文件通知终结点。

从设备将文件上传到 IoT 中心之前,必须配置中心,通过为其关联 Azure 存储帐户实现配置。

然后,设备就能初始化上传,并在上传完成后通知 IoT 中心。 (可选)当设备通知 IoT 中心上传完成以后,服务就可以生成 通知消息

使用时机

使用文件上传功能发送连接的设备间歇性地上传的媒体文件和大型遥测批文件(或者是经过压缩的文件以节省带宽)。

如果在使用报告属性、设备到云消息或文件上传方面有任何疑问,请参阅 设备到云通信指南

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

要使用文件上传功能,必须首先将 Azure 存储帐户链接到 IoT 中心。 可通过 Azure 门户完成此任务,或通过 IoT 中心资源提供程序 REST API 以编程方式完成此任务。 将 Azure 存储帐户与 IoT 中心关联后,当设备发起文件上传请求时,此服务将向该设备返回 SAS URI。

Note

Azure IoT SDK 自动处理检索 SAS URI、上传文件和通知 IoT 中心已完成上传等操作。

初始化文件上传

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": "contoso.azure-devices.cn",
        "containerName": "testcontainer",
        "blobName": "test-device1/image.jpg",
        "sasToken": "1234asdfSAStoken"
    }

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

Note

本部分介绍已弃用的功能,这些功能用于从 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 中心已完成文件上传

设备负责使用 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。

其他参考资料

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

后续步骤

了解如何使用 IoT 中心从设备上传文件以后,可以根据兴趣参阅以下 IoT 中心开发人员指南主题:

若要尝试本文中介绍的一些概念,可以根据兴趣学习以下 IoT 中心教程: