Arricchimenti per i messaggi indirizzati MQTT
Il supporto degli arricchimenti consente di aggiungere fino a 20 proprietà chiave-valore personalizzate ai messaggi prima che vengano inviate all'argomento personalizzato di Griglia di eventi. Questi arricchimenti consentono di:
- Aggiungere dati contestuali ai messaggi. Ad esempio, l'arricchimento del messaggio con il nome del client o il nome dello spazio dei nomi potrebbe fornire agli endpoint informazioni sull'origine del messaggio.
- Ridurre il carico di calcolo sugli endpoint. Ad esempio, arricchire il messaggio con l'indicatore di formato payload della richiesta di pubblicazione MQTT o il tipo di contenuto informa gli endpoint come elaborare il payload del messaggio senza provare prima più parser.
- Filtrare i messaggi indirizzati tramite sottoscrizioni di eventi di Griglia di eventi in base ai dati aggiunti. Ad esempio, l'arricchimento di un attributo client consente di filtrare i messaggi da instradare all'endpoint in base ai valori dell'attributo diverso.
Impostazione
Chiave di arricchimento:
La chiave di arricchimento è una stringa che deve essere conforme ai requisiti seguenti:
- Includere solo caratteri alfanumerici minuscoli: solo (a-z) e (0-9)
- Non deve essere
specversion,id,timetype,source,subject,datacontenttype,dataschema,data, odata_base64. - Non deve iniziare con
azsp. - Non deve essere duplicato.
- Non deve contenere più di 20 caratteri.
Valore di arricchimento:
Il valore di arricchimento può essere una stringa statica per gli arricchimenti statici o uno dei valori supportati che rappresentano gli attributi client o le proprietà del messaggio MQTT per l'arricchimento dinamico. I valori di arricchimento non devono contenere più di 128 caratteri. L'elenco seguente include i valori supportati:
Attributi client
- ${client.authenticationName}: nome del client di pubblicazione.
- ${client.attributes.x}: attributo del client di pubblicazione, dove x è il nome della chiave dell'attributo.
Proprietà MQTT
- ${mqtt.message.userProperties.x}: proprietà utente nel pacchetto MQTTv5 PUBLISH, dove x è il nome della chiave della proprietà utente
- Tipo: string
- Usare invece il formato variabile seguente se la proprietà utente include caratteri speciali ${mqtt.message.userProperties['x']}. È comunque necessario eseguire l'escape di un apostrofo e una barra rovesciata come indicato di seguito: e "PN\t" diventa "PN\t".
- ${mqtt.message.topicName}: argomento nel pacchetto MQTT PUBLISH.
- Tipo: string
- ${mqtt.message.responseTopic}: argomento della risposta nel pacchetto MQTTv5 PUBLISH.
- Tipo: string
- ${mqtt.message.correlationData}: dati di correlazione nel pacchetto MQTTv5 PUBLISH.
- Tipo: binary
- ${mqtt.message.pfi}: indicatore del formato del payload nel pacchetto MQTTv5 PUBLISH.
- Tipo: integer
configurazione di portale di Azure
Per configurare gli arricchimenti del routing, seguire questa procedura:
- Passare allo spazio dei nomi nel portale di Azure.
- In Routing selezionare Abilita routing.
- In Argomento di routing selezionare l'argomento Griglia di eventi creato in cui verranno instradati tutti i messaggi MQTT.
- In Arricchimenti messaggi selezionare + Aggiungi arricchimento.
- Aggiungere fino a 20 coppie chiave-valore e selezionare il tipo in modo appropriato.
- Selezionare Applica.
Per altre informazioni sulla configurazione del routing, vedere Routing portale di Azure configurazione.
Configurazione dell'interfaccia della riga di comando di Azure
Usare il comando e il payload durante la creazione/aggiornamento dello spazio dei nomi per configurare gli arricchimenti del routing:
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": {},
}
Per altre informazioni sulla configurazione del routing, vedere Routing della configurazione dell'interfaccia della riga di comando di Azure.
Output di esempio
Il cloudEvent seguente è un output di esempio di un messaggio MQTTv5 con PFI=0 dopo aver applicato la configurazione di arricchimento precedente:
{
"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==
}
}
Gestione di casi speciali:
- Attributi client/proprietà utente non specificati: se un arricchimento dinamico punta a una proprietà client attributo/utente che non esiste, l'arricchimento includerà la chiave specificata con una stringa vuota per un valore. Ad esempio,
emptyproperty: "". - Matrici: le matrici negli attributi client e le proprietà utente duplicate vengono trasformate in una stringa delimitata da virgole. Ad esempio: se l'attributo client arricchito è impostato su "array": "value1", "value2", "value3", la proprietà arricchita risultante sarà
array:value1,value2,value3. Un altro esempio: se la stessa richiesta di pubblicazione MQTT ha le proprietà > utente seguenti "userproperty1": "value1", "userproperty1": "value2", la proprietà arricchita risultante saràuserproperty1:value1,value2.
Passaggi successivi:
Per altre informazioni sul routing, vedere gli articoli seguenti:
Avvio rapido:
- Esercitazione: Indirizzare i messaggi MQTT a Hub eventi di Azure usando gli argomenti dello spazio dei nomi
- Esercitazione: Indirizzare i messaggi MQTT a Funzioni di Azure usando argomenti personalizzati