Suporte para retenção de MQTT na Grade de Eventos do Azure

O recurso Retain do Transporte de Telemetria de Enfileiramento de Mensagens (MQTT) na Grade de Eventos do Azure garante que o último valor conhecido como bom de um tópico esteja armazenado e prontamente disponível para novos assinantes. Essa funcionalidade permite que novos clientes recebam instantaneamente a mensagem mais recente na conexão, eliminando a necessidade de aguardar a próxima publicação. Ele é benéfico em cenários como relatórios de estado do dispositivo, sinais de controle ou dados de configuração, em que o acesso oportuno à mensagem mais recente é crítico.

Este artigo fornece uma visão geral de como o MQTT Retain funciona, suas implicações de cobrança, limites de armazenamento, métodos de exclusão de mensagens e considerações de gerenciamento de retenção.

Faturamento

Uma publicação retida é contada como duas operações MQTT: uma para processar a mensagem e outra para armazená-la.

Limites de armazenamento

• Até 640 MB ou 10.000 mensagens retidas por unidade de produtividade (TU).
• O tamanho máximo por mensagem retida é de 64 KB.

Para maiores necessidades, entre em contato com o Suporte do Azure.

Exclusão de mensagem

• MQTT 3.1.1: publicar uma carga vazia no tópico. Para definir a expiração, entre em contato com o suporte do Azure.
• MQTT 5.0: defina a expiração ou envie uma mensagem vazia para removê-la.

Mensagens retidas – Obter e Listar

As mensagens retidas permitem que um agente do MQTT armazene a última mensagem conhecida em um tópico para que novos assinantes recebam imediatamente o valor atual sem esperar pela próxima publicação. Agora você pode usar os seguintes endereços de gerenciamento HTTP:

• Retenha Get: busca o corpo bruto da mensagem retida para um tópico específico. Os metadados da mensagem são retornados por meio de cabeçalhos HTTP.
• Lista de Retenção: enumera mensagens retidas que correspondem a um filtro de tópico (caracteres curingas suportados) ou navegue pelos resultados com um token de continuação.

Use essas APIs para observabilidade, auditoria e fluxos de trabalho operacionais (por exemplo, suporte para solução de problemas, backfills ou verificação do estado do dispositivo em escala).

Autenticação e autorização

As APIs da Lista de Retenção e Obtenção exigem:

• Autenticação: Authorization: Bearer <token>.
• Escopo ou audiência de token: use o URI do ID do App do broker ou o recurso fornecido para esta versão prévia (substitua <YOUR TOKEN HERE> em amostras).
• RBAC: o chamador deve ter permissão para invocar operações de leitura de mensagem retidas no namespace.

Para obter o token de portador, execute o seguinte comando da CLI do Azure:

az account get-access-token --resource=https://eventgrid.azure.net --query accessToken -o tsv

API de referência

Reter comando Get

GET /mqtt/retainedMessages/message?topic=<YOUR ENCODED TOPIC HERE>&api-version=2025-11-16-preview HTTP/1.1
Authorization: Bearer YOURENTRATOKEN
Host: <YOUR Event Grid MQTT BROKER URL HERE>

Resposta:

• Corpo: conteúdo de mensagem MQTT bruto (bytes).
• Cabeçalhos: incluem metadados de mensagem (nomes sujeitos a alterações na versão de pré-visualização):
  • x-ms-mqtt-topic: tópico da mensagem retida.
  • x-ms-mqtt-qos: Nível de QoS (0 ou 1).
  • x-ms-mqtt-size: tamanho completo da mensagem MQTT (bytes).
  • x-ms-mqtt-expiry: carimbo de data/hora de expiração (ISO 8601) se estabelecido.
  • x-ms-mqtt-last-modified: marca temporal modificada pela última vez (ISO 8601).

Lista de Retenção

GET /mqtt/retainedMessages?topicFilter=<YOUR ENCODED TOPIC FILTER HERE>&continuationToken=<MUTUALLY EXCLUSIVE WITH TOPIC FILTER>&maxResults=<1-100>&api-version=2025-11-16-preview HTTP/1.1
Authorization: Bearer YOURENTRATOKEN
Host: <YOUR Event Grid MQTT BROKER URL HERE>

