取得訊息

  • 發行項

Get Messages作業會從佇列前面擷取一或多則訊息。

要求

Get Messages 要求的建構如下。 建議您使用 HTTPS。 以儲存體帳戶的名稱取代 myaccount ，並以佇列的名稱取代 myqueue ：

方法 要求 URI HTTP 版本
GET https://myaccount.queue.core.windows.net/myqueue/messages HTTP/1.1

模擬儲存體服務要求

當您對模擬儲存體服務提出要求時，請將模擬器主機名稱和 Azure 佇列儲存體埠指定為 127.0.0.1:10001 ，後面接著模擬的儲存體帳戶名稱：

方法 要求 URI HTTP 版本
GET http://127.0.0.1:10001/devstoreaccount1/myqueue/messages HTTP/1.1

如需詳細資訊，請參閱使用 Azure 模擬器進行本機 Azure 儲存體開發。

URI 參數

您可以在要求的 URI 中指定下列其他參數。

參數 描述
numofmessages 選擇性。 這是非零整數值，可指定從佇列擷取的訊息數目 (32 則為上限)。 如果可見的訊息較少，則會傳回可見的訊息。 根據預設，使用此作業會從佇列擷取單一訊息。
visibilitytimeout 選擇性。 指定相對於伺服器時間的新可見度逾時值，以秒為單位。 預設值為 30 秒。

指定的值必須大於或等於 1 秒，且無法在 2011-08-18 之前的 REST 通訊協定版本上大於 7 天或大於 2 小時。 訊息的可見度逾時可以設定為晚于到期時間的值。
timeout 選擇性。 timeout 參數以秒為單位。 如需詳細資訊，請參閱 設定 Azure 佇列儲存體作業的逾時。

要求標頭

下表描述必要的和選用的要求標頭。

要求標頭 描述
Authorization 必要。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
Date 或 x-ms-date 必要。 指定要求的「國際標準時間」(UTC)。 如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
x-ms-version 選擇性。 指定用於這個要求的作業版本。 如需詳細資訊，請參閱 Azure 儲存體服務的版本。
x-ms-client-request-id 選擇性。 提供用戶端產生的不透明值，其中包含 1-kibibyte (KiB) 設定記錄時記錄在記錄中的字元限制。 強烈建議您使用此標頭，將用戶端活動與伺服器收到的要求相互關聯。 如需詳細資訊，請參閱 監視 Azure 佇列儲存體。

要求本文

無。

回應

回應包括 HTTP 狀態碼和一組回應標頭。

狀態碼

成功的作業會傳回狀態碼 200 (OK)。

如需狀態碼的詳細資訊，請參閱 狀態和錯誤碼。

回應標頭

這項作業的回應包括下列標頭。 回應也可能包括其他標準 HTTP 標頭。 所有標準標頭都符合 HTTP/1.1 通訊協定規格。

回應標頭 描述
x-ms-request-id 可唯一識別已提出的要求，並可用來對要求進行疑難排解。 如需詳細資訊，請參閱 針對 API 作業進行疑難排解。
x-ms-version 指出用來執行要求的 Azure 佇列儲存體版本。 針對針對 2009-09-19 版和更新版本提出的要求，會傳回此標頭。
Date 服務所產生的 UTC 日期/時間值，表示起始回應的時間。
x-ms-client-request-id 可用來針對要求和對應的回應進行疑難排解。 如果此標頭存在於要求中，則此標頭的值等於標頭的值 x-ms-client-request-id ，且值不包含超過 1，024 個可見的 ASCII 字元。 x-ms-client-request-id如果要求中沒有標頭，則不會出現在回應中。

回應本文

Get Messages 作業的回應 XML 會以下列格式傳回。

MessageID 項目是用來識別在佇列中之訊息的 GUID 值。 此值會由 Azure 佇列儲存體指派給訊息，而且不透明地指派給用戶端。 您可以使用 值與 元素的值 PopReceipt ，在使用 Get Messages 作業擷取訊息之後，從佇列中刪除訊息。 的值 PopReceipt 也會不透明于用戶端。 其唯一用途是確保可以使用 刪除訊息 作業刪除訊息。

InsertionTime、ExpirationTime 和 TimeNextVisible 項目會以 UTC 值表示，格式如 RFC 1123 所述。

第一次將訊息從佇列清除時，DequeueCount 項目的值為 1。 後續每次將訊息從佇列清除時，這個值會增加。

注意

只有在使用 Azure 佇列儲存體 2009-09-19 版建立佇列時，才會 DequeueCount 在回應本文中傳回元素。

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

授權

帳戶擁有者及使用共用存取簽章並有權執行這項作業的任何人，都可以執行這項作業。

備註

訊息內容會以 用於放置訊息 作業的格式擷取。

從佇列擷取訊息時，回應中會包含訊息，以及刪除訊息所需的 pop receipt 值。 訊息不會自動從佇列中刪除，但在擷取訊息之後，其他用戶端不會看到該訊息的時間間隔。 visibilitytimeout

如果擷取多個訊息，每個訊息都會有一個相關聯的 pop receipt。 同時擷取的訊息數目上限為 32。

擷取訊息的用戶端預期會在訊息經過處理之後，以及在回應元素所 TimeNextVisible 指定的時間之前刪除訊息，這會根據 參數的值 visibilitytimeout 來計算。 visibilitytimeout的值會新增至擷取訊息的時間，以判斷 的值 TimeNextVisible 。

由於時鐘扭曲，使用特定 visibilitytimeout 擷取的訊息在經過指定的逾時之前可能會重新出現。 請注意，用戶端可以根據快顯收據推斷訊息已經由不同的用戶端取消佇列，這對於每個取消佇列的郵件而言都是唯一的。 如果用戶端的快顯收據無法再刪除或更新訊息，且用戶端收到 404 (找不到) 錯誤，訊息已由另一個用戶端取消佇列。

一般而言，當取用者透過 Get Messages 擷取訊息時，該訊息會保留供刪除，直到 可見度逾時 間隔到期為止。 但並不保證此行為。 可見度逾時間隔到期之後，其他取用者會再次看到訊息。 如果未後續由另一個取用者擷取和刪除訊息，則原始取用者可以使用原始快顯收據來刪除訊息。

當訊息第一次被擷取時，其 DequeueCount 屬性設為 1。 如果未刪除，且後續會再次擷取，則會 DequeueCount 遞增屬性。 用戶端可以使用這個值判斷訊息被擷取的次數。

如果 visibilitytimeout 或 numofmessages 參數超出範圍，服務會傳回狀態碼 400 (錯誤要求) ，以及其他錯誤資訊，如下列範例所示。

  
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 佇列儲存體錯誤碼
授權對 Azure 儲存體的要求
狀態和錯誤碼