メッセージの取得

  • [アーティクル]

Get Messages 操作は、キューの先頭から 1 つ以上のメッセージを取得します。

要求

Get Messages 要求の構成は次のとおりです。 HTTPS を使用することをお勧めします。 myaccount をストレージ アカウントの名前に置き換え、 をキューの名前に置き換えますmyqueue。

Method 要求 URI HTTP バージョン
GET https://myaccount.queue.core.windows.net/myqueue/messages HTTP/1.1

エミュレートされたストレージ サービス要求

エミュレートされたストレージ サービスに対して要求を行う場合は、エミュレーターのホスト名と Azure Queue Storage ポートを として 127.0.0.1:10001指定し、その後にエミュレートされたストレージ アカウント名を指定します。

Method 要求 URI HTTP バージョン
GET http://127.0.0.1:10001/devstoreaccount1/myqueue/messages HTTP/1.1

詳細については、ローカルでの Azure Storage の開発に Azurite エミュレーターを使用する方法に関するページを参照してください。

URI パラメーター

次の追加パラメーターを要求の URI で指定できます。

パラメーター 説明
numofmessages 省略可能。 キューから取得するメッセージの数を示すゼロ以外の整数値を指定します (上限は 32 件)。 表示されるメッセージが少ない場合は、表示されるメッセージが返されます。 既定では、この操作によってキューから 1 つのメッセージが取得されます。
visibilitytimeout 省略可能。 サーバー時刻に対する新しい可視性タイムアウト値を秒単位で指定します。 既定値は 30 秒です。

指定した値は 1 秒以上である必要があり、2011-08-18 より前の REST プロトコル バージョンでは、7 日以上または 2 時間を超えることはできません。 メッセージの可視性タイムアウトは、有効期限より後の値に設定できます。
timeout 省略可能。 timeout パラメーターは、秒単位で表されます。 詳細については、「 Azure Queue Storage 操作のタイムアウトを設定する」を参照してください。

要求ヘッダー

必須要求ヘッダーと省略可能な要求ヘッダーを次の表に示します。

要求ヘッダー 説明
Authorization 必須。 承認スキーム、アカウント名、署名を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
Date または x-ms-date 必須。 要求に対して協定世界時 (UTC) を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。
x-ms-version 省略可能。 この要求に使用する操作のバージョンを指定します。 詳細については、「Azure Storage サービスのバージョン管理」を参照してください。
x-ms-client-request-id 省略可能。 ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。 詳細については、「 Azure Queue Storage の監視」を参照してください。

要求本文

なし。

[応答]

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

状態コード

操作に成功すると、状態コード 200 (OK) が返されます。

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

応答ヘッダー

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

応答ヘッダー 説明
x-ms-request-id 作成された要求を一意に識別し、要求のトラブルシューティングに使用できます。 詳細については、「 API 操作のトラブルシューティング」を参照してください。
x-ms-version 要求の実行に使用された Azure Queue Storage のバージョンを示します。 このヘッダーは、バージョン 2009-09-19 以降に対して行われた要求に対して返されます。
Date サービスによって生成される UTC 日付/時刻値。応答が開始された時刻を示します。
x-ms-client-request-id 要求と対応する応答のトラブルシューティングに使用できます。 このヘッダーの値は、要求に存在し、その値に 1,024 文字以下の ASCII 文字が含まれている場合、ヘッダーの値 x-ms-client-request-id と等しくなります。 ヘッダーが x-ms-client-request-id 要求に存在しない場合、応答には存在しません。

応答本文

Get Messages 操作の応答 XML は次の形式で返されます。

MessageID 要素は、キュー内のメッセージを識別する GUID 値です。 この値は、Azure Queue Storage によってメッセージに割り当てられ、クライアントには不透明です。 値を 要素の PopReceipt 値と共に使用すると、操作を使用してメッセージを取得した後にキューからメッセージを Get Messages 削除できます。 の PopReceipt 値もクライアントに対して不透明です。 その唯一の目的は、メッセージの削除操作でメッセージを 削除 できるようにすることです。

InsertionTime、ExpirationTime、TimeNextVisible の各要素は、RFC 1123 に準拠した形式の UTC 値で表記されます。

DequeueCount 要素には、メッセージが初めてデキューされた時点で値 1 が設定されます。 この値は、その後メッセージがデキューされるたびに 1 増分します。

注意

要素は DequeueCount 、Azure Queue Storage バージョン 2009-09-19 を使用してキューが作成された場合にのみ、応答本文で返されます。

<QueueMessagesList>  
    <QueueMessage>  
      <MessageId>string-message-id</MessageId>  
      <InsertionTime>insertion-time</InsertionTime>  
      <ExpirationTime>expiration-time</ExpirationTime>  
      <PopReceipt>opaque-string-receipt-data</PopReceipt>  
      <TimeNextVisible>time-next-visible</TimeNextVisible>  
      <DequeueCount>integer</DequeueCount>  
      <MessageText>message-body</MessageText>  
    </QueueMessage>  