• topicFilter dá suporte a curingas (por exemplo, factory/+/state, sensors/#).
• continuationToken é mutuamente exclusivo com topicFilter. Use-o para continuar de uma página anterior.
• maxResults delimita o tamanho da página (1 a 100).

Resposta (JSON):

{
    "nextLink": "<NULL OR URL HERE>",
    "retainedMessages": [
        {
            "topic": "<SOME TOPIC>",
            "qos": "<SOME QOS>",
            "size": "<FULL MQTT MESSAGE SIZE>",
            "expiry": "<TIME STAMP>",
            "lastModifiedTime": "<TIME STAMP>"
        }
    ]
}

Exemplos

Exemplo de codificação de URL

• Tópico: factory/line1/cell17/state
  • Codificado: factory%2Fline1%2Fcell17%2Fstate
• Filtro: factory/line1/+/state
  • Codificado: factory%2Fline1%2F%2B%2Fstate

Manter o método GET – exemplo de curl

BROKER="<YOUR BROKER URL HERE>"  # e.g. contoso.westus.ts.eventgrid.azure.net
ENTRATOKEN="<YOUR TOKEN HERE>"
TOPIC_ENC="factory%2Fline1%2Fcell17%2Fstate"

curl -i \
  -H "Authorization: Bearer $ENTRATOKEN" \
  "https://$BROKER/mqtt/retainedMessages/message?topic=$TOPIC_ENC&api-version=2025-11-16-preview"

Resposta de exemplo:

HTTP/1.1 200 OK
x-ms-mqtt-topic: factory/line1/cell17/state
x-ms-mqtt-qos: 1
x-ms-mqtt-size: 42
x-ms-mqtt-expiry: 2025-11-16T08:13:05Z
x-ms-mqtt-last-modified: 2025-11-16T07:59:41Z
content-type: application/octet-stream

{"state":"READY","tempC":25.1,"ts":"2025-11-16T07:59:40Z"}

Manter lista com filtro de tópico – exemplo de curl

BROKER="<YOUR BROKER URL HERE>"
ENTRATOKEN="<YOUR TOKEN HERE>"
FILTER_ENC="factory%2Fline1%2F%2B%2Fstate"

curl -sS \
  -H "Authorization: Bearer $ENTRATOKEN" \
  "https://$BROKER/mqtt/retainedMessages?topicFilter=$FILTER_ENC&maxResults=50&api-version=2025-11-16-preview"

Resposta de exemplo:

{
  "nextLink": null,
  "retainedMessages": [
    {
      "topic": "factory/line1/cell17/state",
      "qos": 1,
      "size": 42,
      "expiry": "2025-11-16T08:13:05Z",
      "lastModifiedTime": "2025-11-16T07:59:41Z"
    },
    {
      "topic": "factory/line1/cell18/state",
      "qos": 1,
      "size": 41,
      "expiry": null,
      "lastModifiedTime": "2025-11-16T07:55:02Z"
    }
  ]
}

Lista de Retenção com continuationToken: exemplo de curl

NEXT_LINK="<PASTE NEXTLINK FROM PRIOR CALL>"

curl -sS -H "Authorization: Bearer $ENTRATOKEN" "$NEXT_LINK"

Comportamento, limites e desempenho

• intervalo maxResults: 1 a 100 por página.
• Filtro de tópico: dá suporte a curingas padrão do MQTT + e # (ambos codificados na URL).
• Tamanho da carga: retornado como bytes brutos (sem encapsulamento JSON).
• Cabeçalhos: fonte única para metadados em Get, não espere um envelope JSON.
• Paginação: siga nextLink até null. Não misture topicFilter com continuationToken.
• Limitação: as restrições de plataforma padrão podem ser aplicadas (429). Use a repetição com backoff.

Tratamento de erros e solução de problemas

• 400 Solicitação Inválida: tópico malformado ou ausente ou "topicFilter"; fornecidos juntos "topicFilter" e "continuationToken".
• 401 Não autorizado: token inválido ou expirado ou público errado.
• 403 Proibido: o chamador não tem permissão no namespace.
• 404 Não Encontrado: nenhuma mensagem retida para o tópico especificado.
• Conflito 409: a solicitação viola as restrições de visualização.
• 429 Solicitações Demais: limitadas, respeitar Retry-After.
• 5xx: erro de serviço transitório; tente novamente com recuo exponencial.