Anreicherungen für durch MQTT weitergeleitete Nachrichten

Artikel
11/16/2023

Mit der Anreicherungsunterstützung können Sie Ihren Nachrichten bis zu 20 benutzerdefinierte Schlüssel-Wert-Eigenschaften hinzufügen, bevor sie an das benutzerdefinierte Event Grid-Thema gesendet werden. Mit diesen Anreicherungen können Sie die folgenden Aufgaben ausführen:

Hinzufügen von kontextbezogene Daten zu Ihren Nachrichten. Wenn Sie die Nachricht beispielsweise mit dem Namen des Clients oder dem Namespacenamen anreichern, können Sie Informationen zur Quelle der Nachricht für Endpunkte bereitstellen.
Verringern der Computinglast für Endpunkte. Wenn Sie beispielsweise die Nachricht mit dem Nutzdatenformatindikator der MQTT-Veröffentlichungsanforderung oder dem Inhaltstyp anreichern, werden Endpunkte darüber informiert, wie die Nutzdaten der Nachricht verarbeitet werden können, ohne zuvor mehrere Parser ausprobieren zu müssen.
Filtern Ihrer weitergeleiteten Nachrichten anhand der hinzugefügten Daten über Event Grid-Ereignisabonnements. Wenn Sie beispielsweise ein Clientattribut anreichern, können Sie die Nachrichten basierend auf den verschiedenen Werten des Attributs filtern, die an den Endpunkt weitergeleitet werden sollen.

Konfiguration

Anreicherungsschlüssel:

Der Anreicherungsschlüssel ist eine Zeichenfolge, die die folgenden Anforderungen erfüllen muss:

Sie darf nur alphanumerische Kleinbuchstaben enthalten: nur (a bis z) und (0 bis 9)
Darf nicht specversion, id, time, type, source, subject, datacontenttype, dataschema, data oder data_base64 sein.
Darf nicht mit azsp beginnen.
Sie darf nicht dupliziert werden.
Sie darf nicht mehr als 20 Zeichen lang sein.

Anreicherungswert:

Der Anreicherungswert kann eine statische Zeichenfolge für statische Anreicherungen oder einer der unterstützten Werte sein, die die Clientattribute oder die MQTT-Nachrichteneigenschaften für dynamische Anreicherung darstellen. Anreicherungswerte dürfen nicht mehr als 128 Zeichen lang sein. Die folgende Liste enthält die unterstützten Werte:

Clientattribute

${client.authenticationName}: Der Name des veröffentlichenden Clients.
${client.attributes.x}: Ein Attribut des veröffentlichenden Clients, wobei x der Attributschlüsselname ist.

MQTT-Eigenschaften

${mqtt.message.userProperties.x}: Benutzereigenschaften im MQTTv5 PUBLISH-Paket, wobei x der Name des Benutzereigenschaftenschlüssels ist
- Type: string
- Verwenden Sie stattdessen das folgende Variablenformat, wenn Ihre Benutzereigenschaft Sonderzeichen ${mqtt.message.userProperties['x']} enthält. Sie müssen weiterhin ein Apostroph und einen umgekehrten Schrägstrich wie folgt mit Escapezeichen versehen:, und „PN\t“ wird zu „PN\t“.
${mqtt.message.topicName}: Das Thema im MQTT PUBLISH-Paket.
- Type: string
${mqtt.message.responseTopic}: Das Antwortthema im MQTTv5 PUBLISH-Paket.
- Type: string
${mqtt.message.correlationData}: Die Korrelationsdaten im MQTTv5 PUBLISH-Paket.
- Typ: Binär
${mqtt.message.pfi}: Der Indikator für das Nutzdatenformat im MQTTv5 PUBLISH-Paket.
- Typ: Ganze Zahl

Konfiguration des Azure-Portals

Führen Sie die folgenden Schritte aus, um Routinganreicherungen zu konfigurieren:

Navigieren Sie im Azure-Portal zu Ihrem Namespace.
Aktivieren Sie unter Routing die Option Routing aktivieren.
Wählen Sie unter „Routingthema“ das Event Grid-Thema aus, das Sie erstellt haben, an das alle MQTT-Nachrichten weitergeleitet werden.
Wählen Sie unter Nachrichtenanreicherung die Option + Anreicherung hinzufügen aus.
Fügen Sie bis zu 20 Schlüssel-Wert-Paare hinzu, und wählen Sie ihren Typ entsprechend aus.
Wählen Sie Übernehmen.

Screenshot showing the routing enrichment configuration through the portal.

Weitere Informationen zur Routingkonfiguration finden Sie unter Routingkonfiguration im Azure-Portal.

Azure CLI-Konfiguration

Verwenden Sie den Befehl und die Nutzdaten während der Erstellung/Aktualisierung des Namespaces, um Routinganreicherungen zu konfigurieren:

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": {},
}

Weitere Informationen zur Routingkonfiguration finden Sie unter Routingkonfiguration in der Azure CLI.

Beispielausgabe

Das folgende CloudEvent ist eine Beispielausgabe einer MQTTv5-Nachricht mit PFI=0 nach dem Anwenden der vorherigen Anreicherungskonfiguration:

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

Behandeln besonderer Fälle:

Nicht angegebene Clientattribute/Benutzereigenschaften: Wenn eine dynamische Anreicherung auf ein Clientattribut bzw. eine Benutzereigenschaft verweist, die nicht vorhanden ist, enthält die Anreicherung den angegebenen Schlüssel mit einer leeren Zeichenfolge für einen Wert. Beispiel: emptyproperty: "".
Arrays: Arrays in Clientattributen und doppelt vorhandenen Benutzereigenschaften werden in eine durch Trennzeichen getrennte Zeichenfolge transformiert. Beispiel: Wenn das angereicherte Clientattribut auf „array“: „value1", „value2“, „value3“ festgelegt ist, lautet die resultierende angereicherte Eigenschaft array: value1,value2,value3. Ein weiteres Beispiel: Wenn dieselbe MQTT-Veröffentlichungsanforderung die folgenden Benutzereigenschaften aufweist > „userproperty1“: „value1“, „userproperty1“: „value2“, lautet die resultierende angereicherte Eigenschaft userproperty1: value1,value2.

Nächste Schritte:

In den folgenden Artikeln erfahren Sie mehr über Routing:

Freigeben über