Enriquecimento para mensagens roteadas MQTT
O suporte a enriquecimento permite que você adicione até 20 propriedades de chave-valor personalizadas às suas mensagens antes que elas sejam enviadas para o tópico personalizado Grade de Eventos. Estes enriquecimentos permitem-lhe:
- Adicione dados contextuais às suas mensagens. Por exemplo, enriquecer a mensagem com o nome do cliente ou o nome do namespace pode fornecer pontos de extremidade com informações sobre a origem da mensagem.
- Reduza a carga de computação nos endpoints. Por exemplo, enriquecer a mensagem com o indicador de formato de carga útil da solicitação de publicação MQTT ou o tipo de conteúdo informa os pontos de extremidade sobre como processar a carga útil da mensagem sem tentar vários analisadores primeiro.
- Filtre suas mensagens roteadas por meio de assinaturas de eventos 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 dos diferentes atributos.
Configuração
Chave de enriquecimento:
A chave de enriquecimento é uma cadeia de caracteres que precisa estar em conformidade com estes requisitos:
- Incluir apenas alfanuméricos minúsculos: apenas (a-z) e (0-9)
- Não deve ser
specversion,id, ,time,type,sourcesubject,dataschemadatacontenttypedataoudata_base64. - Não deve começar com
azsp. - Não deve ser duplicado.
- Não deve ter mais de 20 caracteres.
Valor de Enriquecimento:
O valor de enriquecimento pode ser uma cadeia de caracteres estática para enriquecimento estático ou um dos valores suportados 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 lista a seguir inclui os valores suportados:
Atributos do cliente
- ${client.authenticationName}: o nome do cliente de publicação.
- ${client.attributes.x}: um atributo do cliente de publicação, onde x é o nome da chave do atributo.
Propriedades MQTT
- ${mqtt.message.userProperties.x}: propriedades do usuário no pacote MQTTv5 PUBLI, onde x é o nome da chave de propriedade do usuário
- Tipo: string
- Em vez disso, use o seguinte formato de variável se sua propriedade user incluir caracteres especiais ${mqtt.message.userProperties['x']}. Você ainda precisa escapar de um apóstrofo e barra invertida da seguinte forma: e "PN\t" se torna "PN\t".
- ${mqtt.message.topicName}: o tópico no pacote MQTT PUBLISHING.
- Tipo: string
- ${mqtt.message.responseTopic}: o tópico de resposta no pacote MQTTv5 PUBLISHING.
- Tipo: string
- ${mqtt.message.correlationData}: os dados de correlação no pacote MQTTv5 PUBLI.
- Tipo: binário
- ${mqtt.message.pfi}: o indicador de formato de carga útil no pacote MQTTv5 PUBLISHING.
- Tipo: inteiro
Configuração do portal do Azure
Use as seguintes etapas para configurar o enriquecimento de roteamento:
- Vá para seu namespace no portal do Azure.
- Em Roteamento, marque Habilitar roteamento.
- Em Tópico de roteamento, selecione o tópico Grade de Eventos que você criou onde todas as mensagens MQTT serão roteadas.
- Em Enriquecimento de Mensagem, selecione + Adicionar Enriquecimento.
- Adicione até 20 pares chave-valor e selecione seu tipo apropriadamente.
- Selecione Aplicar.
Para obter mais informações sobre a configuração de roteamento, vá para Configuração do portal do Azure de roteamento.
Configuração da CLI do Azure
Use o comando e a carga útil durante a criação/atualização do namespace para configurar o enriquecimento 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, vá para Configuração da CLI do Azure Roteamento.
Resultado da Amostra
O CloudEvent a seguir é uma saída de exemplo de uma mensagem MQTTv5 com PFI=0 depois de aplicar a 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==
}
}
Manuseamento de casos especiais:
- Atributos de cliente não especificados/propriedades de usuário: se um enriquecimento dinâmico apontou para uma propriedade de atributo/usuário 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: matrizes em atributos de cliente e propriedades de usuário duplicadas são transformadas em uma cadeia de caracteres separada por vírgula. Por exemplo: se o atributo de cliente enriquecido estiver 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 > de usuário "userproperty1": "value1", "userproperty1": "value2", a propriedade enriquecida resultante seráuserproperty1:value1,value2.
Passos seguintes:
Use os seguintes artigos para saber mais sobre roteamento:
Início rápido:
- Tutorial: Encaminhar mensagens MQTT para Hubs de Eventos do Azure usando tópicos de namespace
- Tutorial: Encaminhar mensagens MQTT para o Azure Functions usando tópicos personalizados