Azure Service Bus 配信不能キュー (DLQ) を REST API で操作したい

Azure Service Bus

フルマネージドなメッセージング サービスです。
メッセージングとは、システム間でのメッセージのやり取りです。

詳しくは、以下のドキュメントをご覧ください。

Azure でキュー機能を提供するサービスとして、Service Bus の他に Azure Storage キューがあります。

Storage キューと Service Bus キューの違いや使い分けについては、以下のドキュメントにまとまっていますので、ご参照ください。

配信不能キュー

Azure Service Bus キューとトピック サブスクリプションには、配信不能キュー (DLQ : dead-letter queue) というセカンダリ キューが提供されます。この配信不能キューの目的は、受信者に配信できないメッセージや受信者が処理できなかったメッセージを保持することです。
なお、配信不能キュー内のメッセージは、自動的に削除されることはありません。

メッセージを配信不能キューに移動させるには

メインとなるキューの対象のメッセージが以下のいずれかの条件を満たすと、配信不能キューに移動させることができます。

• メッセージの最大配信数を超過した場合

メッセージの配信できる回数には上限 (既定値 10 回) があり、この配信回数の上限を超えると対象のメッセージは配信不能キューに移動します。

メッセージがピーク/ロック状態で配信されて明示的に削除されたか、ロックが期限切れになった場合に配信回数がカウントアップします。

• メッセージの有効期限が切れた場合

メッセージには有効期限が設けられており、この有効期限が切れたメッセージは配信不能キューに移動します。なお、この操作は明示的にこの操作を有効にした場合のみです。

有効期限が切れたメッセージを自動的に配信不能キューに移動させるには、以下のドキュメントの手順に従って設定してください。

配信不能キューを REST API で操作したい

まず、メッセージを直接配信不能キューに送信することはできません。前述したとおり、メインとなるキューのメッセージがある条件に満たした場合に配信不能キューに移動します。

よって、配信不能キューに格納されたメッセージに対する操作 (受信アクセス) を行うことができます。

アクセス制御

ここでは、Azure リソースのマネージド ID、または Azure AD に登録したアプリケーションのサービス プリンシパルにアクセス許可を付与することを想定します。

配信不能キューのメッセージを操作するためには、(組み込みロールでいうと)「Azure Service Bus データ受信者」ロールを Service Bus 名前空間に割り当てて、アクセス許可すれば良いでしょう。

そして、アクセス元でアクセス トークンを取得し、リクエスト ヘッダーに取得したアクセス トークンを含めて Service Bus の各 REST API にリクエストします。

Request Headers

Authorization: Bearer <アクセス トークン>

配信不能キューのパスは？

ドキュメントには、配信不能キューを操作するためのパスが明確に書かれおらず、以下の構文を使うんだとしか書かれていません...

<queue path>/$deadletterqueue
<topic path>/Subscriptions/<subscription path>/$deadletterqueue

さて、配信不能キューのメッセージを操作するための実際のパスはどのようなものなのでしょうか？

ということで、以下より、筆者が心が折れることなく調べた結果をシェアします。

なお、この件は公式ドキュメントに載っておらず検証結果から見出したものなので、今後の仕様変更などにより変更されるかもしれません。ご了承ください。

※トピック サブスクリプションについては調べていません。
　(同じノリでできると思いますけど)

配信不能キューからメッセージを受信して削除

Receive and Delete Message (Destructive Read)

DELETE https://{serviceNamespace}.servicebus.windows.net/{queuePath}/$DeadLetterQueue/messages/head

パラメーター	設定値
{serviceNamespace}	Service Bus の名前空間。
{queuePath}	Service Bus のキュー。

リクエスト ヘッダー・ボディ、レスポンス コード・ヘッダー・ボディについては、メイン キューでの「メッセージを受信して削除する (破壊読み取り)」と同じですので、以下のドキュメントをご参考ください。

配信不能キューからメッセージを受信 (ピーク/ロック メッセージ)

Peek-Lock Message (Non-Destructive Read)

POST https://{serviceNamespace}.servicebus.windows.net/{queuePath}/$DeadLetterQueue/messages/head

