MQTT ルーティング メッセージのエンリッチメント
エンリッチメントのサポートにより、Event Grid カスタム トピックに送信される前に、最大 20 個のカスタム キーと値のプロパティをメッセージに追加できます。 これらのエンリッチメントを使用すると、次を実行できます。
- メッセージにコンテキスト データを追加します。 たとえば、クライアントの名前または名前空間名でメッセージをエンリッチすると、メッセージのソースに関する情報をエンドポイントに提供できます。
- エンドポイントのコンピューティング負荷を軽減します。 たとえば、MQTT 発行要求のペイロード形式インジケーターやコンテンツ タイプを使用してメッセージをエンリッチすると、メッセージのペイロードを処理する方法がエンドポイントに通知されるため、最初に複数のパーサーを試す必要がなくなります。
- Event Grid イベント サブスクリプション経由でルーティングされるメッセージを、追加されたデータに基づいてフィルター処理します。 たとえば、クライアント属性をエンリッチすると、エンドポイントにルーティングされるメッセージを、さまざまな属性の値に基づいてフィルター処理できます。
構成
エンリッチメント キー:
エンリッチメント キーは、次の要件に準拠する必要がある文字列です。
- 小文字の英数字である (a から z) と (0 から 9) のみを含むこと。
specversion、id、time、type、source、subject、datacontenttype、dataschema、data、data_base64でないこと。- 先頭が
azspではないこと。 - 重複しないこと。
- 20 文字以下であること。
エンリッチメント値:
エンリッチメント値には、静的エンリッチメントでは静的文字列、またはクライアント属性を表すサポートされている値のいずれか、動的エンリッチメントでは MQTT メッセージ プロパティを指定できます。 エンリッチメント値は 128 文字以下にする必要があります。 サポートされている値の一覧を次に示します。
クライアント属性
- ${client.authenticationName}: 発行クライアントの名前。
- ${client.attributes.x}: 発行クライアントの属性。ここで x は属性キー名です。
MQTT プロパティ
- ${mqtt.message.userProperties.x}: MQTTv5 発行パケットのユーザー プロパティ。ここで x はユーザー プロパティ キー名です
- Type: 文字列
- ユーザー プロパティに特殊文字が含まれている場合は、代わりに変数の形式に ${mqtt.message.userProperties['x']} を使用します。 さらに、アポストロフィと円記号を "PN\t" であれば "PN\\t" のようにエスケープする必要があります。
- ${mqtt.message.topicName}: MQTT 発行パケット内のトピック。
- Type: 文字列
- ${mqtt.message.responseTopic}: MQTTv5 発行パケット内の応答トピック。
- Type: 文字列
- ${mqtt.message.correlationData}: MQTTv5 発行パケット内の相関データ。
- 型: バイナリ
- ${mqtt.message.pfi}: MQTTv5 発行パケット内のペイロード形式インジケーター。
- 型: 整数
Azure portal の構成
次の手順を使用して、ルーティング エンリッチメントを構成します。
- Azure portal でご使用の名前空間に移動します。
- [ルーティング] で、[ルーティングを有効にする] をオンにします。
- [トピックのルーティング] で、すべての MQTT メッセージのルーティング先である、作成した Event Grid トピックを選択します。
- [メッセージ エンリッチメント] で、[+ エンリッチメントの追加] を選択します。
- 最大 20 個のキーと値のペアを追加し、その該当する種類を選択します。
- [適用] を選択します。
ルーティング構成の詳細については、Azure portal のルーティング構成に関する記事を参照してください。
Azure CLI の構成
名前空間の作成/更新中にコマンドとペイロードを使用して、ルーティング エンリッチメントを構成します。
az resource create --resource-type Microsoft.EventGrid/namespaces --id /subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/namespaces/<Namespace Name> --is-full-object --api-version 2023-06-01-preview --properties @./resources/NS.json
NS.json
{
"properties": {
"topicSpacesConfiguration": {
"state": "Enabled",
"routeTopicResourceId": "/subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/topics/<Event Grid Topic name>",
"routingEnrichments": {
"static": [
{
"key": "namespaceid",
"value": "123",
"valueType": "string"
}
],
"dynamic": [
{
"key": "clientname",
"value": "${client.authenticationName}"
},
{
"key": "clienttype",
"value": "${client.attributes.type}"
},
{
"key": "address",
"value": "${mqtt.message.userProperties['client.address']}"
},
{
"key": "region",
"value": "${mqtt.message.userProperties.location}"
},
{
"key": "mqtttopic",
"value": "${mqtt.message.topicName}"
},
{
"key": "mqttresponsetopic",
"value": "${mqtt.message.responseTopic}"
},
{
"key": "mqttcorrelationdata",
"value": "${mqtt.message.correlationData}"
},
{
"key": "mqttpfi",
"value": "${mqtt.message.pfi}"
}
]
}
}
},
"location": "eastus2euap",
"tags": {},
}
ルーティング構成の詳細については、Azure CLI のルーティング構成に関する記事を参照してください。
サンプル出力
次の CloudEvent は、前のエンリッチメント構成を適用した後の、PFI=0 での MQTTv5 メッセージのサンプル出力です。
{
"specversion": "1.0",
"id": "9aeb0fdf-c01e-0131-0922-9eb54906e20", // unique id stamped by the service
"time": "2019-11-18T15:13:39.4589254Z", // timestamp when messages was received by the service
"type": "MQTT.EventPublished", // set type for all MQTT messages enveloped by the service
"source": "testnamespace", // namespace name
"subject": "campus/buildings/building17", // topic of the MQTT publish request
"namespaceid": "123", // static enrichment
"clientname": "client1", // dynamic enrichment of the name of the publishing client
"clienttype": "operator", // dynamic enrichment of an attribute of the publishing client
"address": "1 Microsoft Way, Redmond, WA 98052", // dynamic enrichment of a user property in the MQTT publish request
"region": "North America", // dynamic enrichment of another user property in the MQTT publish request
"mqtttopic": "campus/buildings/building17", // dynamic enrichment of the topic of the MQTT publish request
"mqttresponsetopic": "campus/buildings/building17/response", // dynamic enrichment of the response topic of the MQTT publish request
"mqttcorrelationdata": "cmVxdWVzdDE=", // dynamic enrichment of the correlation data of the MQTT publish request encoded in base64
"mqttpfi": 0, // dynamic enrichment of the payload format indicator of the MQTT publish request
"datacontenttype": "application/octet-stream", //content type of the MQTT publish request
"data_base64":
{
IlRlbXAiOiAiNzAiLAoiaHVtaWRpdHkiOiAiNDAiCg==
}
}
特殊なケースの処理:
- 指定されていないクライアント属性/ユーザー プロパティ: 動的エンリッチメントが存在しないクライアント属性/ユーザー プロパティを指した場合、エンリッチメントには、値に空の文字列を持つ指定されたキーが含められます。 例:
emptyproperty""。 - 配列: クライアント属性内の配列、および重複するユーザー プロパティは、コンマ区切りの文字列に変換されます。 たとえば、エンリッチされたクライアント属性が "array": "value1", "value2", "value3" と設定された場合、結果のエンリッチされたプロパティは
array:value1,value2,value3になります。 別の例: 同じ MQTT 発行要求に次のユーザー プロパティ > "userproperty1": "value1", "userproperty1": "value2" がある場合、結果のエンリッチされたプロパティはuserproperty1:value1,value2になります。
次のステップ:
ルーティングの詳細については、次の記事を参照してください。
クイックスタート:
- チュートリアル: 名前空間トピックを使用して MQTT メッセージを Azure Event Hubs にルーティングする
- チュートリアル: カスタム トピックを使用して MQTT メッセージを Azure Functions にルーティングする