チュートリアル: IoT Hub メッセージ ルーティングを使用してデバイス データを Azure Storage に送信する

Azure IoT Hub のメッセージ ルーティングを使用して、IoT デバイスから Blob Storage、Service Bus キュー、Service Bus トピック、Event Hubs などの Azure サービスにテレメトリ データを送信します。 すべての IoT ハブには、Event Hubs との互換性がある、既定の組み込みのエンドポイントがあります。 ルーティング クエリを定義することで、カスタム エンドポイントを作成し、他の Azure サービスにメッセージをルーティングすることもできます。 IoT ハブに到着した各メッセージは、ルーティング クエリが一致するすべてのエンドポイントにルーティングされます。 メッセージが、定義されているルーティング クエリのいずれとも一致しない場合、既定のエンドポイントにルーティングされます。

このチュートリアルでは、以下のタスクを実行します。

• IoT ハブを作成し、デバイス メッセージを送信します。
• ストレージ アカウントを作成します。
• ストレージ アカウントのカスタム エンドポイントを作成し、IoT ハブからメッセージをルーティングします。
• ストレージ アカウント BLOB 内のデバイス メッセージを表示します。

前提条件

• Azure サブスクリプション。 Azure サブスクリプションをお持ちでない場合は、開始する前に 無料アカウント を作成してください。

• Azure サブスクリプション内の IoT ハブ。 ハブがまだない場合は、「IoT ハブの作成」の手順に従うことができます。

• このチュートリアルでは、C# 向けの Azure IoT SDK からのサンプル コードを使用します。

  • SDK リポジトリをダウンロードするか、開発用マシンに複製します。
  • 開発用マシン上に .NET Core 3.0.0 以降をインストールします。 dotnet --version を実行してバージョンを確認し、必要に応じて .NET をダウンロードします。

• ポート 8883 がファイアウォールで開放されていることを確認してください。 このチュートリアルのサンプルでは、ポート 8883 を介して通信する MQTT プロトコルを使用しています。 このポートは、企業や教育用のネットワーク環境によってはブロックされている場合があります。 この問題の詳細と対処方法については、「IoT Hub への接続 (MQTT)」を参照してください。

• 必要に応じて、Azure IoT Explorer をインストールします。 このツールは、メッセージが IoT ハブに到着したときのメッセージの監視に役立ちます。 この記事では、Azure IoT Explorer を使用します。

Azure Portal

Azure portal には、その他の前提条件はありません。

Azure CLI

• Azure Cloud Shell で Bash 環境を使用します。 詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。

  

• CLI リファレンス コマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。

  • ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、Azure CLI でのサインインに関するページを参照してください。

  • 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。

  • az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。 最新バージョンにアップグレードするには、az upgrade を実行します。

デバイスを登録し、IoT Hub にメッセージを送信する

IoT ハブに新しいデバイスを登録します。

重要

この記事では、Shared Access Signature (対称キー認証とも呼ばれます) を使用してデバイスを接続する手順について説明しています。 この認証方法はテストと評価には便利ですが、デバイスの認証方法としては、X.509 証明書を使用する方が安全です。 詳細については、「セキュリティのベスト プラクティス」の「接続のセキュリティ」を参照してください。>

Azure Portal

1. Azure Portal にサインインし、IoT Hub に移動します。

2. メニューの [デバイス管理] セクションから [デバイス] を選択します。

3. [デバイスの追加] を選択します。

   

4. デバイス ID を指定し、[保存] を選択します。

5. 新しいデバイスがデバイスの一覧に表示されます。 そうでない場合は、ページを更新します。 デバイス ID を選択し、[デバイスの詳細] ページを開きます。

6. デバイス キーの 1 つをコピーして保存します。 この値を使用して、シミュレートされたデバイス テレメトリ メッセージを生成するサンプル コードを構成します。

   

Azure CLI

ヒント

このチュートリアルで使用する CLI コマンドの多くは、同じパラメーターを使用します。 便宜上、必要に応じて呼び出すことができるローカル変数を定義して頂きます。 すべてのコマンドを同じセッションで実行してください。そうしないと、変数を再定義する必要があります。

1. IoT ハブとデバイスの変数を定義します。

   IOTHUB_NAME: このプレースホルダーを IoT ハブの名前に置き換えます。

   DEVICE_NAME: このプレースホルダーを、このチュートリアルでデバイスに使用する任意の名前に置き換えます。

   hubName=IOTHUB_NAME
   deviceName=DEVICE_NAME
   

