Prise en charge de la conservation de MQTT dans Azure Event Grid

La fonctionnalité `Retain` de Message Queuing Telemetry Transport (MQTT) dans Azure Event Grid garantit que la dernière valeur correcte connue d’un sujet est stockée et facilement disponible pour les nouveaux abonnés. Cette fonctionnalité permet aux nouveaux clients de recevoir instantanément le message le plus récent lors de la connexion, ce qui élimine la nécessité d’attendre la publication suivante. Elle est utile dans les scénarios tels que le reporting sur l’état des appareils, les signaux de contrôle ou les données de configuration, où un accès rapide au dernier message est essentiel.

Cet article présente le fonctionnement de MQTT Retain, ses implications en matière de facturation, ses limites de stockage, ses méthodes de suppression de messages et des considérations relatives à sa gestion.

Facturation

Une publication conservée est comptabilisée comme deux opérations MQTT : une pour le traitement du message et l’autre pour le stockage.

Limites de stockage

• Jusqu’à 640 Mo ou 10 000 messages conservés par unité de débit (TU).
• La taille maximale par message conservé est de 64 Ko.

Pour des besoins plus importants, contactez le support Azure.

Suppression de messages

• MQTT 3.1.1 : publiez une charge utile vide dans la rubrique. Pour définir l’expiration, contactez le support Azure.
• MQTT 5.0 : définissez l’expiration ou envoyez un message vide pour le supprimer.

Messages conservés : Obtenir et répertorier

Les messages conservés permettent à un répartiteur MQTT de stocker le dernier message connu sur une rubrique afin que les nouveaux abonnés reçoivent immédiatement la valeur actuelle sans attendre la publication suivante. Vous pouvez maintenant utiliser les points de terminaison de gestion HTTP suivants :

• Conserver Get : récupère le corps du message conservé brut pour une rubrique spécifique. Les métadonnées du message sont retournées via des en-têtes HTTP.
• Retain List : énumère les messages conservés correspondant à un filtre de rubrique (caractères génériques pris en charge) ou parcourt les résultats avec un jeton de continuation.

Utilisez ces API pour l’observabilité, l’audit et les flux de travail opérationnels (par exemple, prendre en charge la résolution des problèmes, les remblais ou vérifier l’état de l’appareil à grande échelle).

Authentification et autorisation

Les API Retain Get et Retain List nécessitent les éléments suivants :

• Auth : Authorization: Bearer <token>.
• Audience ou étendue de jeton : utilisez l’URI ID d’application du broker ou la ressource fournie pour cette version préliminaire. (Remplacez <YOUR TOKEN HERE> dans les exemples.)
• RBAC : l’appelant doit avoir l’autorisation d’appeler des opérations de lecture de message conservées sur l’espace de noms.

Pour obtenir le jeton du porteur, exécutez la commande Azure CLI suivante :

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

API de référence

Conserver la fonction 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>

Réponse :

• Corps : charge utile de message MQTT brute (octets).
• En-têtes : inclure des métadonnées de message (noms susceptibles de changer en préversion) :
  • x-ms-mqtt-topic: sujet du message conservé.
  • x-ms-mqtt-qos: niveau QoS (0 ou 1).
  • x-ms-mqtt-size: taille complète du message MQTT (octets).
  • x-ms-mqtt-expiry: horodatage d’expiration (ISO 8601) s’il est défini.
  • x-ms-mqtt-last-modified: dernier horodatage modifié (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 prend en charge les caractères génériques (par exemple, factory/+/state, sensors/#).
• continuationToken est mutuellement exclusif avec topicFilter. Utilisez-la pour continuer à partir d’une page précédente.
• maxResults limite la taille de la page (1 à 100).

Réponse (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

Exemple d’encodage d’URL

• Sujet: factory/line1/cell17/state
  • Encodé: factory%2Fline1%2Fcell17%2Fstate
• Filtre: factory/line1/+/state
  • Encodé: factory%2Fline1%2F%2B%2Fstate

Conserver la requête GET - exemple 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"

Exemple de réponse :

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

Conserver la liste avec le filtre de sujet - exemple 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"

Exemple de réponse :

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

Conserver la liste avec continuationToken - exemple de commande curl

NEXT_LINK="<PASTE NEXTLINK FROM PRIOR CALL>"

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

Comportement, limites et performances

• plage maxResults : 1 à 100 par page.
• Filtre de rubrique : prend en charge les + caractères génériques MQTT standard et # (encodés dans l’URL).
• Taille de la charge utile : retournée sous forme d’octets bruts (sans habillage JSON).
• En-têtes : source unique pour les métadonnées dans Get ; ne vous attendez pas à une enveloppe JSON.
• Pagination : suivez nextLink jusqu’à null. Ne mélangez pas topicFilter avec continuationToken.
• Limitation : les limitations de plateforme standard peuvent s’appliquer (429). Utilisez une nouvelle tentative avec backoff.

Gestion des erreurs et dépannage

• 400 Requête incorrecte : rubrique ou topicFilter incorrect(e) ou manquant(e) ; fourniture de topicFilter et continuationToken.
• 401 Non autorisé : jeton non valide ou arrivé à expiration ou audience incorrecte.
• 403 Interdit : l’appelant n’a pas d’autorisation sur l’espace de noms.
• 404 Introuvable : aucun message conservé pour la rubrique spécifiée.
• Conflit 409 : la requête enfreint les contraintes d’aperçu.
• 429 Trop de requêtes : limitées; respectez le champ Retry-After.
• 5xx : erreur de service temporaire ; réessayez avec backoff exponentiel.