Azure Event Grid での MQTT Retain のサポート

Azure Event Grid のメッセージキューテレメトリトランスポート (MQTT) 保持機能により、トピックの最後の既知の適切な値が格納され、新しいサブスクライバーがすぐに使用できるようになります。この機能により、新しいクライアントは接続時に最新のメッセージをすぐに受信できるため、次の発行を待つ必要がなくなります。これは、最新のメッセージにタイミングよくアクセスすることが重要である、デバイス状態レポート、制御信号、構成データなどのシナリオで役立ちます。

この記事では、MQTT Retain の仕組み、その課金への影響、ストレージ制限、メッセージ削除方法、および Retain 管理に関する考慮事項の概要について説明します。

請求書

保持された発行は、2 つの MQTT 操作としてカウントされます。1 つはメッセージの処理用と格納用です。

ストレージの制限

スループットユニット (TU) あたり最大 640 MB または 10,000 個の保持メッセージ。
保持メッセージあたりの最大サイズは 64 KB です。

より大きなニーズについては、Azure サポートにお問い合わせください。

メッセージの削除

MQTT 3.1.1: 空のペイロードをトピックに発行します。有効期限を設定するには、Azure サポートにお問い合わせください。
MQTT 5.0: 有効期限を設定するか、空のメッセージを送信して削除します。

保持されるメッセージ – 取得と一覧表示

保持されたメッセージを使用すると、MQTT ブローカーは トピックに最後の既知のメッセージ を格納できるため、新しいサブスクライバーは次の発行を待たずに、すぐに現在の値を受け取ることができます。次の HTTP 管理エンドポイントを使用できるようになりました。

リテイン取得: 特定のトピックの未加工のリテインメッセージ本文を取得します。メッセージメタデータは HTTP ヘッダーを介して返されます。
リストの保持: トピックフィルター (サポートされているワイルドカード) またはページに一致する保持メッセージを、継続トークンを使用して結果を通じて列挙します。

監視 、監査、運用のワークフロー にこれらの API を使用します (たとえば、トラブルシューティング、バックフィル、大規模なデバイスの状態の確認をサポートします)。

認証と承認

Retain Get および Retain List の API には、次のものが必要です。

認証: Authorization: Bearer <token>。
トークンの対象ユーザーまたはスコープ: このプレビュー用に提供されているブローカーのアプリ ID URI またはリソースを使用します (サンプルの <YOUR TOKEN HERE> を置き換えます)。
RBAC: 呼び出し元には、名前空間に対して保持されているメッセージ読み取り操作を呼び出すアクセス許可が必要です。

Bearer トークンを取得するには、次の Azure CLI コマンドを実行します。

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

リファレンス API

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>

応答:

ボディ: 生の MQTT メッセージペイロード (バイト)。
ヘッダー: メッセージメタデータを含めます (名前はプレビューで変更される可能性があります)。
- x-ms-mqtt-topic: 保持されるメッセージのトピック。
- x-ms-mqtt-qos: QoS レベル (0 または 1)。
- x-ms-mqtt-size: 完全な MQTT メッセージサイズ (バイト)。
- x-ms-mqtt-expiry: 設定されている場合、有効期限のタイムスタンプ (ISO 8601)。
- x-ms-mqtt-last-modified: 最終変更タイムスタンプ (ISO 8601)。

リストの保持

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 では、ワイルドカード ( factory/+/state, sensors/# など) がサポートされます。
continuationToken は topicFilter と相互に排他的です。これを使用して、前のページから続行します。
maxResults は、ページサイズ (1 ~ 100) を制限します。

応答 (JSON):

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

例示

URL エンコードの例

トピック： factory/line1/cell17/state
- エンコード： factory%2Fline1%2Fcell17%2Fstate
フィルター： factory/line1/+/state
- エンコード： factory%2Fline1%2F%2B%2Fstate

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

サンプルの応答:

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

topicFilter を使用してリストを保持する - 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"

サンプルの応答:

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

continuationToken でリストを保持する - curl の例

NEXT_LINK="<PASTE NEXTLINK FROM PRIOR CALL>"

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

動作、制限、およびパフォーマンス

maxResults の範囲: 1 ページあたり 1 ~ 100。
トピックフィルター: 標準の MQTT ワイルドカード + と # (URL でエンコード) をサポートします。
ペイロードサイズ: 生バイトとして返されます (JSON ラップなし)。
ヘッダー: Get のメタデータの単一ソース。JSON エンベロープは想定されません。
ページング: null になるまで nextLink に従います。 topicFilter と continuationToken を混在させる必要はありません。
スロットリング: 標準プラットフォームのスロットリングが適用される場合があります (429)。バックオフ戦略を用いて再試行します。

エラー処理とトラブルシューティング

400 無効な要求: 形式が正しくないか、トピックまたは topicFilter が見つかりません。topicFilter と continuationToken の両方を指定しました。
401 未承認: 無効または期限切れのトークンまたは間違った対象ユーザー。
403 Forbidden: 呼び出し元に名前空間に対するアクセス許可がありません。
404 見つかりません: 指定されたトピックの保持メッセージがありません。
409 競合: 要求がプレビューの制約に違反しています。
429 リクエストが多すぎます: 制限されています。Retry-After を守ってください。
5xx: 一時的なサービスエラー。指数バックオフを使用して再試行します。

注

トピックが正確で (大文字と小文字が区別される) 正しく URL エンコードされていることを確認します。
ブローカーの適切な対象ユーザーまたはスコープを要求していることを確認します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-12-18