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

多くのシナリオでは、IoT Hub が受け付ける比較的小さな device-to-cloud メッセージに自分のデバイス データを簡単にマップすることはできません。 たとえば、動画などの大きなメディア ファイルの送信や、大きなテレメトリ バッチの送信などがあり、断続的に接続されるデバイスによってアップロードされるか、帯域幅を節約するために集約して圧縮されるかします。

デバイスから大きいファイルをアップロードする必要がある場合も、IoT Hub のセキュリティと信頼性を利用できます。 ただし、IoT Hub は、それ自体を介してメッセージを仲介するのではなく、関連付けられている Azure ストレージ アカウントへのディスパッチャーとして機能します。 さらに IoT Hub は、デバイスがファイルのアップロードを完了した際にバックエンド サービスに通知を提供します。

報告されるプロパティ、device-to-cloud メッセージ、ファイルのアップロードの使用場面を判断するうえでヘルプが必要な場合は、「device-to-cloud 通信に関するガイダンス」を参照してください。

ファイルのアップロードの概要

IoT ハブは、そのハブからファイルのアップロード用に構成された BLOB コンテナーと Azure ストレージ アカウントの共有アクセス署名 (SAS) URI をアップロードごとに接続デバイスに提供して、それらからのファイル アップロードを支援します。 IoT Hub によるファイル アップロードの使用には、次の 3 つの部分があります。

• お使いの IoT ハブで Azure ストレージ アカウントと BLOB コンテナーを構成する。
• デバイスからファイルをアップロードする。
• 必要に応じて、完了したファイルのアップロードをバックエンド サービスに通知する。

ファイルのアップロード機能を使用するには、Azure ストレージ アカウントと BLOB コンテナーを自分の IoT ハブに関連付けておく必要があります。 また、IoT Hub での Azure ストレージの認証方法、IoT ハブがデバイスに渡す SAS URI の有効期限 (TTL)、バックエンド サービスへのファイル アップロード通知を制御する設定を構成することもできます。 詳細については、「Azure ストレージ アカウントと IoT Hub の関連付け」を参照してください。

デバイスは 3 ステップのプロセスに沿って、関連付けられた BLOB コンテナーにファイルをアップロードします。

1. デバイスが IoT ハブによるファイル アップロードを開始します。 これは要求で BLOB の名前を渡し、応答として SAS URI と関連付け ID を受け取ります。 SAS URI には、要求された BLOB コンテナーの BLOB への読み取り/書き込みアクセス許可をデバイスに付与する、Azure ストレージの SAS トークンが含まれています。 詳細については、「デバイス: ファイルのアップロードを開始する」を参照してください。

2. デバイスにより、SAS URI を使用して Azure Blob Storage API が安全に呼び出され、ファイルが BLOB コンテナーにアップロードされます。 詳細については、「デバイス: Azure Storage API を使用してファイルをアップロードする」を参照してください。

3. ファイルのアップロードが完了すると、デバイスは、アップロードを開始したときに IoT Hub から受け取った関連付け ID を使用して、完了状態を IoT ハブに通知します。 詳細については、「デバイス: ファイルのアップロードの完了を IoT Hub に通知する」を参照してください。

バックエンド サービスは、IoT ハブのサービス向けファイル アップロード通知エンドポイントで、ファイルのアップロードの通知にサブスクライブできます。 これらの通知を自分の IoT ハブで有効にすると、デバイスがファイルのアップロード完了をハブに通知するたびに、このエンドポイントで IoT ハブによって通知が提供されます。 サービスはこれらの通知を利用して、BLOB データに対する追加の処理をトリガーできます。 詳細については、「サービス: ファイルのアップロード通知」を参照してください。

Azure IoT デバイスおよびサービス SDK では、ファイルのアップロードを完全にサポートしています。 詳細については、「SDK を使用したファイルのアップロード」を参照してください。

ファイル アップロードのクォータと制限

IoT Hub では、一定の期間内に開始できるファイル アップロードの回数に調整制限が課されます。 そのしきい値は、SKU とお客様の IoT ハブのユニット数に基づきます。 さらに、一度にアクティブにできる同時ファイル アップロードは各デバイスで 10 件に制限されています。 詳細については、IoT Hub のクォータと調整に関するページを参照してください。

