Wzbogacanie komunikatów trasowanych MQTT
Obsługa wzbogacania umożliwia dodanie do 20 niestandardowych właściwości klucz-wartość do komunikatów przed wysłaniem ich do tematu niestandardowego usługi Event Grid. Te wzbogacenia umożliwiają:
- Dodaj dane kontekstowe do wiadomości. Na przykład wzbogacanie komunikatu o nazwę klienta lub nazwę przestrzeni nazw może dostarczyć punktom końcowym informacje o źródle komunikatu.
- Zmniejszenie obciążenia obliczeniowego punktów końcowych. Na przykład wzbogacanie komunikatu wskaźnikiem formatu ładunku żądania publikowania MQTT lub typem zawartości informuje punkty końcowe o sposobie przetwarzania ładunku komunikatu bez wcześniejszej próby wypróbowania wielu analizatorów.
- Przefiltruj kierowane komunikaty za pomocą subskrypcji zdarzeń usługi Event Grid na podstawie dodanych danych. Na przykład wzbogacanie atrybutu klienta umożliwia filtrowanie komunikatów, które mają być kierowane do punktu końcowego na podstawie wartości różnych atrybutów.
Konfigurowanie
Klucz wzbogacania:
Klucz wzbogacania to ciąg, który musi spełniać następujące wymagania:
- Uwzględnij tylko małe litery alfanumeryczne: tylko (a-z) i (0–9)
- Nie może być
specversion, ,id,typedatacontenttypetimesubjectdataschemasourcedatalub .data_base64 - Nie może rozpoczynać się od
azsp. - Nie można duplikować.
- Nie może zawierać więcej niż 20 znaków.
Wartość wzbogacania:
Wartość wzbogacania może być ciągiem statycznym dla wzbogacenia statycznego lub jedną z obsługiwanych wartości reprezentujących atrybuty klienta lub właściwości komunikatu MQTT na potrzeby wzbogacania dynamicznego. Wartości wzbogacania nie mogą zawierać więcej niż 128 znaków. Poniższa lista zawiera obsługiwane wartości:
Atrybuty klienta
- ${client.authenticationName}: nazwa klienta publikowania.
- ${client.attributes.x}: atrybut klienta publikowania, gdzie x jest nazwą klucza atrybutu.
Właściwości MQTT
- ${mqtt.message.userProperties.x}: właściwości użytkownika w pakiecie PUBLISH MQTTv5, gdzie x to nazwa klucza właściwości użytkownika
- Typ: ciąg
- Użyj następującego formatu zmiennej, jeśli właściwość użytkownika zawiera znaki specjalne ${mqtt.message.userProperties['x']}. Nadal musisz uciec przed apostrofem i ukośnikiem odwrotnym w następujący sposób: i "PN\t" staje się "PN\t".
- ${mqtt.message.topicName}: temat w pakiecie PUBLISH MQTT.
- Typ: ciąg
- ${mqtt.message.responseTopic}: temat odpowiedzi w pakiecie PUBLISH MQTTv5.
- Typ: ciąg
- ${mqtt.message.correlationData}: dane korelacji w pakiecie PUBLISH MQTTv5.
- Typ: binarny
- ${mqtt.message.pfi}: wskaźnik formatu ładunku w pakiecie PUBLISH MQTTv5.
- Typ: liczba całkowita
Konfiguracja witryny Azure Portal
Aby skonfigurować wzbogacania routingu, wykonaj następujące kroki:
- Przejdź do przestrzeni nazw w witrynie Azure Portal.
- W obszarze Routing zaznacz opcję Włącz routing.
- W obszarze temat routingu wybierz temat usługi Event Grid, który został utworzony, w którym będą kierowane wszystkie komunikaty MQTT.
- W obszarze Wzbogacanie komunikatów wybierz pozycję + Dodaj wzbogacanie.
- Dodaj do 20 par klucz-wartość i odpowiednio wybierz ich typ.
- Wybierz Zastosuj.
Aby uzyskać więcej informacji na temat konfiguracji routingu, zobacz Konfiguracja routingu w witrynie Azure Portal.
Konfiguracja interfejsu wiersza polecenia platformy Azure
Użyj polecenia i ładunku podczas tworzenia/aktualizacji przestrzeni nazw, aby skonfigurować wzbogacania routingu:
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": {},
}
Aby uzyskać więcej informacji na temat konfiguracji routingu, przejdź do tematu Routing konfiguracji interfejsu wiersza polecenia platformy Azure.
Przykładowe dane wyjściowe
Następujący element CloudEvent to przykładowe dane wyjściowe komunikatu MQTTv5 z pfI=0 po zastosowaniu poprzedniej konfiguracji wzbogacania:
{
"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==
}
}
Obsługa przypadków specjalnych:
- Nieokreślone atrybuty klienta/właściwości użytkownika: jeśli wzbogacenie dynamiczne wskazuje właściwość atrybutu klienta/użytkownika, która nie istnieje, wzbogacanie będzie zawierać określony klucz z pustym ciągiem dla wartości. Na przykład
emptyproperty: "". - Tablice: tablice w atrybutach klienta i zduplikowane właściwości użytkownika są przekształcane w ciąg rozdzielany przecinkami. Na przykład: jeśli wzbogacony atrybut klienta ma wartość "array": "value1", "value2", "value3", wynikowa wzbogacona właściwość będzie następująca
array:value1,value2,value3. Inny przykład: jeśli to samo żądanie publikowania MQTT ma następujące właściwości > użytkownika "userproperty1": "value1", "userproperty1": "value2", wynikowa wzbogacona właściwość będzie następująca:userproperty1value1,value2.
Następne kroki:
Aby dowiedzieć się więcej na temat routingu, skorzystaj z następujących artykułów:
Szybki start:
- Samouczek: kierowanie komunikatów MQTT do usługi Azure Event Hubs przy użyciu tematów przestrzeni nazw
- Samouczek: kierowanie komunikatów MQTT do usługi Azure Functions przy użyciu tematów niestandardowych