2. CLI シェルで、az iot hub device-identity create コマンドを実行します。 このコマンドで、デバイス ID が作成されます。

   az iot hub device-identity create --device-id $deviceName --hub-name $hubName
   

3. デバイス ID の出力から、囲みの引用符を除いた primaryKey 値をコピーして保存します。 この値を使用して、シミュレートされたデバイス テレメトリ メッセージを生成するサンプル コードを構成します。

デバイス ID とキーが用意されたので、サンプル コードを使用して IoT Hub へのデバイス テレメトリ メッセージの送信を開始します。

ヒント

このチュートリアルの Azure CLI の手順に従っている場合は、別のセッションでサンプル コードを実行します。 これにより、CLI の残りの手順を実行している間にサンプル コードの実行を継続できます。

1. 前提条件の一部として実行しなかった場合は、GitHub から C# リポジトリの Azure IoT SDK を今すぐにダウンロードまたは複製してください。

2. SDK をダウンロードまたはクローンしたフォルダーから、azure-iot-sdk-csharp\iothub\device\samples\how to guides\HubRoutingSample フォルダーに移動します。

3. Azure IoT C# SDK と HubRoutingSample.csproj ファイルに指定されている必要な依存関係をインストールします。

   dotnet restore
   

4. 任意のエディターで Parameters.cs ファイルをオープンします。 このファイルには、サンプルでサポートされているパラメーターが示されます。 この記事では、サンプルを実行するときに、PrimaryConnectionString パラメーターのみを使用します。 このファイルのコードを確認します。 変更は不要です。

5. 次のコマンドを使用してサンプル コードをビルドし、実行します。

   <myDevicePrimaryConnectionString> を IoT ハブ内のデバイスのプライマリ接続文字列に置き換えてください。

   dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
   

6. メッセージが IoT Hub に送信されるときに、出力用に印刷されたメッセージが表示されるようになります。 チュートリアルの間は、このプログラムを実行したままにします。

メッセージを表示するように IoT Explorer を構成する

IoT Hub に接続し、組み込みエンドポイントに到着したメッセージを読み取るように IoT Explorer を構成します。

まず、IoT ハブの接続文字列を取得します。

Azure Portal

1. Azure Portal で、お使いの IoT ハブに移動します。

2. メニューの [セキュリティ設定] セクションから [共有アクセス ポリシー] を選択します。

3. iothubowner ポリシーを選択します。

   

4. プライマリ接続文字列をコピーします。

   

Azure CLI

1. az iot hub connection-string show コマンドを実行します。

   az iot hub connection-string show --hub-name $hubName
   

2. 囲み引用符無しで接続文字列をコピーします。

次に、その接続文字列を使用して、IoT ハブ用に IoT Explorer を構成します。

1. 開発用マシンで IoT Explorer を開きます。

2. [接続の追加] を選択します。

   

3. ハブの接続文字列をテキスト ボックスに貼り付けます。

4. [保存] を選択します。

5. IoT ハブに接続すると、デバイスの一覧が表示されます。 このチュートリアル用に作成したデバイス ID を選択します。

6. [テレメトリ] を選択します。

7. デバイスが引き続き実行されている状態で、[スタート] を選択します。 デバイスが実行されていない場合、テレメトリは表示されません。

   

8. デバイスから届くメッセージが表示され、最新のものが上部に表示されます。

   

   受信メッセージをしばらく見て、通常、ストレージ、クリティカルの 3 種類のメッセージ表示を確認します。 これを確認したら、デバイスを停止できます。

これらのメッセージはすべて、IoT ハブの既定の組み込みエンドポイントに到着します。 次のセクションでは、カスタム エンドポイントを作成し、メッセージのプロパティに基づいて、これらのメッセージの一部をストレージにルーティングします。 これらのメッセージは、IoT Explorer に表示されなくなります。メッセージは、IoT ハブ内の他のルートと一致しない場合にのみ組み込みエンドポイントに送信されるためです。

メッセージ ルーティングを設定する

シミュレートされたデバイスからメッセージに添付されたプロパティに基づいて、メッセージを異なるリソースにルーティングします。 カスタム ルーティングされないメッセージは、既定のエンドポイント (メッセージ/イベント) に送信されます。

このチュートリアルのサンプル アプリは、IoT ハブに送信する各メッセージにレベル プロパティを割り当てます。 各メッセージには、 通常、 ストレージ、または クリティカルのレベルがランダムに割り当てられます。

