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

A API HTTP de Publicação do broker MQTT do Azure Event Grid permite aos clientes publicar mensagens MQTT (Message Queuing Telemetry Transport) utilizando pedidos 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 publicar em 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. O Event Grid mapeia partes do pedido HTTP para propriedades padrão dos pacotes MQTT PUBLISH.
  3. As mensagens fluem pelo pipeline de encaminhamento e enriquecimento do Event Grid, que assegura as garantias de entrega e aplica qualquer enriquecimento ou transformação necessária.

Exemplo: equivalente de publicação MQTT

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 seguinte descreve como as partes de um pedido HTTP correspondem às propriedades do pacote PUBLISH do MQTT. Consulte a documentação original para obter todos os detalhes.

Secção 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 Parâmetro de 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 array JSON em 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-interval 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 da mensagem 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 gerais para utilizar a publicação HTTP

  1. Prepare seu token de portador do Microsoft Entra ID para autenticação.
  2. Construa o seu pedido HTTP POST para o ponto final do broker MQTT do Event Grid.
  3. Inclua os parâmetros de consulta necessários, como o tópico.
  4. Adicione cabeçalhos opcionais para QoS, o indicador RETAIN, o tópico de resposta e as propriedades do utilizador.
  5. Adicione a sua carga útil no corpo HTTP.
  6. Envie o pedido.
  7. Confirme a entrega através dos logs e das métricas no portal do Event Grid.

Autenticação e autorização

  • O HTTP Publish utiliza o Microsoft Entra ID 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
  • Entidade principal de autorização

Melhores práticas

  • Utilize, sempre que possível, chaves de cabeçalho em minúsculas. 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

  • Última atualização a