Partilhar via

Publicação HTTP de mensagens MQTT com Azure Event Grid

A API de Publicação HTTP do Agente MQTT da Grade de Eventos do Azure permite que os clientes publiquem mensagens MQTT (Transporte de Telemetria de Enfileiramento de Mensagens) usando solicitações HTTP padrão. Esse recurso complementa as conexões diretas do cliente MQTT. Ele fornece uma opção simples e escalável para sistemas do lado do servidor que preferem HTTP para comando e controle de servidor para dispositivo, atualizações ou gerenciamento de mensagens retidas.

Principais vantagens:

  • Permite que os serviços back-end enviem mensagens MQTT sem manter abertas as sessões MQTT persistentes.
  • Ajuda a proteger a estabilidade do broker limitando sessões MQTT por cliente.
  • Garante o processamento consistente de mensagens originadas de MQTT e HTTP.

Quando usar a publicação HTTP

Considere o uso do HTTP Publish quando:

  • Seus serviços de back-end são nativos HTTP e precisam enviar comandos ou atualizações do dispositivo pelo MQTT.
  • Você deseja gerenciar mensagens retidas sem abrir uma conexão MQTT.
  • Você precisa aumentar a capacidade de publicação sem esgotar os limites de sessão.

Como funciona

  1. Os clientes HTTP emitem uma solicitação HTTP POST com detalhes do MQTT Publishing.
  2. A Grade de Eventos mapeia partes de solicitação HTTP para propriedades de pacote MQTT PUBLISH padrão.
  3. As mensagens fluem através do pipeline de roteamento e enriquecimento da Grade de Eventos, que garante garantias de entrega e aplica qualquer enriquecimento ou transformação.

Exemplo: MQTT Publish equivalente

PUBLISH Topic Name: devices/CXa-23112/prompt  
QoS: 1  
RETAIN: 0  
Response Topic: devices/CXa-23112/reply  
Correlation Data: >U±¶¶»/  
User Property: Urgency = alert  
User Property: RequestId = 55f4a7ee-b0b4-4d7f-8eb5-2edba2ced5d7  
Payload: Please accept terms of licensing and agreement

Exemplo: Solicitação de publicação HTTP

POST /mqtt/messages?topic=devices%2FCXa-23112%2Fprompt&api-version=2025-02-15-preview HTTP/1.1  
Host: nsname.westus3-1.ts.eventgrid.azure.net  
Authorization: Bearer <ENTRA_TOKEN_HERE>  
mqtt-qos: 1  
mqtt-retain: 0  
mqtt-response-topic: devices%2FCXa-23112%2Freply  
mqtt-correlation-data: PlXCscK2wrbCuy8=  
mqtt-user-properties: W3siVXJnZW5jeSI6ImFsZXJ0In0seyJSZXF1ZXN0SWQiOiI1NWY0YTdlZS1iMGI0LTRkN2YtOGViNS0yZWRiYTJjZWQ1ZDcifV0=  
Content-Type: text/plain;charset=UTF-8  
Date: Sun, 06 Nov 1994 08:49:37 GMT  
Content-Length: 46  

Please accept terms of licensing and agreement

Parâmetros de solicitação

A tabela a seguir descreve como as peças de solicitação HTTP são mapeadas para as propriedades do pacote MQTT PUBLISHING. Consulte a documentação original para obter todos os detalhes.

Parte de publicação MQTT Tipo/Valores Localização Obrigatório Description
Nome do tópico Cadeia de caracteres codificada por porcentagem Consulta topic Yes Tópico MQTT para publicar em
QoS 0 ou 1 Consulta qos ou cabeçalho mqtt-qos Não [padrão = 1] Nível de Qualidade de Serviço (QoS)
RETAIN bandeira 0 ou 1 Consulta retain ou cabeçalho mqtt-retain Não [padrão = 0] Se a mensagem deve ser mantida
Tópico de resposta Cadeia de caracteres codificada por porcentagem Cabeçalho mqtt-response-topic Não Tópico de resposta, se necessário
Dados de correlação Cadeia de caracteres Base64 Cabeçalho mqtt-correlation-data Não Dados extras para rastreamento
Propriedades do utilizador Matriz JSON Base64 Cabeçalho mqtt-user-properties Não Propriedades de usuário personalizadas
Tipo de conteúdo Corda Cabeçalho content-type Não Tipo de carga útil
Intervalo de expiração da mensagem Inteiro não assinado Cabeçalho mqtt-message-expiry Não Período de retenção em segundos
Indicador de formato de carga útil 0 ou 1 Cabeçalho mqtt-payload-format-indicator Não [padrão = 0] Indicador de formato
Carga útil Bytes Corpo HTTP Não Corpo da mensagem

Notes:

  • Os valores dos parâmetros de consulta substituem os valores de cabeçalho se ambos estiverem presentes.
  • A codificação percentual é necessária para o tópico e o tópico de resposta.
  • Os dados de correlação devem ser codificados em Base64.

Etapas de alto nível para usar a publicação HTTP

  1. Prepare seu token de portador do Microsoft Entra ID para autenticação.
  2. Construa sua solicitação HTTP POST para o ponto de extremidade do broker MQTT da Grade de Eventos.
  3. Inclua os parâmetros de consulta necessários, como o tópico.
  4. Adicione cabeçalhos opcionais para QoS, o sinalizador, o tópico de resposta e as RETAIN propriedades do usuário.
  5. Adicione sua carga como o corpo HTTP.
  6. Envie o pedido.
  7. Confirme a entrega por meio de logs e métricas no portal da Grade de Eventos.

Autenticação e autorização

  • A publicação HTTP usa o ID do Microsoft Entra para autenticação.
  • Um token de portador é necessário no cabeçalho de autorização.
  • A ID do objeto Microsoft Entra torna-se a ID do cliente MQTT.
  • O modelo AuthN/AuthZ se alinha com conexões MQTT padrão.

Roteamento e observabilidade

As métricas e os logs incluem:

  • Protocolo: http-publish
  • ID de solicitação
  • Tópico
  • IP de origem
  • Principal de autorização

Melhores práticas

  • Use teclas de cabeçalho minúsculas sempre que possível. As chaves de cabeçalho HTTP/2 não diferenciam maiúsculas de minúsculas.
  • Monitore a taxa de transferência porque as mensagens HTTP tendem a ser maiores do que as mensagens MQTT diretas.
  • Observe que HTTP Publish compartilha limites de taxa de transferência com mensagens diretas publicadas pelo MQTT.

Regulação de Velocidade

A publicação HTTP conta para sua cota geral de taxa de transferência MQTT. Monitorize a sua utilização para evitar exceder limites.

Conteúdo relacionado

  • Last updated on