使用 IoT 中心上传文件Upload files with IoT Hub

IoT 中心终结点一文中详述,设备可以通过面向设备的终结点 (/devices/{deviceId}/files) 发送通知以启动文件上传。As detailed in the IoT Hub endpoints article, a device can start a file upload by sending a notification through a device-facing endpoint (/devices/{deviceId}/files). 当设备通知 IoT 中心已完成某个上传时,IoT 中心会通过面向服务的终结点 (/messages/servicebound/filenotifications) 发送文件上传通知消息。When a device notifies IoT Hub that an upload is complete, IoT Hub sends a file upload notification message through the /messages/servicebound/filenotifications service-facing endpoint.

IoT 中心本身不中转消息,而是充当关联 Azure 存储帐户的调度程序。Instead of brokering messages through IoT Hub itself, IoT Hub instead acts as a dispatcher to an associated Azure Storage account. 设备请求来自 IoT 中心的存储令牌,该令牌特定于设备要上传的文件。A device requests a storage token from IoT Hub that is specific to the file the device wishes to upload. 设备使用 SAS URI 将文件上传到存储,上传完成后,设备将完成通知发送到 IoT 中心。The device uses the SAS URI to upload the file to storage, and when the upload is complete the device sends a notification of completion to IoT Hub. IoT 中心检查文件上传是否已完成,然后将文件上传通知消息添加到面向服务的文件通知终结点。IoT Hub checks the file upload is complete and then adds a file upload notification message to the service-facing file notification endpoint.

从设备将文件上传到 IoT 中心之前,必须通过为其关联 Azure 存储帐户来配置该中心。Before you upload a file to IoT Hub from a device, you must configure your hub by associating an Azure Storage account to it.

然后,设备就能初始化上传,并在上传完成后通知 IoT 中心Your device can then initialize an upload and then notify IoT hub when the upload completes. (可选)设备通知 IoT 中心上传完成以后,服务可以生成通知消息Optionally, when a device notifies IoT Hub that the upload is complete, the service can generate a notification message.

何时使用When to use

使用文件上传功能发送连接的设备间歇性地上传的媒体文件和大型遥测批文件(或者是经过压缩的文件以节省带宽)。Use file upload to send media files and large telemetry batches uploaded by intermittently connected devices or compressed to save bandwidth.

如果在使用报告属性、设备到云消息或文件上传方面有任何疑问,请参阅设备到云通信指南Refer to Device-to-cloud communication guidance if in doubt between using reported properties, device-to-cloud messages, or file upload.

将 Azure 存储帐户与 IoT 中心相关联Associate an Azure Storage account with IoT Hub

要使用文件上传功能,必须首先将 Azure 存储帐户链接到 IoT 中心。To use the file upload functionality, you must first link an Azure Storage account to the IoT Hub. 可通过 Azure 门户完成此任务,或通过 IoT 中心资源提供程序 REST API 以编程方式完成此任务。You can complete this task either through the Azure portal, or programmatically through the IoT Hub resource provider REST APIs. 将 Azure 存储帐户与 IoT 中心关联后,当设备启动文件上传请求时,此服务将向该设备返回 SAS URI。Once you've associated an Azure Storage account with your IoT Hub, the service returns a SAS URI to a device when the device starts a file upload request.

使用 IoT 中心将文件从设备上传到云操作指南提供了文件上传过程的完整演练。The Upload files from your device to the cloud with IoT Hub how-to guides provide a complete walkthrough of the file upload process. 这些操作指南展示了如何使用 Azure 门户将存储帐户与 IoT 中心相关联。These how-to guides show you how to use the Azure portal to associate a storage account with an IoT hub.

Note

Azure IoT SDK 自动处理检索 SAS URI、上传文件和通知 IoT 中心已完成上传等操作。The Azure IoT SDKs automatically handle retrieving the SAS URI, uploading the file, and notifying IoT Hub of a completed upload.

初始化文件上传Initialize a file upload

IoT 中心有一个终结点,专供设备在上传文件时请求用于存储的 SAS URI。IoT Hub has an endpoint specifically for devices to request a SAS URI for storage to upload a file. 为了启动文件上传过程,设备会使用以下 JSON 正文向 {iot hub}.azure-devices.net/devices/{deviceId}/files 发送 POST 请求:To start the file upload process, the device sends a POST request to {iot hub}.azure-devices.net/devices/{deviceId}/files with the following JSON body:

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

IoT 中心返回以下数据,供设备用来上传文件:IoT Hub returns the following data, which the device uses to upload the file:

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

已弃用:使用 GET 初始化文件上传Deprecated: initialize a file upload with a GET

Note

本部分介绍已弃用的功能,这些功能用于从 IoT 中心接收 SAS URI。This section describes deprecated functionality for how to receive a SAS URI from IoT Hub. 使用前面所述的 POST 方法。Use the POST method described previously.

