Peek-Lock メッセージ (非破壊的読み取り)

2025-03-19

この操作は、処理のためにキューまたはサブスクリプションからメッセージをアトミックに取得してロックします。メッセージは、キュー/サブスクリプションの説明で指定されたロック期間中に、(同じキューまたはサブスクリプション上でのみ) 他の受信側に配信されないことが保証されます。ロックの有効期限が切れると、メッセージは他の受信者が使用できるようになります。メッセージの処理を完了するには、受信側は、この操作から受信したロック ID を使用して delete コマンドを発行する必要があります。メッセージの処理を中止して他の受信者に対してロックを解除するには、Unlock Message コマンドを発行する必要があります。そうしないと、ロック期間が切れる可能性があります。

この操作は、少なくとも 1 回 配信保証 必要なアプリケーションで使用する必要があります。処理が成功する前に受信側がメッセージを削除しない場合、この操作により、ロック期間が経過した後に別の受信者が処理を試みることができます。

依頼

方式	要求 URI	HTTP バージョン
投稿	`http{s}://{serviceNamespace}.servicebus.windows.net/{queuePath}/messages/head` 又は `http{s}://{serviceNamespace}.servicebus.windows.net/{topicPath}/subscriptions/{subscriptionName}/messages/head\|HTTP/1.1`

要求ヘッダー

次の表では、必須の要求ヘッダーと省略可能な要求ヘッダーについて説明します。一覧表示されているプロパティに加えて、ヘッダーにはカスタムプロパティを含めることができます。例を参照してください。

要求ヘッダー形容

認可

要求ヘッダー	形容
認可	次のいずれかのトークン値を指定します。 Microsoft Entra JSON Web トークン (JWT) トークン。例: `Authorization: Bearer <Azure AD JWT token>`. Microsoft Entra トークンの生成の詳細については、「アプリケーションからの認証」を参照してください。 SAS トークン。例: `Authorization: SharedAccessSignature sr=<NAMESPACE NAME>.servicebus.windows.net&sig=<SHARED ACCESS KEY>&se=<TOKEN EXPIRY INSTANT>&skn=<SHARED KEY NAME>`. SAS トークンの生成の詳細については、「Shared Access Signature トークンの生成」および「SAS トークンの生成」を参照してください。

次のいずれかのトークン値を指定します。

Microsoft Entra JSON Web トークン (JWT) トークン。
例: Authorization: Bearer <Azure AD JWT token>.
Microsoft Entra トークンの生成の詳細については、「アプリケーションからの認証」を参照してください。
SAS トークン。
例: Authorization: SharedAccessSignature sr=<NAMESPACE NAME>.servicebus.windows.net&sig=<SHARED ACCESS KEY>&se=<TOKEN EXPIRY INSTANT>&skn=<SHARED KEY NAME>.
SAS トークンの生成の詳細については、「Shared Access Signature トークンの生成」および「SAS トークンの生成」を参照してください。

要求本文

何一つ。

応答

応答には、HTTP 状態コード、一連の応答ヘッダー、および応答本文が含まれます。

応答コード

コード	形容
201	メッセージが正常に取得され、ロックされました。
204	指定されたタイムアウト期間内に使用できるメッセージはありません。
400	要求が正しくありません。
401	承認エラー。
410	指定されたキューまたはサブスクリプションが存在しません。
500	内部エラー。

状態コードの詳細については、「状態コードとエラーコードの」を参照してください。

応答ヘッダー

この操作の応答には、次のヘッダーが含まれます。応答には、より標準的な HTTP ヘッダーが含まれる場合もあります。すべての標準ヘッダーは、HTTP/1.1 プロトコル仕様に準拠しています。

応答ヘッダー	形容
`Content-Type`	`application/atom+xml;type=entry;charset=utf-8`に設定します。
`Location`	ロックされたメッセージの URI。この URI を使用して、メッセージのロックを解除または削除できます。
`BrokerProperties`	受信したメッセージの JSON エンコードされた `BrokerProperties`。 `LockToken` プロパティは、返されたメッセージのロック ID を表します。 `SequenceNumber` プロパティは、返されたメッセージのシーケンス番号を表します。

応答本文

応答本文は、取得したメッセージのメッセージ本文です。

例

次の HTTP 要求は、キューからメッセージをロックして返します。

POST https://your-namespace.servicebus.windows.net/HttpClientSampleQueue/messages/head?timeout=60 HTTP/1.1  
Authorization: SharedAccessSignature sr=your-namespace&sig=Fg8yUyR4MOmXfHfj55f5hY4jGb8x2Yc%2b3%2fULKZYxKZk%3d&se=1404256819&skn=RootManageSharedAccessKey  
Host: your-namespace.servicebus.windows.net  
Content-Length: 0

Service Bus は次の応答を返します。メッセージには、カスタムプロパティの Priority と Customerが含まれています。

HTTP/1.1 201 Created  
Transfer-Encoding: chunked  
Content-Type: application/atom+xml;type=entry;charset=utf-8  
Location: https://your-namespace.servicebus.windows.net/httpclientsamplequeue/messages/2/7da9cfd5-40d5-4bb1-8d64-ec5a52e1c547  
Server: Microsoft-HTTPAPI/2.0  
BrokerProperties: {"DeliveryCount":1,"EnqueuedSequenceNumber":0,"EnqueuedTimeUtc":"Wed, 02 Jul 2014 01:32:27 GMT","Label":"M1","LockToken":"7da9cfd5-40d5-4bb1-8d64-ec5a52e1c547","LockedUntilUtc":"Wed, 02 Jul 2014 01:33:27 GMT","MessageId":"31907572164743c38741631acd554d6f","SequenceNumber":2,"State":"Active","TimeToLive":10}  
Priority: "High"  
Customer: "12345,ABC"  
Date: Wed, 02 Jul 2014 01:32:27 GMT  
  
12  
This is a message.  
0