Compartilhar via

Publicação HTTP de mensagens MQTT com a Grade de Eventos do Azure (versão prévia)

A API de Publicação HTTP do Agente MQTT da Grade de Eventos do Azure permite que os clientes publiquem mensagens do Protocolo de Telemetria de Filas de Mensagens (MQTT) usando solicitações HTTP padrão. Essa capacidade complementa as conexões diretas de clientes MQTT. Ela oferece uma opção simples e escalonável para sistemas do lado do servidor que preferem usar HTTP para o envio de comandos e controle de dispositivos, atualizações ou gerenciamento de mensagens retidas.

Observação

Esse recurso está atualmente em versão prévia.

Benefícios principais:

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

Quando usar a Publicação HTTP

Considere usar a Publicação HTTP quando:

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

Como funciona

  1. Clientes HTTP emitem uma solicitação HTTP POST com detalhes da Publicação MQTT.
  2. A Grade de Eventos mapeia partes da solicitação HTTP para propriedades padrão do pacote MQTT PUBLISH.
  3. As mensagens fluem pelo pipeline de roteamento e enriquecimento da Grade de Eventos, que assegura as garantias de entrega e aplica qualquer enriquecimento ou transformação.

Exemplo: equivalente à 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 a seguir descreve como as partes da solicitação HTTP são mapeadas para as propriedades do pacote MQTT PUBLISH. Consulte a documentação original para obter todos os detalhes.

Parte da Publicação MQTT Tipo/Valores Localização Obrigatório Description
Nome do tópico Cadeia codificada em formato percent-encoding Consulta topic Yes Tópico MQTT para publicação
QoS 0 ou 1 Consulta qos ou cabeçalho mqtt-qos Não [padrão = 1] Nível de Qualidade de Serviço (QoS)
Sinalizador RETAIN 0 ou 1 Consulta retain ou cabeçalho mqtt-retain Não [padrão = 0] Se a mensagem deve ser retida
Tópico de resposta Cadeia codificada em formato percent-encoding 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 adicionais para acompanhamento
Propriedades do usuário Matriz JSON Base64 Cabeçalho mqtt-user-properties Não Propriedades personalizadas do usuário
Tipo de conteúdo fio Cabeçalho content-type Não Tipo de payload
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 do payload 0 ou 1 Cabeçalho mqtt-payload-format-indicator Não [padrão = 0] Indicador de formato
Conteúdo Bytes Corpo HTTP Não Corpo da mensagem

Notes:

  • Os valores de parâmetro de consulta substituem os valores de cabeçalho, se ambos estiverem presentes.
  • A codificação de porcentagem é obrigatória para o tópico e o tópico de resposta.
  • Os dados de correlação devem ser Base64-encoded.

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 agente MQTT da Grade de Eventos.
  3. Incluir os parâmetros de consulta obrigatórios, como o tópico.
  4. Adicione cabeçalhos opcionais para QoS, o sinalizador RETAIN, tópico de resposta e propriedades do usuário.
  5. Adicione seu payload como corpo HTTP.
  6. Enviar a solicitação.
  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 Microsoft Entra ID para autenticação.
  • É necessário um token de portador no cabeçalho de autorização.
  • O Microsoft Entra Object ID se torna o ID do cliente MQTT.
  • O modelo AuthN/AuthZ está alinhado com as conexões MQTT padrão.

Roteiros e observabilidade

Métricas e logs incluem:

  • Protocolo: http-publish
  • ID da Solicitação
  • Tópico
  • IP de origem
  • Entidade de segurança de autorização

Práticas recomendadas

  • Usar cabeçalhos em minúsculas sempre que possível. As chaves de cabeçalho HTTP/2 não diferenciam maiúsculas de minúsculas.
  • Monitorar a taxa de transferência, pois as mensagens HTTP tendem a ser maiores que as mensagens MQTT diretas.
  • Observe que a publicação HTTP compartilha limites de taxa de transferência com mensagens publicadas diretamente por MQTT.

Limitação

A publicação HTTP é contabilizada na sua cota de taxa de transferência total do MQTT. Monitore seu uso para não exceder os limites.

Conteúdo relacionado

  • Last updated on