使用 IoT 中心上传文件

概述

IoT Hub endpoints(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 中心的 {iot hub}.azure-devices.cn/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.cn/devices/{deviceId}/files/{filename} 向 IoT 中心发送 GET 来启动文件上载过程。该 IoT 中心将返回特定于要上载的文件的 SAS URI,以及上载完成时要使用的相关性 ID。

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

设备负责使用 Azure 存储 SDK 将文件上传到存储空间。上载完成后,设备会使用以下 JSON 正文向 IoT 中心的 {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 中心通过面向服务的终结点 (/messages/servicebound/feedback) 以消息的形式传递文件上载通知。文件上载通知的接收语义与云到设备的消息的接收语义相同,并且具有相同的消息生命周期。从文件上传通知终结点检索到的每条消息都是具有以下属性的 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 中心教程: