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

[アーティクル]
05/11/2023

メッセージエンリッチメントは、指定されたエンドポイントに送信される前のメッセージに対し、追加情報を含んだスタンプメッセージを適用する Azure IoT Hub の機能です。メッセージエンリッチメントを使用する理由の 1 つは、ダウンストリームの処理を単純化するために用いることのできるデータを追加することです。たとえば、デバイスツインタグを使用してデバイスのメッセージのエンリッチメントを行えば、この情報のために顧客側でデバイスツイン API を呼び出す負担を軽減することができます。詳細については、メッセージエンリッチメントの概要に関するページを参照してください。

このチュートリアルの最初のパートでは、カスタムエンドポイントを作成し、他の Azure サービスにメッセージをルーティングする方法を確認しました。このチュートリアルでは、IoT ハブ用のメッセージエンリッチメントをテストするために必要な追加リソースを作成し、構成する方法について説明します。このリソースには、エンリッチメッセージを保持するための既存のストレージアカウント (チュートリアルの最初のパートで作成したもの) の 2 つ目のストレージコンテナーと、それらをそこに送信するメッセージルートが含まれます。メッセージルーティングとメッセージエンリッチメントの構成が完了したら、アプリケーションを使用してメッセージを IoT ハブに送信します。その後、ハブによって両方のストレージコンテナーにルーティングされます。 enriched ストレージコンテナーのエンドポイントに送信されるメッセージだけがエンリッチされます。

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

ストレージアカウントで 2 つ目のコンテナーを作成します。
別のカスタムエンドポイントを作成し、IoT ハブからそこにメッセージをルーティングします。
新しいエンドポイントにルーティングされるメッセージエンリッチメントを構成します。
IoT デバイスをシミュレートするアプリを実行し、ハブにメッセージを送信します。
その結果を表示して、メッセージエンリッチメントがターゲットメッセージに適用されていることを確認します。

前提条件

Azure サブスクリプションが必要です。 Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。
「チュートリアル: IoT Hub メッセージルーティングを使用してデバイスデータを Azure Storage に送信する」を完了し、そのために作成したリソースを保守している必要があります。
ポート 8883 がファイアウォールで開放されていることを確認してください。このチュートリアルのデバイスサンプルでは、ポート 8883 を介して通信する MQTT プロトコルを使用しています。このポートは、企業や教育用のネットワーク環境によってはブロックされている場合があります。この問題の詳細と対処方法については、「IoT Hub への接続 (MQTT)」を参照してください。

Azure Portal
Azure CLI

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

ストレージアカウントで 2 つ目のコンテナーを作成する

このチュートリアルの最初のパートでは、ルーティングされたメッセージ用にストレージアカウントとコンテナーを作成しました。次は、エンリッチメッセージ用に 2 つ目のコンテナーを作成する必要があります。

Azure Portal
Azure CLI

Azure portal で、[ストレージアカウント] を検索します。
先ほど作成したアカウントを選択します。
[ストレージアカウント] メニューの [データストレージ] セクションから [コンテナー] を選択します。
[コンテナー] を選んで、新しいコンテナーを作成します。
コンテナーに enriched という名前を付け、[作成] を選択します。

ヒント

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

これらの変数値は、このチュートリアルの最初のパートで使ったリソースと同じにする必要があります。

IoT ハブ、ストレージアカウント、コンテナーの変数を定義します。

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

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

DEVICE_ID: このプレースホルダーをデバイスの ID に置き換えます。

STORAGE_NAME: このプレースホルダーをストレージアカウントの名前に置き換えます。

このチュートリアルでは、containerName 変数の値を enriched にする必要があります。
```
resourceGroup=GROUP_NAME
hubName=IOTHUB_NAME
deviceId=DEVICE_ID
storageName=STORAGE_NAME
containerName=enriched
```
az storage container create コマンドを使ってストレージアカウントにコンテナーを追加します。
```
az storage container create --auth-mode login --account-name $storageName --name $containerName
```

2 つ目のエンドポイントにメッセージをルーティングする

エンリッチメッセージのために 2 つ目のエンドポイントとルートを作成します。

重要

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

Azure Portal
Azure CLI

Azure portal で IoT Hub に移動します。
リソースメニューの [ハブ設定] で、[メッセージルーティング] を選択し、[追加] を選択します。

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

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

エンドポイントのコンテナーの選択を示すスクリーンショット。

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

ストレージエンドポイントを追加したので、新しいルートの作成を続けます。新しいルートに関して、次の情報を入力します。

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

ルーティングクエリ情報の保存を示すスクリーンショット。

[エンリッチメントの作成 + 追加] を選択します。

