Suporte para MQTT Retain no Azure Event Grid

O recurso Message Queuing Telemetry Transport (MQTT) Retain no Azure Event Grid garante que o último valor válido conhecido de um tópico seja armazenado de forma a estar prontamente disponível para novos assinantes. Esse recurso permite que novos clientes recebam instantaneamente a mensagem mais recente após a conexão, eliminando a necessidade de esperar pela próxima publicação. É benéfico em cenários como relatórios de estado do dispositivo, sinais de controle ou dados de configuração, onde o acesso oportuno à mensagem mais recente é fundamental.

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

Faturação

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

Limites de armazenamento

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

Para necessidades maiores, contacte o Suporte do Azure.

Eliminação de mensagens

• MQTT 3.1.1: Publique uma carga vazia no tópico. Para definir a expiração, contacte 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 corretor MQTT armazene a última mensagem conhecida num tema, para que os novos subscritores recebam imediatamente o valor atual sem esperar pela próxima publicação. Agora pode usar os seguintes endpoints de gestão HTTP:

• Retain Get: recupera o corpo bruto da mensagem retida para um tópico específico. Os metadados da mensagem são devolvidos através de cabeçalhos HTTP.
• Retain List: enumera mensagens retidas que correspondem a um filtro de tópico (curingas suportadas) ou a página através de resultados com um token de continuação.

Use estas APIs para observabilidade, auditoria e fluxos de trabalho operacionais (como, por exemplo, para suportar a resolução de problemas, backfills ou verificação do estado do dispositivo em escala).

Autenticação e autorização

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

• Auth: Authorization: Bearer <token>.
• Audiência ou âmbito do token: Utilize o ID da App, o URI ou recurso fornecido pelo corretor para esta pré-visualização (substitua <YOUR TOKEN HERE> em exemplos).
• RBAC: O chamador deve ter permissão para invocar operações de leitura de mensagens retidas no namespace.

Para obter o token Bearer, execute o seguinte comando Azure CLI:

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

API de referência

Reter Obter

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: carga útil bruta de mensagens MQTT (bytes).
• Cabeçalhos: incluem metadados da mensagem (nomes sujeitos a alterações na visualização prévia):
  • x-ms-mqtt-topic: tema 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 temporal de expiração (ISO 8601) caso esteja definido.
  • x-ms-mqtt-last-modified: marca temporal modificada mais recente (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 suporta curingas (por exemplo, factory/+/state, sensors/#).
• continuationToken é mutuamente exclusivo em relação a topicFilter. Use-o para continuar a partir de uma página anterior.
• maxResults limita o tamanho da página (1–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>"
        }
    ]
}

Examples

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

Retain 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"

Exemplo de resposta:

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"}

Retain List com filtro de tópicos - exemplo de uso do 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"

Exemplo de resposta:

{
  "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 de maxResults: 1–100 por página.
• Filtro de tópico: suporta curingas + MQTT padrão e # (codificado em URL).
• Tamanho da carga útil: devolvido como bytes brutos (sem envolvimento JSON).
• Cabeçalhos: fonte única para metadados no Get; Não esperes um envelope JSON.
• Paginação: siga nextLink até null. Não misture o topicFilter com o continuationToken.
• Limitação: podem aplicar-se as limitações padrão da plataforma (429). Usa retry com backoff.

Tratamento de erros e solução de problemas

• 400 Pedido Mal Formado: tópico malformado ou em falta; forneceu tanto topicFilter como continuationToken.
• 401 Não autorizado: token inválido ou expirado ou destinatário incorreto.
• 403 Proibido: o chamador não tem permissão no namespace.
• 404 Não Encontrado: não há mensagem retida para o tópico especificado.
• 409 Conflito: pedido viola restrições de pré-visualização.
• 429 pedidos a mais: limitado; Respeita Retry-After.
• 5xx: erro de serviço transitório; Tenta novamente com recuo exponencial.