Azure ストレージ アカウントと IoT Hub の関連付け

ファイル アップロード機能を使用するには、Azure ストレージ アカウントと BLOB コンテナーを自分の IoT ハブに関連付ける必要があります。 自分の IoT ハブに登録されているデバイスからのファイル アップロードはすべて、このコンテナーに送られます。 IoT ハブでストレージ アカウントと BLOB コンテナーを構成するには、「Azure Portal を使用して IoT Hub ファイルのアップロードを構成する」、「Azure CLI を使用して IoT Hub ファイルのアップロードを構成する」、または「PowerShell を使用して IoT Hub ファイルのアップロードを構成する」を参照してください。 IoT Hub の管理 API を使用して、ファイル アップロードをプログラムで構成することもできます。

既定では、Azure IoT Hub はキーベースの認証を使用して Azure Storage に接続し、認証します。 ユーザー割り当てまたはシステム割り当てのマネージド ID を構成して、Azure Storage で Azure IoT Hub を認証することもできます。 マネージド ID は、Microsoft Entra ID で自動的に管理される ID を安全な方法で Azure サービスに提供します。

ファイルのアップロードは Azure Storage のファイアウォール設定に従います。 認証構成に従って、デバイスが Azure ストレージと通信できることを確認する必要があります。

この他に、ファイル アップロードの動作とファイルのアップロード通知を制御する設定がいくつかあります。 以下のセクションでは、使用可能な設定をすべて示しています。 ファイル アップロードの構成に Azure portal、Azure CLI、PowerShell、管理 API のどれを使用するかによって、これらの設定の一部が使用できない場合があります。 ファイル アップロードの完了時にバックエンド サービスに通知を送信したい場合は、enableFileUploadNotifications の設定を行うようにしてください。

IoT Hub のストレージと認証の設定

次の設定では、ストレージ アカウントとコンテナーを自分の IoT ハブに関連付けて、Azure ストレージによる IoT ハブの認証方法を制御します。 これらの設定は、Azure ストレージによるデバイスの認証方法に影響しません。 その場合も、SAS URI を使用してデバイスをストレージに接続する必要があります。 現在、SAS URI は接続文字列を使用して生成されます。

ID ベースの認証を使用するようにファイル アップロードを構成する方法については、「マネージド ID を使用してファイルのアップロードを構成する」を参照してください。

ファイル アップロードの設定

次の設定では、デバイスからのファイル アップロードを制御します。

ファイル アップロードの通知設定

次の設定では、バックエンド サービスへのファイル アップロード通知を制御します。

SDK を使用したファイルのアップロード

次のハウツー ガイドでは、Azure IoT デバイスおよびサービス SDK を使用してファイルをアップロードするための完全で詳細な手順を説明しています。 このガイドでは、Azure portal を使用してストレージ アカウントを IoT ハブに関連付ける方法が示されています。 また、このガイドにはコード スニペットが含まれており、アップロードをガイドするサンプルを紹介します。

デバイス: ファイルのアップロードを開始する

デバイスは、ファイル アップロード SAS URI の作成 REST API、またはいずれかのデバイス SDK の同等の API を呼び出して、ファイル アップロードを開始します。

サポートされているプロトコル: HTTPS
エンドポイント: {iot hub}.azure-devices.net/devices/{deviceId}/files
メソッド: POST

{
    "blobName":"myfile.txt"
}

IoT Hub は、デバイスが Azure ストレージによる認証に使用できる関連付け ID と SAS URI の要素で応答します。 この応答は、調整制限とターゲット IoT ハブのデバイス単位のアップロード制限に従います。

{
    "correlationId":"MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "hostName":"contosostorageaccount.blob.core.windows.net",
    "containerName":"device-upload-container",
    "blobName":"mydevice/myfile.txt",
    "sasToken":"?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw"
}

応答を受け取ったデバイスの動作:

• 関連付け ID を保存して、アップロード完了時に IoT ハブへのファイル アップロード完了通知に含めます。