パラメーター	設定値
{serviceNamespace}	Service Bus の名前空間。
{queuePath}	Service Bus のキュー。

リクエスト ヘッダー・ボディ、レスポンス コード・ヘッダー・ボディについては、メイン キューでの「ピーク/ロック メッセージ (非破壊読み取り)」と同じですので、以下のドキュメントをご参考ください。

配信不能キューのメッセージを削除

Delete Message

DELETE https://{serviceNamespace}.servicebus.windows.net/{queuePath}/$DeadLetterQueue/messages/{messageId | sequence-number}/{lockToken}

パラメーター	設定値
{serviceNamespace}	Service Bus の名前空間。
{queuePath}	Service Bus のキュー。
{messageId}	ピーク/ロック メッセージ操作で返されるレスポンス ヘッダー BrokerProperties{MessageId} の値。メッセージ ID。
{sequence-number}	ピーク/ロック メッセージ操作で返されるレスポンス ヘッダー BrokerProperties{SequenceNumber} の値。メッセージのシーケンス番号。
{lockToken}	ピーク/ロック メッセージ操作で返されるレスポンス ヘッダー BrokerProperties{LockToken}の値。メッセージのロックトークン。

リクエスト ヘッダー・ボディ、レスポンス コード・ヘッダー・ボディについては、メイン キューでの「メッセージの削除」と同じですので、以下のドキュメントをご参考ください。

配信不能キューのメッセージのロックを解除

Unlock Message

PUT https://{serviceNamespace}.servicebus.windows.net/{queuePath}/$DeadLetterQueue/messages/{messageId | sequence-number}/{lockToken}

パラメーター	設定値
{serviceNamespace}	Service Bus の名前空間。
{queuePath}	Service Bus のキュー。
{messageId}	ピーク/ロック メッセージ操作で返されるレスポンス ヘッダー BrokerProperties{MessageId} の値。メッセージ ID。
{sequence-number}	ピーク/ロック メッセージ操作で返されるレスポンス ヘッダー BrokerProperties{SequenceNumber} の値。メッセージのシーケンス番号。
{lockToken}	ピーク/ロック メッセージ操作で返されるレスポンス ヘッダー BrokerProperties{LockToken}の値。メッセージのロックトークン。

リクエスト ヘッダー・ボディ、レスポンス コード・ヘッダー・ボディについては、メイン キューでの「メッセージのロックを解除する」と同じですので、以下のドキュメントをご参考ください。

配信不能キューのメッセージのロックを更新

Renew-Lock for a Message

POST https://{serviceNamespace}.servicebus.windows.net/{queuePath}/$DeadLetterQueue/messages/{messageId | sequence-number}/{lockToken}

パラメーター	設定値
{serviceNamespace}	Service Bus の名前空間。
{queuePath}	Service Bus のキュー。
{messageId}	ピーク/ロック メッセージ操作で返されるレスポンス ヘッダー BrokerProperties{MessageId} の値。メッセージ ID。
{sequence-number}	ピーク/ロック メッセージ操作で返されるレスポンス ヘッダー BrokerProperties{SequenceNumber} の値。メッセージのシーケンス番号。
{lockToken}	ピーク/ロック メッセージ操作で返されるレスポンス ヘッダー BrokerProperties{LockToken}の値。メッセージのロックトークン。

リクエスト ヘッダー・ボディ、レスポンス コード・ヘッダー・ボディについては、メイン キューでの「メッセージのロックを更新する」と同じですので、以下のドキュメントをご参考ください。

まとめ

Azure Service Bus 配信不能キューの存在、その目的と操作方法を知ることで、オモテ向きのキューだけでなく、配信不能キューもいろいろと活用できそうですね。

今回は REST API での操作について触れましたが、各種 SDK を用いれば配信不能キューの操作もカンタンにできると思います。

なお、REST API でアクセスする場合は、そのパスにドキュメントに示されている「$DeadLetterQueue」 を含めることをお忘れなく。

この投稿の内容が少しでもお役に立てればと思います。