IoT Hub を使用したファイルのアップロードUpload files with IoT Hub

IoT Hub エンドポイントに関する記事で詳しく説明したように、デバイスは、デバイス向けエンドポイント ( /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 Hub に通知すると、IoT Hub はサービス向けエンドポイント ( /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 Hub 自体を介してメッセージをやり取りする代わりに、IoT Hub が、関連付けられている Azure ストレージ アカウントへのディスパッチャーとして機能します。Instead of brokering messages through IoT Hub itself, IoT Hub instead acts as a dispatcher to an associated Azure Storage account. デバイスは、アップロードするファイルに固有のストレージ トークンを IoT Hub に要求します。A device requests a storage token from IoT Hub that is specific to the file the device wishes to upload. SAS URI を使用して、ファイルをストレージにアップロードし、アップロードが完了すると、IoT Hub に完了の通知を送信します。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 Hub は、ファイル アップロードが完了したことを確認してから、サービス向けファイル通知エンドポイントにファイル アップロード通知メッセージを追加します。IoT Hub checks the file upload is complete and then adds a file upload notification message to the service-facing file notification endpoint.

デバイスから IoT Hub にファイルをアップロードするには、Azure Storage アカウントを関連付けることによってハブを構成する必要があります。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 Hub に通知できます。Your device can then initialize an upload and then notify IoT hub when the upload completes. 必要に応じて、デバイスがアップロードの完了を IoT Hub に通知するときに、サービスによって通知メッセージを生成できます。Optionally, when a device notifies IoT Hub that the upload is complete, the service can generate a notification message.

重要

ファイル アップロード機能は、X.509 証明機関 (CA) 認証を使用するデバイスではサポートされません。File upload functionality is not supported on devices that use X.509 certificate authority (CA) authentication. これは、X.509 拇印認証を使用するデバイスでサポートされます。It is supported on devices that use X.509 thumbprint authentication. IoT Hub での X.509 認証の詳細については、「サポートされている X.509 証明書」を参照してください。To learn more about X.509 authentication with IoT Hub, see Supported X.509 certificates.

使用する場合When to use

ファイルのアップロードを使用して、断続的に接続されたデバイスでアップロードされた、または帯域幅を節約するために圧縮されたメディア ファイルや大容量のテレメトリ バッチを送信します。Use file upload to send media files and large telemetry batches uploaded by intermittently connected devices or compressed to save bandwidth.

報告プロパティ、Device-to-cloud メッセージ、またはファイルのアップロードのどれを使用するべきか不明な場合は、デバイスからクラウドへの通信に関するガイダンスを参照してください。Refer to Device-to-cloud communication guidance if in doubt between using reported properties, device-to-cloud messages, or file upload.

Azure Storage アカウントと IoT Hub の関連付けAssociate an Azure Storage account with IoT Hub

ファイルのアップロード機能を使用するには、最初に Azure ストレージ アカウントを IoT Hub にリンクする必要があります。To use the file upload functionality, you must first link an Azure Storage account to the IoT Hub. このタスクは、Azure portal から、または IoT Hub のリソース プロバイダー 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 Hub でデバイスからクラウドにファイルをアップロードする方法に関する操作ガイドに、ファイルのアップロード プロセスの完全な手順が示されています。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 portal を使用してストレージ アカウントを IoT ハブに関連付ける方法が説明されています。These how-to guides show you how to use the Azure portal to associate a storage account with an IoT hub.

注意

Azure IoT SDK では、SAS URI の取得、ファイルのアップロード、および IoT Hub へのアップロード完了の通知を自動的に処理します。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 Hub には、ファイルをアップロードするためのストレージの SAS URI を要求する、特にデバイス向けのエンドポイントがあります。IoT Hub has an endpoint specifically for devices to request a SAS URI for storage to upload a file. ファイルのアップロード プロセスを開始するために、デバイスは以下の JSON 本文を含む POST 要求を {iot hub}.azure-devices.net/devices/{deviceId}/files に送信します。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 Hub は次のデータを返します。デバイスはこのデータを使用してファイルをアップロードします。IoT Hub returns the following data, which the device uses to upload the file:

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

非推奨: ファイルのアップロードの初期化Deprecated: initialize a file upload with a GET

注意

このセクションでは、IoT Hub から 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 Hub には、ファイルのアップロードをサポートする 2 つの REST エンドポイントがあります。1 つは、ストレージの SAS URI を取得します。もう 1 つは、アップロードの完了を IoT Hub に通知します。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 Hub は以下を返します。The IoT hub returns:

  • アップロードするファイルに固有の SAS URIA SAS URI specific to the file to be uploaded.

  • アップロードの完了後に使用される関連付け IDA correlation ID to be used once the upload is completed.

IoT Hub へのファイルのアップロード完了の通知Notify IoT Hub of a completed file upload

デバイスは、Azure Storage SDK を使用してストレージにファイルをアップロードします。The device uploads the file to storage using the Azure Storage SDKs. アップロードが完了すると、デバイスは、次の JSON 本文を含む POST 要求を {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications に送信します。When the upload is complete, the device sends a POST request to {iot hub}.azure-devices.net/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 は、ストレージに対するファイルのアップロードの状態であり、statusDescriptionstatusCode に対応します。The 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 Hub に通知すると、IoT Hub によって通知メッセージが生成されます。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 Hub はサービス向けエンドポイント ( /messages/servicebound/fileuploadnotifications) 経由でメッセージとしてファイルのアップロード通知を配信します。As explained in Endpoints, IoT Hub delivers file upload notifications through a service-facing endpoint (/messages/servicebound/fileuploadnotifications) as messages. ファイルのアップロード通知の受信セマンティクスは cloud-to-device メッセージの場合と同様であり、メッセージのライフ サイクルも同じです。The receive semantics for file upload notifications are the same as for cloud-to-device messages and have the same message life cycle. ファイルのアップロード通知エンドポイントから取得した各メッセージは、次のプロパティを持つ 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.windows.net/{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. 最大 48 時間の ISO_8601 書式による間隔 (最小 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.

IoT ハブ上でこれらのプロパティを設定するには、Azure portal、Azure CLI、または PowerShell を使用します。You can set these properties on your IoT hub using the Azure portal, Azure CLI, or PowerShell. 詳細については、ファイル アップロードの構成に関する記事を参照してください。To learn how, see the topics under Configure file upload.

参考資料Additional reference material

IoT Hub 開発者ガイド内の他の参照トピックは次のとおりです。Other reference topics in the IoT Hub developer guide include:

  • IoT Hub エンドポイント: 実行時および管理操作用のさまざまな IoT Hub エンドポイントについて説明します。IoT Hub endpoints describes the various IoT hub endpoints for run-time and management operations.

  • スロットルとクォータ: IoT Hub サービスに適用されるクォータとスロットルの動作について説明します。Throttling and quotas describes the quotas and throttling behaviors that apply to the IoT Hub service.

  • Azure IoT device SDK とサービス SDK: IoT Hub とやりとりするデバイスとサービス アプリの両方を開発する際に使用できるさまざまな言語の SDK を紹介します。Azure IoT device and service SDKs lists the various language SDKs you can use when you develop both device and service apps that interact with IoT Hub.

  • IoT Hub のクエリ言語: IoT Hub からデバイス ツインとジョブに関する情報を取得する際に使用できるクエリ言語について説明します。IoT Hub query language describes the query language you can use to retrieve information from IoT Hub about your device twins and jobs.

  • IoT Hub の MQTT サポート: IoT Hub での MQTT プロトコルのサポートについて詳しく説明します。IoT Hub MQTT support provides more information about IoT Hub support for the MQTT protocol.

次のステップNext steps

IoT Hub を使用してデバイスからファイルをアップロードする方法を理解できたら、次の IoT Hub 開発者ガイドのトピックも参考にしてください。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 Hub のチュートリアルをご覧ください。To try out some of the concepts described in this article, see the following IoT Hub tutorial: