Compatibilidad con la función Retain de MQTT en Azure Event Grid

La función de retención de Message Queuing Telemetry Transport (MQTT) en Azure Event Grid garantiza que el último valor válido conocido de una etiqueta o categoría se almacene y esté fácilmente disponible para los nuevos suscriptores. Esta funcionalidad permite a los nuevos clientes recibir instantáneamente el mensaje más reciente tras la conexión, lo que elimina la necesidad de esperar a la próxima publicación. Es útil en escenarios como la notificación del estado de los dispositivos, las señales de control o los datos de configuración, donde el acceso oportuno al mensaje más reciente es fundamental.

Este artículo ofrece una descripción general del funcionamiento de MQTT Retain, sus implicaciones en la facturación, los límites de almacenamiento, los métodos de eliminación de mensajes y las consideraciones sobre la gestión de Retain.

Facturación

Una publicación conservada se cuenta como dos operaciones MQTT: una para procesar el mensaje y otra para almacenarlo.

Límites de Storage

• Hasta 640 MB o 10 000 mensajes retenidos por unidad de rendimiento (TU).
• El tamaño máximo por mensaje retenido es de 64 KB.

Para necesidades mayores, póngase en contacto con el soporte técnico de Azure.

Eliminación de mensajes

• MQTT 3.1.1: publicar una carga vacía en el tema. Para establecer la expiración, póngase en contacto con el soporte técnico de Azure.
• MQTT 5.0: establezca la expiración o envíe un mensaje vacío para quitarlo.

Mensajes retenidos: Obtener y enumerar

Los mensajes retenidos permiten que un agente MQTT almacene el último mensaje conocido en un tema para que los nuevos suscriptores reciban inmediatamente el valor actual sin esperar a la próxima publicación. Ahora puede usar los siguientes puntos de conexión de administración HTTP:

• Retain Get: obtiene el cuerpo del mensaje retenido en bruto para un tópico específico. Los metadatos del mensaje se devuelven a través de encabezados HTTP.
• Lista de retención: aquí figuran los mensajes retenidos que coincidan con un filtro de etiqueta (se admiten caracteres comodín) o hace un recorrido por los resultados con un token de continuación.

Usa estas API para realizar tareas de observabilidad, auditoría y flujos de trabajo operativos (por ejemplo, dar soporte a la solución de problemas, realizar reposiciones o comprobar el estado del dispositivo a escala).

Autenticación y autorización

Las APIs Retain Get y Retain List requieren:

• Autenticación: Authorization: Bearer <token>.
• Audiencia o nivel del token: use el URI del identificador de la aplicación o el recurso del agente facilitado para este ejemplo (reemplace <YOUR TOKEN HERE> en los ejemplos).
• RBAC: el autor de la llamada debe tener permiso para invocar operaciones de lectura de mensajes retenidos en el espacio de nombres.

Para obtener el token de portador, ejecute el siguiente comando de la CLI de Azure:

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

API de referencia

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

Respuesta:

• Cuerpo: carga de mensajes mediante MQTT sin formato (bytes).
• Encabezados: incluyen metadatos del mensaje (nombres sujetos a cambios en la versión preliminar):
  • x-ms-mqtt-topic: tema del mensaje retenido.
  • x-ms-mqtt-qos: nivel de QoS (0 o 1).
  • x-ms-mqtt-size: tamaño completo del mensaje MQTT (bytes).
  • x-ms-mqtt-expiry: marca de tiempo de expiración (ISO 8601) si se establece.
  • x-ms-mqtt-last-modified: marca de tiempo modificada por última vez (ISO 8601).

Retain List

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 admite caracteres comodín (por ejemplo, factory/+/state, sensors/#).
• continuationToken es mutuamente excluyente con topicFilter. Úselo para continuar desde una página anterior.
• maxResults limita el tamaño de la página (de 1 a 100).

Respuesta (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

Ejemplo de codificación url

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

Retain Get: Ejemplo 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"

Respuesta de ejemplo:

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

Mantener lista con "topicFilter": ejemplo 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"

Respuesta de ejemplo:

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

Retain List con continuationToken: Ejemplo de curl

NEXT_LINK="<PASTE NEXTLINK FROM PRIOR CALL>"

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

Comportamiento, límites y rendimiento

• rango maxResults: de 1 a 100 por página.
• Filtro de tema: admite caracteres + comodín MQTT estándar y # (codificado en dirección URL).
• Tamaño de carga: devuelto como bytes sin formato (sin envoltura JSON).
• Encabezados: fuente única de metadatos en el método Get; no se espera a un contenedor JSON.
• Paginación: siga nextLink hasta null. No mezcle topicFilter con continuationToken.
• Limitación: podrían aplicarse limitaciones de plataforma estándar (429). Use reintentos con retroceso.

Control de errores y solución de problemas

• 400 Solicitud incorrecta: formato incorrecto o falta del tema o del filtro de tema; se proporcionaron tanto el filtro de tema como el token de continuación.
• 401 No autorizado: token no válido o expirado o audiencia incorrecta.
• 403 Prohibido: el autor de la llamada carece de permiso en el espacio de nombres.
• 404 No encontrado: no se ha conservado ningún mensaje para el tema especificado.
• 409 Conflicto: la solicitud infringe las restricciones de vista previa.
• 429 Demasiadas solicitudes: limitación; cumple con Retry-After.
• 5xx: error transitorio del servicio; vuelva a intentar con retroceso exponencial.