• その他のプロパティを使用して、Azure ストレージによる認証に使用される BLOB の SAS URI を構築します。 SAS URI には、要求された BLOB のリソース URI と SAS トークンが含まれています。 次の形式を取る: https://{hostName}/{containerName}/{blobName}{sasToken}(応答のsasTokenプロパティには先頭に '?' 文字が含まれます)。中かっこは含まれません。

  たとえば、前のサンプルで返される値の場合、SAS URI は https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw です。

  SAS URI と SAS トークンの詳細については、Azure ストレージのドキュメントにある「サービス SAS を作成する」を参照してください。

デバイス: Azure Storage API を使用してファイルをアップロードする

デバイスによって Azure Blob Storage REST API または同等の Azure Storage SDK API が使用され、Azure ストレージ内の BLOB にファイルがアップロードされます。

サポートされているプロトコル: HTTPS

次の例は、小さなブロック BLOB を作成または更新する Put Blob 要求を示しています。 この要求に使用される URI が、前のセクションで IoT Hub によって返された SAS URI であることに注目してください。 x-ms-blob-type ヘッダーは、この要求がブロック BLOB 用であることを示しています。 要求が成功すると、Azure ストレージは 201 Created を返します。

PUT https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw HTTP/1.1
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Host: contosostorageaccount.blob.core.windows.net
x-ms-blob-type: BlockBlob

hello world

Azure Storage API の操作については、この記事の対象外です。 このセクションで前にリンクがあった Azure Blob Storage REST API に加えて、作業の開始に役立つ次のドキュメントを確認できます。

• Azure ストレージでの BLOB の操作について詳しくは、「Azure Blob Storage のドキュメント」を参照してください。

• Azure Storage クライアント SDK を使用して BLOB をアップロードする方法の詳細については、「Azure Blob Storage API リファレンス」を参照してください。

デバイス: ファイルのアップロードの完了を IoT Hub に通知する

デバイスはファイル アップロードの完了時に、ファイル アップロード ステータスの更新 REST API、またはいずれかのデバイス SDK の同等の API を呼び出します。 アップロードが成功したか失敗したかにかかわらず、デバイスは IoT Hub によってファイルのアップロード状態を更新する必要があります。

サポートされているプロトコル: HTTPS
エンドポイント: {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
メソッド: POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}

デバイスからファイル アップロード完了通知を受け取った IoT Hub の動作:

• ファイルのアップロード通知が構成されている場合は、バックエンド サービスへのファイルのアップロード通知をトリガーします。

• ファイル アップロードに関連付けられたリソースをリリースします。 IoT Hub は、通知を受け取らない場合、アップロードに関連付けられた SAS URI の Time to Live (TTL) が切れるまでリソースを維持し続けます。

サービス: ファイルのアップロード通知

自分の IoT ハブでファイルのアップロード通知が有効になっている場合、その IoT ハブはファイルのアップロード完了通知をデバイスから受け取ったときに、バックエンド サービス用の通知メッセージを生成します。 IoT Hub はこれらのファイルのアップロード通知をサービス向けエンドポイント経由で提供します。 ファイルのアップロード通知の受信セマンティクスは cloud-to-device メッセージの場合と同様であり、メッセージのライフ サイクルも同じです。 サービス SDK によって、ファイルのアップロード通知を処理する API が公開されます。

サポートされているプロトコル: AMQP、AMQP-WS
エンドポイント: {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
メソッド: GET

ファイルのアップロード通知エンドポイントから取得される各メッセージは JSON レコードです。

{
    "deviceId":"mydevice",
    "blobUri":"https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt",
    "blobName":"mydevice/myfile.txt",
    "lastUpdatedTime":"2021-07-31T00:26:50+00:00",
    "blobSizeInBytes":11,
    "enqueuedTimeUtc":"2021-07-31T00:26:51.5134008Z"
}

サービスで通知を使用してアップロードを管理できます。 たとえば、BLOB データの独自の処理をトリガーしたり、他の Azure サービスを使用して BLOB データの処理をトリガーしたりできるほか、後のレビューのためにファイルのアップロード通知をログすることができます。

次のステップ

• IoT Hub でファイル アップロードを構成する方法

• IoT Hub でマネージド ID を構成する方法