</QueueMessagesList>

応答のサンプル

Response Status:  
HTTP/1.1 200 OK  
Response Headers:  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Fri, 16 Sep 2011 21:04:30 GMT  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
  
Response Body:  
<?xml version="1.0" encoding="utf-8"?>  
<QueueMessagesList>  
  <QueueMessage>  
    <MessageId>5974b586-0df3-4e2d-ad0c-18e3892bfca2</MessageId>  
    <InsertionTime>Fri, 09 Oct 2009 21:04:30 GMT</InsertionTime>  
    <ExpirationTime>Fri, 16 Oct 2009 21:04:30 GMT</ExpirationTime>  
    <PopReceipt>YzQ4Yzg1MDItYTc0Ny00OWNjLTkxYTUtZGM0MDFiZDAwYzEw</PopReceipt>  
    <TimeNextVisible>Fri, 09 Oct 2009 23:29:20 GMT</TimeNextVisible>  
    <DequeueCount>1</DequeueCount>  
    <MessageText>PHRlc3Q+dGhpcyBpcyBhIHRlc3QgbWVzc2FnZTwvdGVzdD4=</MessageText>  
  </QueueMessage>  
</QueueMessagesList>

承認

この操作を実行できるのは、アカウント所有者と、この操作を実行するアクセス許可を持つ共有アクセス署名を使用する任意のユーザーです。

注釈

メッセージの内容は、 Put Message 操作に使用された形式で取得されます。

キューからメッセージを取得するときの応答には、メッセージと、メッセージを削除するときに必要な pop receipt 値が含まれます。 メッセージはキューから自動的に削除されませんが、取得後、 パラメーターで visibilitytimeout 指定された時間間隔の間、他のクライアントには表示されません。

複数のメッセージを取得した場合は、各メッセージに POPReceipt が関連付けられます。 同時に取得できるメッセージの最大数は 32 です。

メッセージを取得するクライアントは、メッセージが処理された後、および応答の 要素によって TimeNextVisible 指定された時刻 (パラメーターの値に基づいて計算されます) の前に、メッセージを visibilitytimeout 削除する必要があります。 の visibilitytimeout 値は、 の値 TimeNextVisibleを決定するためにメッセージが取得された時刻に追加されます。

クロック スキューのため、特定 visibilitytimeout の を使用して取得されたメッセージは、指定されたタイムアウトが経過する前に再び表示される可能性があります。 クライアントは、メッセージのデキューごとに一意のポップ レシートに基づいて、メッセージが別のクライアントによって既にデキューされていることを推測できることに注意してください。 クライアントのポップ レシートでメッセージの削除または更新が機能しなくなり、クライアントが 404 (見つかりません) エラーを受け取った場合、メッセージは別のクライアントによってデキューされます。

通常、コンシューマーが を介して Get Messagesメッセージを取得すると、そのメッセージは visibilitytimeout 間隔の有効期限が切れるまで削除用に予約されます。 ただし、この動作は保証されません。 visibilitytimeout 間隔の有効期限が切れると、メッセージはもう一度他のコンシューマーに表示されるようになります。 メッセージが後で別のコンシューマーによって取得および削除されない場合、元のコンシューマーは元のポップ レシートを使用してメッセージを削除できます。

メッセージが初めて取得されると、その DequeueCount プロパティが 1 に設定されます。 削除されておらず、その後再度取得される場合は、 DequeueCount プロパティがインクリメントされます。 クライアントはこの値を使用して、メッセージが取得された回数を確認できます。

visibilitytimeout または numofmessages パラメーターが範囲外の場合、次の例に示すように、サービスは状態コード 400 (Bad Request) と追加のエラー情報を返します。

  
HTTP/1.1 400 One of the query parameters specified in the request URI is outside the permissible range.  
Connection: Keep-Alive  
Content-Length: 455  
Via: 1.1 TK5-PRXY-22  
Date: Wed, 02 May 2012 19:37:23 GMT  
Content-Type: application/xml  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: 6a03526c-ca2c-4358-a63a-b5d096988533  
x-ms-version: 2011-08-18  
  
<?xml version="1.0" encoding="utf-8"?>  
   <Error>  
      <Code>OutOfRangeQueryParameterValue</Code>  
      <Message>One of the query parameters specified in the request URI is outside the permissible range.  
               RequestId:6a03526c-ca2c-4358-a63a-b5d096988533  
               Time:2012-05-02T19:37:24.2438463Z  
      </Message>  
     <QueryParameterName>numofmessages</QueryParameterName>  
     <QueryParameterValue>0</QueryParameterValue>  
     <MinimumAllowed>1</MinimumAllowed>  
     <MaximumAllowed>32</MaximumAllowed>  
   </Error>

関連項目

Azure Queue Storage のエラー コード
Azure Storage への要求を承認する
状態コードとエラー コード