IoT 中心有两个 REST 终结点支持文件上传,一个用于获取存储的 SAS URI,另一个用于通知 IoT 中心已完成上传。IoT Hub has two REST endpoints to support file upload, one to get the SAS URI for storage and the other to notify the IoT hub of a completed upload. 设备通过在 {iot hub}.azure-devices.net/devices/{deviceId}/files/{filename} 向 IoT 中心发送 GET 来启动文件上传过程。The device starts the file upload process by sending a GET to the IoT hub at {iot hub}.azure-devices.net/devices/{deviceId}/files/{filename}. IoT 中心返回:The IoT hub returns:

  • 特定于要上传的文件的 SAS URI。A SAS URI specific to the file to be uploaded.
  • 上传完成后要使用的相关 ID。A correlation ID to be used once the upload is completed.

通知 IoT 中心已完成文件上传Notify IoT Hub of a completed file upload

设备使用 Azure 存储 SDK 将文件上传到存储。The device uploads the file to storage using the Azure Storage SDKs. 上传完成后,设备会使用以下 JSON 正文向 {iot hub}.azure-devices.cn/devices/{deviceId}/files/notifications 发送 POST 请求:When the upload is complete, the device sends a POST request to {iot hub}.azure-devices.cn/devices/{deviceId}/files/notifications with the following JSON body:

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

isSuccess 的值为布尔值,指示文件是否已成功上传。The value of isSuccess is a Boolean that indicates whether the file was uploaded successfully. statusCode 的状态代码表示将文件上传到存储时的状态,statusDescription 对应于 statusCodeThe status code for statusCode is the status for the upload of the file to storage, and the statusDescription corresponds to the statusCode.

参考主题:Reference topics:

以下参考主题详细介绍了如何从设备上传文件。The following reference topics provide you with more information about uploading files from a device.

文件上传通知File upload notifications

(可选)当设备通知 IoT 中心某个上传完成后,IoT 中心将生成一条通知消息。Optionally, when a device notifies IoT Hub that an upload is complete, IoT Hub generates a notification message. 此消息包含文件的名称和存储位置。This message contains the name and storage location of the file.

终结点中所述,IoT 中心通过面向服务的终结点 (/messages/servicebound/fileuploadnotifications) 以消息的形式传递文件上传通知。As explained in Endpoints, IoT Hub delivers file upload notifications through a service-facing endpoint (/messages/servicebound/fileuploadnotifications) as messages. 文件上传通知的接收语义与云到设备的消息的接收语义相同,并且具有相同的消息生命周期The receive semantics for file upload notifications are the same as for cloud-to-device messages and have the same message lifecycle. 从文件上传通知终结点检索到的每条消息都是具有以下属性的 JSON 记录:Each message retrieved from the file upload notification endpoint is a JSON record with the following properties:

属性Property 说明Description
EnqueuedTimeUtcEnqueuedTimeUtc 指示通知创建时间的时间戳。Timestamp indicating when the notification was created.
DeviceIdDeviceId DeviceIdDeviceId of the device which uploaded the file.
BlobUriBlobUri 已上传文件的 URI。URI of the uploaded file.
BlobNameBlobName 已上传文件的名称。Name of the uploaded file.
LastUpdatedTimeLastUpdatedTime 指示文件更新时间的时间戳。Timestamp indicating when the file was last updated.
BlobSizeInBytesBlobSizeInBytes 已上传文件的大小。Size of the uploaded file.

示例Example. 此示例显示文件上传通知消息的正文。This example shows the body of a file upload notification message.

{
    "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"
}

文件上传通知配置选项File upload notification configuration options

每个 IoT 中心都具有针对文件上传通知的以下配置选项:Each IoT hub has the following configuration options for file upload notifications:

属性Property 说明Description 范围和默认值Range and default
enableFileUploadNotificationsenableFileUploadNotifications 控制是否将文件上传通知写入文件通知终结点。Controls whether file upload notifications are written to the file notifications endpoint. 布尔型。Bool. 默认值:True。Default: True.
fileNotifications.ttlAsIso8601fileNotifications.ttlAsIso8601 文件上传通知的默认 TTL。Default TTL for file upload notifications. ISO_8601 间隔上限为 48 小时(下限为 1 分钟)。ISO_8601 interval up to 48H (minimum 1 minute). 默认值:1 小时。Default: 1 hour.
fileNotifications.lockDurationfileNotifications.lockDuration 文件上传通知队列的锁定持续时间。Lock duration for the file upload notifications queue. 5 到 300 秒(最小为 5 秒)。5 to 300 seconds (minimum 5 seconds). 默认值:60 秒。Default: 60 seconds.
fileNotifications.maxDeliveryCountfileNotifications.maxDeliveryCount 文件上传通知队列的最大传递计数。Maximum delivery count for the file upload notification queue. 1 到 100。1 to 100. 默认值:100。Default: 100.

其他参考资料Additional reference material

IoT 中心开发人员指南中的其他参考主题包括:Other reference topics in the IoT Hub developer guide include:

后续步骤Next steps

现在,你已了解了如何使用 IoT 中心从设备上传文件,接下来可以根据兴趣查看以下 IoT 中心开发人员指南主题:Now you've learned how to upload files from devices using IoT Hub, you may be interested in the following IoT Hub developer guide topics:

要尝试本文中介绍的一些概念,请参阅以下 IoT 中心教程:To try out some of the concepts described in this article, see the following IoT Hub tutorial: