Enriquecimentos para mensagens roteadas MQTT
O suporte a enriquecimentos permite que você adicione até 20 propriedades de chave-valor personalizadas às suas mensagens antes que elas sejam enviadas para o tópico personalizado da Grade de Eventos. Esses enriquecimentos permitem que você:
- Adicione dados contextuais às mensagens. Por exemplo, enriquecer a mensagem com o nome do cliente ou o nome do namespace pode fornecer aos pontos de extremidade informações sobre a origem da mensagem.
- Reduza a carga de computação dos pontos de extremidade. Por exemplo, enriquecer a mensagem com o indicador de formato de conteúdo da solicitação de publicação MQTT ou o tipo de conteúdo informa aos pontos de extremidade como processar o conteúdo da mensagem sem tentar usar vários analisadores primeiro.
- Filtre as mensagens roteadas por meio de assinaturas de evento da Grade de Eventos com base nos dados adicionados. Por exemplo, enriquecer um atributo de cliente permite filtrar as mensagens a serem roteadas para o ponto de extremidade com base nos valores do atributo diferente.
Configuração
Chave de enriquecimento:
A chave de enriquecimento é uma cadeia de caracteres que precisa estar em conformidade com estes requisitos:
- Incluir apenas caracteres alfanuméricos minúsculos: somente (a-z) e (0-9)
- Não pode ser
specversion,id,time,type,source,subject,datacontenttype,dataschema,dataoudata_base64. - Não deve começar com
azsp. - Não deve ser duplicada.
- Não deve ter mais de 20 caracteres.
Valor de enriquecimento:
O valor de enriquecimento pode ser uma cadeia de caracteres estática para enriquecimentos estáticos ou um dos valores com suporte que representam os atributos do cliente ou as propriedades da mensagem MQTT para enriquecimento dinâmico. Os valores de enriquecimento não devem ter mais de 128 caracteres. A seguinte lista inclui os valores com suporte:
Atributos de cliente
- ${client.authenticationName}: o nome do cliente de publicação.
- ${client.attributes.x}: um atributo do cliente de publicação, sendo que x é o nome da chave de atributo.
Propriedades do MQTT
- ${mqtt.message.userProperties.x}: propriedades do usuário no pacote PUBLISH do MQTT v5, sendo que x é o nome da chave de propriedade do usuário
- Type: string
- Use o formato de variável a seguir se a propriedade do usuário incluir caracteres especiais ${mqtt.message.userProperties['x']}. Você ainda precisa usar caracteres de escape em apóstrofos e barras invertidas da seguinte maneira: e "PN\t" se torna "PN\t".
- ${mqtt.message.topicName}: o tópico no pacote PUBLISH do MQTT.
- Type: string
- ${mqtt.message.responseTopic}: o tópico de resposta no pacote PUBLISH do MQTT v5.
- Type: string
- ${mqtt.message.correlationData}: os dados de correlação no pacote PUBLISH do MQTT v5.
- Tipo: binário
- ${mqtt.message.pfi}: o indicador de formato de conteúdo no pacote PUBLISH do MQTT v5.
- Tipo: inteiro
Configuração do portal do Azure
Use as seguintes etapas para configurar os enriquecimentos de roteamento:
- Acesse seu namespace no portal do Azure.
- Em Roteamento, marque Habilitar o roteamento.
- No tópico de roteamento, selecione o tópico da Grade de Eventos que você criou para o qual todas as mensagens MQTT serão roteadas.
- Em Enriquecimentos de mensagens, selecione + Adicionar enriquecimento.
- Adicione até 20 pares chave-valor e selecione o tipo delas de acordo.
- Escolha Aplicar.
Para obter mais informações sobre a configuração de roteamento, acesse Configuração de roteamento no portal do Azure.
Configuração da CLI do Azure
Use o comando e o conteúdo durante a criação/a atualização do namespace para configurar os enriquecimentos de roteamento:
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": {},
}
Para obter mais informações sobre a configuração de roteamento, acesse Configuração de roteamento na da CLI do Azure.
Saída de exemplo
O seguinte CloudEvent é um exemplo de saída de uma mensagem MQTT v5 com PFI=0 após a aplicação da configuração de enriquecimento anterior:
{
"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==
}
}
Tratamento de casos especiais:
- Propriedades do usuário/atributos de cliente não especificados: se um enriquecimento dinâmico apontar para uma propriedade do usuáriode/atributo de cliente que não existe, o enriquecimento incluirá a chave especificada com uma cadeia de caracteres vazia para um valor. Por exemplo,
emptyproperty: "". - Matrizes: as matrizes em atributos de cliente e nas propriedades do usuário duplicadas são transformadas em uma cadeia de caracteres separada por vírgula. Por exemplo: se o atributo de cliente enriquecido for definido como “array”: “value1”, “value2”, “value3”, a propriedade enriquecida resultante será
array:value1,value2,value3. Outro exemplo: se a mesma solicitação de publicação MQTT tiver as seguintes propriedades do usuário > "userproperty1": "value1", "userproperty1": "value2", a propriedade enriquecida resultante seráuserproperty1:value1,value2.
Próximas etapas:
Use os seguintes artigos para saber mais sobre roteamento:
Guia de Início Rápido:
- Tutorial: Encaminhar mensagens MQTT para Hubs de Eventos do Azure usando tópicos de namespace
- Tutorial: Encaminhar mensagens MQTT para Azure Functions usando tópicos personalizados