エンドポイントとルートのコマンドに変数を構成し、それぞれ ContosoStorageEndpointEnriched と ContosoStorageRouteEnriched の値を使います。
```
endpointName=ContosoStorageEndpointEnriched
routeName=ContosoStorageRouteEnriched
```

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

az iot hub message-endpoint create \
  --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

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

新しいエンドポイントにメッセージエンリッチメントを追加する

enriched ストレージコンテナーにルーティングされる 3 つのメッセージエンリッチメントを作成します。

Azure Portal
Azure CLI

ルートの追加ウィザードの [エンリッチメント] タブで、enriched と呼ばれるストレージコンテナーのエンドポイントに送信されるメッセージのメッセージエンリッチメントが 3 つ追加されます。

ContosoStorageEndpointEnriched エンドポイントのメッセージエンリッチメントとしてこれらの値を追加します。

名前値

myIotHub $hubname

DeviceLocation $twin.tags.location (前提としてデバイスツインに場所タグがある)

customerID 6ce345b8-1e4a-411e-9398-d34587459a3a

作業が完了すると、エンリッチメントは次の画像のようになります。
[追加] を選択して、メッセージエンリッチメントを追加します。

名前	値
myIotHub	`$hubname`
DeviceLocation	`$twin.tags.location` (前提としてデバイスツインに場所タグがある)
customerID	`6ce345b8-1e4a-411e-9398-d34587459a3a`

az iot hub message-enrichment create コマンドを 3 回呼び出して、先ほど作成したエンドポイントに向かうルートにメッセージエンリッチメントを追加します。

az iot hub message-enrichment create \
  --key myIotHub \
  --value $hubName \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

# This assumes that the device twin has a location tag.
az iot hub message-enrichment create \
  --key DeviceLocation \
  --value '$twin.tags.location' \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

az iot hub message-enrichment create \
  --key customerID \
  --value 6ce345b8-1e4a-411e-9398-d34587459a3a \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

これで、エンリッチメッセージ用に作成したエンドポイントにルーティングされるすべてのメッセージに、メッセージエンリッチメントが設定されました。デバイスツインに場所タグを追加しない場合は、「メッセージエンリッチメントをテストする」セクションまでスキップしてチュートリアルを続けることができます。

デバイスツインに場所タグを追加する

IoT ハブで構成されたメッセージエンリッチメントのいずれかに DeviceLocation のキーを指定します。この値は次のデバイスツインパスによって決まります: $twin.tags.location。デバイスツインに場所タグがない場合、メッセージエンリッチメントの DeviceLocation キーの文字列として、ツインパス $twin.tags.location がスタンプされます。

デバイスのツインに場所タグを追加するには、次の手順に従います。

Azure Portal
Azure CLI

Azure Portal で、IoT ハブに移動します。
IoT ハブのナビゲーションメニューで [デバイス] を選択して、デバイスを選択します。
デバイスページの上部にある [デバイスツイン] タブを選択し、デバイスツインの下部にある右中かっこの直前に次の行を追加します。次に、 [保存] を選択します。
```
  , "tags": {"location": "Plant 43"}
```

az iot hub device-twin update コマンドを使い、新しいタグのキーと値を指定してデバイスツインを更新します。

az iot hub device-twin update \
  --hub-name $hubName \
  --device-id $deviceId \
  --tags '{"location": "Plant 43"}'

ヒント

約5分間待ってから、次のセクションに進みます。デバイスツインの更新がメッセージエンリッチメント値に反映されるまで、最大でもそれくらいの時間がかかることがあります。

メッセージエンリッチメントでデバイスツインパスを処理する方法の詳細については、「メッセージエンリッチメントの制限事項」を参照してください。デバイスツインの詳細については、「IoT Hub のデバイスツインの理解と使用」を参照してください。

メッセージエンリッチメントをテストする

メッセージエンリッチメントは ContosoStorageEndpointEnriched エンドポイントに対して構成されているので、シミュレートされたデバイスのアプリケーションを実行して、IoT ハブにメッセージを送信します。この時点で、メッセージのルーティングは次のように設定されています。

チュートリアルの最初のパートで作成したストレージエンドポイントにルーティングされたメッセージは、エンリッチされず、そのときに作成したストレージコンテナーに格納されます。
ストレージエンドポイント ContosoStorageEndpointEnriched にルーティングされたメッセージはエンリッチされて、ストレージコンテナー enriched に格納されます。

このチュートリアルの最初のパートにある SimulatedDevice コンソールアプリケーションをまだ実行していない場合は、もう一度実行します。

ヒント

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

