Unterstützung für MQTT-Aufbewahrung im Azure Event Grid

Die Message Queuing Telemetry Transport (MQTT) Retain-Funktion in Azure Event Grid stellt sicher, dass der letzte bekannte gute Wert eines Themas gespeichert wird und für neue Abonnenten sofort verfügbar ist. Diese Funktion ermöglicht es neuen Kunden, sofort nach der Verbindung die neueste Nachricht zu erhalten, so dass sie nicht auf die nächste Veröffentlichung warten müssen. Dies ist in Szenarien von Vorteil, in denen der rechtzeitige Zugriff auf die neueste Nachricht entscheidend ist, wie z. B. bei der Meldung des Gerätezustands, bei Steuersignalen oder bei Konfigurationsdaten.

Dieser Artikel bietet einen Überblick über die Funktionsweise von MQTT Retain, die Auswirkungen auf die Abrechnung, Speichergrenzen, Methoden zum Löschen von Nachrichten und Überlegungen zur Verwaltung von Retain.

Abrechnung

Eine aufbewahrte Veröffentlichung wird als zwei MQTT-Vorgänge gezählt: eine für die Verarbeitung der Nachricht und eine zum Speichern.

Speichergrenzwerte

• Bis zu 640 MB oder 10.000 gespeicherte Nachrichten pro Durchsatzeinheit (TU).
• Die maximale Größe pro gespeicherte Nachricht beträgt 64 KB.

Kontaktieren Sie den Azure-Support.

Löschen von Nachrichten

• MQTT 3.1.1: Veröffentlichen Sie eine leere Nutzlast an das Topic. Um das Ablaufdatum festzulegen, wenden Sie sich an den Azure-Support.
• MQTT 5.0: Legen Sie das Ablaufdatum fest oder senden Sie eine leere Nachricht, um es zu entfernen.

Beibehaltene Nachrichten – Abrufen und Auflisten

Mit beibehaltenen Nachrichten kann ein MQTT-Broker die letzte bekannte Nachricht in einem Thema speichern, sodass neue Abonnenten sofort den aktuellen Wert erhalten, ohne auf die nächste Veröffentlichung zu warten. Jetzt können Sie die folgenden HTTP-Verwaltungsendpunkte verwenden:

• Retain Get: Ruft den unformatierten Nachrichtentextkörper für ein bestimmtes Thema ab. Die Nachrichtenmetadaten werden über HTTP-Header zurückgegeben.
• Retain List: Listet zurückgehaltene Nachrichten auf, die einem Themenfilter entsprechen (Platzhalter werden unterstützt) oder blättert die Ergebnisse mit einem Fortsetzungs-Token durch.

Verwenden Sie diese APIs für Beobachtbarkeits-, Audit- und Betriebsworkflows (z. B. Unterstützung bei der Problembehandlung, Rückfüllvorgänge oder Überprüfung des Gerätezustands in großem Maßstab).

Authentifizierung und Autorisierung

Für die Retain Get- und Retain List-APIs ist Folgendes erforderlich:

• Authentifizierung: Authorization: Bearer <token>.
• Token Zielgruppe oder Bereich: Verwenden Sie die App ID URI des Brokers oder die für diese Vorschau bereitgestellte Ressource (ersetzen Sie <YOUR TOKEN HERE> in den Beispielen).
• RBAC: Der Aufrufer muss über die Berechtigung zum Aufrufen beibehaltener Nachrichtenlesevorgänge im Namespace verfügen.

Führen Sie zum Abrufen des Bearer-Tokens den folgenden Azure CLI-Befehl aus:

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

Referenz-API

Behalten Erhalten

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>

Antwort:

• Hauptteil: rohe MQTT-Nutzlast (Bytes).
• Kopfzeilen: Nachrichtenmetadaten einschließen (Namen, die in der Vorschau geändert werden können):
  • x-ms-mqtt-topic: Thema der aufbewahrten Nachricht.
  • x-ms-mqtt-qos: QoS-Ebene (0 oder 1).
  • x-ms-mqtt-size: vollständige MQTT-Nachrichtengröße (Bytes).
  • x-ms-mqtt-expiry: Ablaufzeitstempel (ISO 8601) bei Festlegung.
  • x-ms-mqtt-last-modified: Zeitstempel der letzten Änderung (ISO 8601).

Liste beibehalten

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 unterstützt Wildcards (z. B factory/+/state, sensors/#. ).
• continuationToken schließt sich gegenseitig mit topicFilter aus. Verwenden Sie sie, um von einer vorherigen Seite fortzufahren.
• maxResults begrenzt die Seitengröße (1–100).

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

Beispiel für die URL-Codierung

• Thema: factory/line1/cell17/state
  • Codiert: factory%2Fline1%2Fcell17%2Fstate
• Filter: factory/line1/+/state
  • Codiert: factory%2Fline1%2F%2B%2Fstate

Behalten Erhalten - curl Beispiel

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"

Beispielantwort:

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

Behalten Liste mit topicFilter - curl Beispiel

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"

Beispielantwort:

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

Behalten Liste mit continuationToken - curl Beispiel

NEXT_LINK="<PASTE NEXTLINK FROM PRIOR CALL>"

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

Verhalten, Grenzwerte und Leistung

• maxResults-Bereich: 1 bis 100 pro Seite.
• Themenfilter: unterstützt standardmäßige MQTT-Wildcards + und # (codiert in URL).
• Nutzlastgröße: als unformatierte Bytes (kein JSON-Wrapping) zurückgegeben.
• Kopfzeilen: einzelne Quelle für Metadaten in "Get"; erwarten Sie keinen JSON-Umschlag.
• Paging: folgen Sie nextLink bis null. Mischen Sie "topicFilter" nicht mit "continuationToken".
• Drosselung: Es gelten ggf. die üblichen Plattformdrosselungen (429). Verwenden Sie Wiederholungsversuche mit Backoff.

Fehlerbehandlung und Fehlerbehebung

• 400 Ungültige Anfrage: fehlerhaftes oder fehlendes Thema oder topicFilter; hat sowohl topicFilter als auch continuationToken bereitgestellt.
• 401 Nicht autorisiert: ungültiges oder abgelaufenes Token oder falsche Zielgruppe.
• 403 Verboten: Der Aufrufer besitzt keine Berechtigung für den Namespace.
• 404 Nicht gefunden: Keine beibehaltene Nachricht für das angegebene Thema.
• 409 Konflikt: Die Anforderung verstößt gegen Vorschaueinschränkungen.
• 429 Zu viele Anfragen: gedrosselt; Später erneut versuchen einhalten.
• 5xx: vorübergehender Dienstfehler; Wiederholungsversuch mit exponentiellem Backoff.