最初の手順では、データのルーティング先のエンドポイントを設定します。 2 番目の手順では、そのエンドポイントを使用するメッセージ ルートを設定します。 ルーティングの設定後、ポータルでエンドポイントとメッセージ ルートを表示できます。

ストレージ アカウントの作成

Azure Storage アカウントとそのアカウント内にコンテナーを作成します。このアカウントには、そのアカウントにルーティングされるデバイス メッセージが保持されます。

Azure Portal

1. Azure portal で、[ストレージ アカウント] を検索します。

2. ［作成］ を選択します

3. ストレージ アカウントには、下の値を指定します。

   パラメーター	値
   サブスクリプション	IoT Hub を含む同じサブスクリプションを選択します。
   リソース グループ	IoT Hub を含む同じリソース グループを選択します。
   Storage account name (ストレージ アカウント名)	グローバルに一意の名前を [ストレージ アカウント] に指定します。
   パフォーマンス	既定値の [標準] をそのまま使用します。

   

4. [確認と作成] を選択すると、他のすべての既定値をそのまま使用できます。

5. 検証が完了した後、 [作成] を選択します。

6. デプロイが完了したら、[リソースに移動] を選択します。

7. [ストレージ アカウント] メニューの [データ ストレージ] セクションから [コンテナー] を選択します。

8. [+ コンテナー] を選択して、新しいコンテナーを作成します。

   

9. コンテナーの名前を入力し、[作成] を選択します。

Azure CLI

1. ストレージ アカウントとコンテナーの変数を定義します。

   GROUP_NAME: このプレースホルダーを IoT ハブを含むリソース グループの名前に置き換えます。

   STORAGE_NAME: このプレースホルダーをストレージ アカウントの名前に置き換えます。 ストレージ アカウント名は小文字で、グローバルに一意である必要があります。

   CONTAINER_NAME: このプレースホルダーをコンテナーの名前に置き換えます。

   resourceGroup=GROUP_NAME
   storageName=STORAGE_NAME
   containerName=CONTAINER_NAME
   

2. az storage account create コマンドを使用して、汎用の標準汎用 v2 ストレージ アカウントを作成します。

   az storage account create --name $storageName --resource-group $resourceGroup
   

3. az storage container create を使用して、ストレージ アカウントにコンテナーを追加します。

   az storage container create --auth-mode login --account-name $storageName --name $containerName
   

ストレージ アカウントへのルーティング

ストレージ アカウントへのルーティングを設定します。 このセクションでは、作成したストレージ アカウントを指す新しいエンドポイントを定義します。 次に、 [level] プロパティが [strage] に設定されているメッセージをフィルター処理するルートを作成し、それらを ストレージ エンドポイントにルーティングします。

Note

データは、既定の Apache Avro 形式または JSON のいずれかで Blob Storage に書き込むことができます。

エンコード形式は、BLOB ストレージ エンドポイントの構成時にのみ設定できます。 既に設定されているエンドポイントの形式は変更できません。 JSON エンコードを使用する場合は、メッセージのシステム プロパティで contentType を JSON に設定し、contentEncoding を UTF-8 に設定する必要があります。

BLOB ストレージ エンドポイントの使用に関する詳細については、ストレージへのルーティングに関するガイダンスを参照してください。

重要

この記事では、Shared Access Signature を使用してサービスに接続する手順について説明しています。 この認証方法はテストと評価には便利ですが、サービスに対する認証方法としては、Microsoft Entra ID またはマネージド ID を使用する方が安全です。 詳細については、「セキュリティのベスト プラクティス」の「クラウドのセキュリティ」 を参照してください。>

Azure Portal

1. Azure portal で IoT Hub に移動します。

2. リソース メニューの [ハブ設定] で、[メッセージ ルーティング] を選択し、[追加] を選択します。

   

3. [エンドポイント] タブで、次の情報を指定してストレージ エンドポイントを作成します。

   パラメーター	値
   [エンドポイントの種類]	[ストレージ] を選択します。
   [エンドポイント名]	このエンドポイントの一意の名前を指定します。
   [Azure Storage コンテナー]	[コンテナーを選択します] を選択します。 プロンプトに従って、前のセクションで作成したストレージ アカウントとコンテナーを選択します。
   [エンコード]	[JSON] を選択します。 このフィールドが淡色表示されている場合、ストレージ アカウント リージョンは JSON をサポートしません。 その場合は、既定の [AVRO] で続行します。

   

4. 残りのパラメーターの既定値をそのまま使用し、[作成 + 次へ] を選択します。

