Obsługa funkcji MQTT Retain w usłudze Azure Event Grid

Funkcja zachowywania transportu telemetrii kolejkowania komunikatów (MQTT) w usłudze Azure Event Grid gwarantuje, że ostatnia znana dobra wartość tematu jest przechowywana i łatwo dostępna dla nowych subskrybentów. Ta funkcja umożliwia nowym klientom natychmiastowe odbieranie najnowszych komunikatów po połączeniu, eliminując konieczność oczekiwania na następną publikację. Jest to korzystne w scenariuszach, takich jak raportowanie stanu urządzenia, sygnały sterowania lub dane konfiguracji, w których terminowy dostęp do najnowszego komunikatu jest krytyczny.

Ten artykuł zawiera omówienie działania funkcji zachowywania MQTT, jego wpływu na rozliczenia, limity magazynu, metody usuwania komunikatów i zagadnienia dotyczące zarządzania zachowaniem.

Fakturowanie

Zachowana publikacja jest liowana jako dwie operacje MQTT: jedna do przetwarzania komunikatu i jedna do jego przechowywania.

Limity magazynu

• Do 640 MB lub 10 000 zachowanych komunikatów na jednostkę przepływności (TU).
• Maksymalny rozmiar zachowanego komunikatu wynosi 64 KB.

W przypadku większych potrzeb skontaktuj się z pomocą techniczną platformy Azure.

Usuwanie komunikatów

• MQTT 3.1.1: Publikowanie pustego ładunku w temacie. Aby ustawić wygaśnięcie, skontaktuj się z pomocą techniczną platformy Azure.
• MQTT 5.0: Ustaw wygaśnięcie lub wyślij pusty komunikat, aby go usunąć.

Zachowane komunikaty — uzyskiwanie i wylistowanie

Zachowane komunikaty pozwalają brokerowi MQTT przechowywać ostatni znany komunikat w temacie, dzięki czemu nowi subskrybenci natychmiast otrzymają bieżącą wartość bez oczekiwania na następną publikację. Teraz możesz użyć następujących punktów końcowych zarządzania HTTP:

• Pobierz zachowany: pobiera surową zachowaną treść wiadomości dla określonego tematu. Metadane komunikatu są zwracane za pośrednictwem nagłówków HTTP.
• Lista zatrzymanych: wymienia zachowane komunikaty pasujące do filtra tematu (obsługuje symbole wieloznaczne) lub przeglądać wyniki za pomocą tokenu kontynuacji.

Te interfejsy API służą do obserwowania, inspekcji i operacyjnych przepływów pracy (na przykład obsługi rozwiązywania problemów, wypełniania kopii zapasowych lub weryfikowania stanu urządzenia na dużą skalę).

Uwierzytelnianie i autoryzacja

API "Retain Get" i "Retain List" wymagają:

• Uwierzytelnianie: Authorization: Bearer <token>.
• Odbiorcy tokenu lub zakres: użyj identyfikatora URI lub zasobu identyfikatora aplikacji brokera udostępnionego dla tej wersji zapoznawczej (zastąp <YOUR TOKEN HERE> w przykładach).
• RBAC: Obiekt wywołujący musi mieć uprawnienia do wywoływania operacji odczytu zachowanych wiadomości w przestrzeni nazw.

Aby uzyskać Bearer token, uruchom następujące polecenie Azure CLI:

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

Referencyjny interfejs API

Zachowaj pobieranie

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>

Odpowiedź:

• Treść: nieprzetworzone ładunek komunikatu MQTT (bajty).
• Nagłówki: zawierają metadane wiadomości (nazwy podlegają zmianie w wersji zapoznawczej):
  • x-ms-mqtt-topic: temat zachowanej wiadomości.
  • x-ms-mqtt-qos: poziom QoS (0 lub 1).
  • x-ms-mqtt-size: pełny rozmiar komunikatu MQTT (bajty).
  • x-ms-mqtt-expiry: sygnatura czasowa wygaśnięcia (ISO 8601), jeśli ustawiono.
  • x-ms-mqtt-last-modified: znacznik czasu ostatniej modyfikacji (ISO 8601).

Zachowaj 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 obsługuje symbole wieloznaczne (na przykład factory/+/state, sensors/#).
• continuationToken jest wzajemnie wykluczający z topicFilter. Użyj go, aby kontynuować z poprzedniej strony.
• maxResults określa rozmiar strony (1–100).

Odpowiedź (JSON):

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

Przykłady

Przykład kodowania adresów URL

• Temat: factory/line1/cell17/state
  • Zakodowany: factory%2Fline1%2Fcell17%2Fstate
• Filtr: factory/line1/+/state
  • Zakodowany: factory%2Fline1%2F%2B%2Fstate

Zachowaj przykład Get — 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"

Przykładowa odpowiedź:

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

Zachowaj listę z topicFilter — przykład użycia 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"

Przykładowa odpowiedź:

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

Zachowaj listę z elementem continuationToken — przykład curl

NEXT_LINK="<PASTE NEXTLINK FROM PRIOR CALL>"

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

Zachowanie, limity i wydajność

• zakres maxResults: 1–100 na stronę.
• Filtr tematu: obsługuje standardowe symbole wieloznaczne + MQTT i # (zakodowane w adresie URL).
• Rozmiar ładunku: zwracany jako nieprzetworzone bajty (bez zawijania JSON).
• Nagłówki: jedno źródło metadanych w funkcji Get; nie oczekuj koperty JSON.
• Stronicowanie: kontynuuj za pomocą nextLink, aż do napotkania wartości null. Nie mieszaj topicFilter z continuationToken.
• Ograniczanie przepustowości: mogą być stosowane standardowe ograniczenia platformy (429). Użyj ponawiania prób z opóźnieniami.

Obsługa błędów i rozwiązywanie problemów

• 400 Nieprawidłowe żądanie: błędnie sformułowany lub brakujący temat lub filtr tematu; dostarczono zarówno topicFilter, jak i continuationToken.
• 401 Brak autoryzacji: nieprawidłowy lub wygasły token lub niewłaściwi odbiorcy.
• 403 Zabronione: obiekt wywołujący nie ma uprawnień do przestrzeni nazw.
• 404 Nie znaleziono: brak zachowanego komunikatu dla określonego tematu.
• 409 Konflikt: żądanie narusza ograniczenia wersji zapoznawczej.
• 429 Zbyt wiele żądań: ograniczane; przestrzegaj Retry-After.
• 5xx: przejściowy błąd serwisu; ponów próbę z wykładniczym opóźnieniem.