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

[アーティクル]
03/09/2023

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

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

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

重要

X.509 証明機関 (CA) 認証を使用するデバイスのファイルアップロード機能はパブリックプレビュー段階であり、プレビューモードを有効にする必要があります。これは、Azure デバイスプロビジョニングサービスで x.509 拇印認証または x.509 証明書の構成証明を使用するデバイスで一般提供されています。 IoT Hub での X.509 認証の詳細については、「サポートされている X.509 証明書」を参照してください。

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

IoT ハブは、そのハブで事前構成された BLOB コンテナーと Azure ストレージアカウントの共有アクセス署名 (SAS) URI をアップロードごとに接続デバイスに提供することで、それらからのファイルアップロードを支援します。 IoT Hub によるファイルアップロードの使用には、自分の IoT ハブでの Azure ストレージアカウントと BLOB コンテナーの事前構成、デバイスからのファイルのアップロード、バックエンドサービスへのファイルアップロードの完了通知 (省略可能) の 3 つのパートがあります。

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

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

デバイスが IoT ハブによるファイルアップロードを開始します。これは要求で BLOB の名前を渡し、応答として SAS URI と関連付け ID を受け取ります。 SAS URI には、要求された BLOB コンテナーの BLOB への読み取り/書き込みアクセス許可をデバイスに付与する、Azure ストレージの SAS トークンが含まれています。詳細については、「デバイス: ファイルのアップロードを開始する」を参照してください。
デバイスにより、SAS URI を使用して Azure Blob Storage API が安全に呼び出され、ファイルが BLOB コンテナーにアップロードされます。詳細については、「デバイス: Azure Storage API を使用してファイルをアップロードする」を参照してください。
ファイルのアップロードが完了すると、デバイスは、アップロードを開始したときに 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 ストレージのドキュメントにある「ストレージアカウントの作成」を参照してください。ストレージアカウントを用意できたら、Azure Blob Storage のクイックスタートで、BLOB コンテナーを作成する方法について確認しましょう。既定では、Azure IoT Hub はキーベースの認証を使用して Azure Storage に接続し、認証します。ユーザー割り当てまたはシステム割り当てのマネージド ID を構成して、Azure Storage で Azure IoT Hub を認証することもできます。マネージド ID は、Microsoft Entra ID で自動的に管理される ID を安全な方法で Azure サービスに提供します。マネージド ID を構成する方法については、「IoT Hub でのマネージド ID のサポート」の「マネージド ID を使用してファイルのアップロードを構成する」セクションを参照してください。

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

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

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

次の設定では、ストレージアカウントとコンテナーを自分の IoT ハブに関連付けて、Azure ストレージによる IoT ハブの認証方法を制御します。これらの設定は、Azure ストレージによるデバイスの認証方法に影響しません。デバイスは常に、IoT Hub から取得した SAS URI で示される SAS トークンによって認証されます。

プロパティ	説明	範囲と既定値
storageEndpoints.$default.authenticationType	Azure ストレージによる IoT Hub の認証方法を制御します。	keyBased と identityBased の値を設定できます。既定値は keyBased です。
storageEndpoints.$default.connectionString	ファイルアップロードに使用する Azure ストレージアカウントへの接続文字列。	既定値は空の文字列です。
storageEndpoints.$default.containerName	ファイルのアップロード先となるコンテナーの名前。	既定値は空の文字列です。
storageEndpoints.$default.identity	ID ベースの認証に使用するマネージド ID。	システム割り当てマネージド ID に `[system]`、ユーザー割り当てマネージド ID にリソース ID を値として設定できます。この値はキーベースの認証には使用されません。既定値は null 値です。

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

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

プロパティ	説明	範囲と既定値
storageEndpoints.$default.ttlAsIso8601	IoT Hub によって生成される SAS URI の既定の TTL。	最大 48 時間の ISO_8601 書式による間隔 (最小 1 分)。既定値: 1 時間。

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

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