5. [ルート] タブで、次の情報を指定して、作成したストレージ エンドポイントを指すルートを作成します。

   パラメーター	値
   名前	ルートの名前を作成します。
   データ ソース	ドロップダウン リストから [デバイス テレメトリ メッセージ] が選択されていることを確認します。
   ルートの有効化	このフィールドがオンにされていることを確認します。
   ルーティング クエリ	クエリ文字列として、「level="storage"」と入力します。

   

6. [エンリッチメントの作成 + スキップ] を選択します。

Azure CLI

1. エンドポイントとルート コマンドに必要な変数を構成します。

   ENDPOINT_NAME: ストレージ コンテナーを表すエンドポイントの名前を指定します。

   ROUTE_NAME: ストレージ エンドポイントのメッセージをフィルター処理するルートの名前を指定します

   endpointName=ENDPOINT_NAME
   routeName=ROUTE_NAME
   

2. az iot hub message-endpoint create コマンドを使用して、前のセクションで作成したストレージ コンテナーを指すカスタム エンドポイントを作成します。

   az iot hub message-endpoint create storage-container \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. az iot hub message-route create コマンドを使用して、level=storage の任意のメッセージをストレージ コンテナー エンドポイントに渡すルートを作成します。

   az iot hub message-route create \
     --route-name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source-type devicemessages \
     --endpoint-name $endpointName \
     --enabled true \
     --condition 'level="storage"'
   

ルーティングされたメッセージを表示する

ルートが IoT Hub で作成され、有効になると、そのクエリ条件を満たすメッセージのストレージ エンドポイントへのルーティングが直ちに開始されます。

IoT Explorer を使用して組み込みエンドポイントを監視する

開発用マシンの IoT Explorer セッションに戻ります。 IoT Explorer が IoT ハブの組み込みエンドポイントを監視することを思い出してください。 つまり、作成したカスタム ルートによってルーティングされていないメッセージのみが表示されます。

コードを実行して、サンプルをもう一度開始します。 受信メッセージをしばらく監視すると、level が normal または critical に設定されているメッセージのみが表示されます。

ストレージ コンテナー内のメッセージを表示する

メッセージがストレージ コンテナーに到着していることを確認します。

1. Azure portal のストレージ アカウントに移動します。

2. メニューの [データ ストレージ] セクションから [コンテナー] を選択します。

3. このチュートリアル用に作成したコンテナーを選択します。

4. IoT ハブの名前を持つフォルダーが存在する必要があります。 .json ファイルが表示されるまで、ファイル構造をドリルダウンします。

   

5. JSON ファイルを選択し、[ダウンロード] を選択して JSON ファイルをダウンロードします。 level プロパティが storage に設定されているデバイスからのメッセージが含まれていることを確認します。

6. サンプルの実行を停止します。

リソースをクリーンアップする

このチュートリアルで使用した Azure リソースをすべて削除するには、リソース グループを削除します。 これにより、そのグループ内に含まれているすべてのリソースも削除されます。 リソース グループ全体を削除しない場合は、Azure portal を使用して個々のリソースを見つけて削除します。

次のチュートリアルに進む場合は、ここで作成したリソースを残してください。

Azure Portal

1. Azure portal で、このチュートリアルの IoT ハブとストレージ アカウントを含むリソース グループに移動します。
2. リソース グループ内にあるすべてのリソースを確認して、クリーンアップするリソースを決定します。
   • すべてのリソースを削除する場合は、 [リソース グループの削除] を選択します。
   • 特定のリソースのみを削除する場合は、各リソース名の横にあるチェック ボックスを使用して、削除するリソースを選択します。 次に、 [削除] を選択します。

Azure CLI

1. az resource list コマンドを使用して、リソース グループ内のすべてのリソースを表示します。

   az resource list --resource-group $resourceGroup --output table
   

2. リソース グループ内にあるすべてのリソースを確認して、クリーンアップするリソースを決定します。

   • すべてのリソースを削除する場合は、 az group delete コマンドを使用します。

     az group delete --name $resourceGroup
     

   • 特定のリソースのみを削除する場合は、 az resource delete コマンドを使用します。 次に例を示します。

     az resource delete --resource-group $resourceGroup --name $storageName
     

次のステップ

このチュートリアルでは、Azure リソースのカスタム エンドポイントを作成し、そのエンドポイントにデバイス メッセージを送信するルートを作成する方法について説明しました。 次のチュートリアルに進み、ダウンストリーム処理を簡略化するために使用できる追加のデータでメッセージをエンリッチする方法を学習します

Azure IoT Hub のメッセージ エンリッチメントを使用する