サンプルフォルダーで、 /iot-hub/Tutorials/Routing/SimulatedDevice/ フォルダーに移動します。
さきほど更新した変数定義はまだ有効なはずですが、そうでない場合は Program.cs ファイル内で編集します。
1. Program クラスの上部にある変数定義を見つけます。次の変数を自分の情報で更新します。
  - s_myDeviceId: デバイスを IoT ハブに登録するときに割り当てたデバイス ID。
  - s_iotHubUri: IOTHUB_NAME.azure-devices.net 形式を受け取る IoT ハブのホスト名。
  - s_deviceKey: デバイス ID 情報に含まれるデバイスの主キー。
2. ファイルを保存して閉じます。
サンプルコードを実行する。
```
dotnet run
```

コンソールアプリケーションを数分間実行した後、データを確認します。

Azure portal のストレージアカウントに移動します。
ナビゲーションメニューから [ストレージブラウザー] を選びます。 [BLOB コンテナー] を選ぶと、これらのチュートリアルの過程で作成した 2 つのコンテナーが表示されます。

enriched というコンテナー内のメッセージには、メッセージエンリッチメントが適用されています。先ほど作成したコンテナー内のメッセージには、エンリッチメントが適用されていない生のメッセージが格納されます。 enriched コンテナーをドリルダウンして一番下まで移動し、最新のメッセージファイルを開きます。次に、もう一方のコンテナーに対して同じ操作を行って、1 つがエンリッチされ、もう 1 つがエンリッチされていないことを確認します。

エンリッチされたメッセージを見ると、次のように、"myIotHub" とハブ名、場所、顧客 ID が含まれているはずです。

{
  "EnqueuedTimeUtc":"2019-05-10T06:06:32.7220000Z",
  "Properties":
  {
    "level":"storage",
    "myIotHub":"{your hub name}",
    "DeviceLocation":"Plant 43",
    "customerID":"6ce345b8-1e4a-411e-9398-d34587459a3a"
  },
  "SystemProperties":
  {
    "connectionDeviceId":"Contoso-Test-Device",
    "connectionAuthMethod":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
    "connectionDeviceGenerationId":"636930642531278483",
    "enqueuedTime":"2019-05-10T06:06:32.7220000Z"
  },"Body":"eyJkZXZpY2VJZCI6IkNvbnRvc28tVGVzdC1EZXZpY2UiLCJ0ZW1wZXJhdHVyZSI6MjkuMjMyMDE2ODQ4MDQyNjE1LCJodW1pZGl0eSI6NjQuMzA1MzQ5NjkyODQ0NDg3LCJwb2ludEluZm8iOiJUaGlzIGlzIGEgc3RvcmFnZSBtZXNzYWdlLiJ9"
}

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

このチュートリアルの両方のパートで作成したリソースをすべて削除するには、リソースグループを削除します。これにより、そのグループ内に含まれているすべてのリソースも削除されます。リソースグループ全体を削除しない場合は、リソースグループ内の個々のリソースを選んで削除できます。

Azure Portal
Azure CLI

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

az resource list コマンドを使用して、リソースグループ内のすべてのリソースを表示します。
```
az resource list --resource-group $resourceGroup --output table
```
リソースグループ内にあるすべてのリソースを確認して、クリーンアップするリソースを決定します。
- すべてのリソースを削除する場合は、 az group delete コマンドを使用します。
```
az group delete --name $resourceGroup
```
- 特定のリソースのみを削除する場合は、 az resource delete コマンドを使用します。次に例を示します。
```
az resource delete --resource-group $resourceGroup --name $storageName
```

次のステップ

このチュートリアルでは、IoT Hub メッセージがエンドポイントにルーティングされる際にメッセージエンリッチメントを構成し、テストしました。

メッセージエンリッチメントの詳細については、メッセージエンリッチメントの概要に関するページを参照してください。

IoT Hub の詳細については、次のチュートリアルに進んでください。

チュートリアル: IoT ハブでメトリックとログを設定して使用する

次の方法で共有

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

前提条件

ストレージアカウントで 2 つ目のコンテナーを作成する

2 つ目のエンドポイントにメッセージをルーティングする

新しいエンドポイントにメッセージエンリッチメントを追加する

デバイスツインに場所タグを追加する

メッセージエンリッチメントをテストする

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

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

前提条件

ストレージ アカウントで 2 つ目のコンテナーを作成する

2 つ目のエンドポイントにメッセージをルーティングする

新しいエンドポイントにメッセージ エンリッチメントを追加する

デバイス ツインに場所タグを追加する

メッセージ エンリッチメントをテストする

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

次のステップ

フィードバック

その他のリソース

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

ストレージアカウントで 2 つ目のコンテナーを作成する

新しいエンドポイントにメッセージエンリッチメントを追加する

デバイスツインに場所タグを追加する

メッセージエンリッチメントをテストする