プロパティ	説明	範囲と既定値
enableFileUploadNotifications	ファイルのアップロード通知をファイル通知エンドポイントに書き込むかどうかを制御します。	ブール値。既定値は False です。
fileNotifications.ttlAsIso8601	ファイルのアップロード通知の既定の TTL。	最大 48 時間の ISO_8601 書式による間隔 (最小 1 分)。既定値: 1 時間。
fileNotifications.lockDuration	ファイルのアップロード通知キューのロック期間。	5 から 300 秒です。既定値: 60 秒。
fileNotifications.maxDeliveryCount	ファイルのアップロード通知キューの最大配信数。	1 ～ 100。既定値: 10。

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

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

ハウツーガイド	デバイス SDK の例	サービス SDK の例
.NET	はい	はい
Java	はい	はい
Node.js	はい	はい
Python	はい	いいえ (サポートされていません)

注意

C デバイス SDK では、ファイルアップロードを実行するためにデバイスクライアントで 1 回の呼び出しを使用します。詳細については、「IoTHubDeviceClient_UploadToBlobAsync()」と「IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync()」を参照してください。これらの関数では、ファイルアップロードのすべての段階 (アップロードの開始、Azure ストレージへのファイルのアップロード、完了時の IoT Hub への通知) を 1 回の呼び出しで実行します。この相互作用は、これらの関数では Azure Storage API への呼び出しを実行するため、デバイスは IoT Hub との通信に使用する任意のプロトコルに加えて、HTTPS 経由で Azure ストレージと通信できる必要もあることを意味します。

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

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

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

{
    "blobName":"myfile.txt"
}

プロパティ	説明
blobName	SAS URI を生成する対象となる BLOB の名前。

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

プロパティ	説明
correlationId	デバイスが IoT Hub へのファイルアップロード完了通知を送信する際に使用する識別子。
hostName	IoT ハブで構成されたストレージアカウントの Azure ストレージホスト名
containerName	IoT ハブで構成された BLOB コンテナーの名前。
blobName	BLOB が保存されるコンテナー内の場所。名前には次の形式が使用されます。`{device ID of the device making the request}/{blobName in the request}`
sasToken	Azure ストレージの BLOB に対する読み取り/書き込みアクセス権を付与する SAS トークン。このトークンは IoT Hub によって生成、署名されます。

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

関連付け 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"
}

プロパティ	説明
correlationId	最初の SAS URI 要求で受け取った関連付け ID。
isSuccess	ファイルのアップロードが成功したかどうかを示すブール値。
statusCode	ファイルアップロードの状態コードを表す整数。通常は 3 桁の数字です (200 や 201 など)。
statusDescription	ファイルのアップロード状態の説明。

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

ファイルのアップロード通知が構成されている場合は、バックエンドサービスへのファイルのアップロード通知をトリガーします。
ファイルアップロードに関連付けられたリソースをリリースします。 IoT Hub が通知を受け取らない場合、アップロードに関連付けられた SAS URI の有効期限 (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"
}

プロパティ	説明
enqueuedTimeUtc	通知が作成された日時を示すタイムスタンプ。
deviceId	ファイルをアップロードしたデバイスのデバイス ID。
blobUri	アップロードされたファイルの URI。
blobName	アップロードされたファイルの名前。名前には次の形式が使用されます。`{device ID of the device}/{name of the blob}`
lastUpdatedTime	ファイルが最後に更新された日時を示すタイムスタンプ。
blobSizeInBytes	アップロードされたファイルのサイズをバイト単位で表す整数。

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

次のステップ

ファイルアップロードのハウツーガイド
IoT Hub でファイルアップロードを構成する方法
IoT Hub でマネージド ID を構成する方法
Azure Blob Storage のドキュメント
Azure IoT device SDK とサービス SDK: IoT Hub とやりとりするデバイスとサービスアプリの両方を開発する際に使用できるさまざまな言語の SDK を紹介します。