共用方式為


取得訊息

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 儲存體提出要求
Datex-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 也會不透明于用戶端。 其唯一用途是確保可以使用 刪除訊息 作業刪除訊息。

InsertionTimeExpirationTimeTimeNextVisible 項目會以 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 遞增屬性。 用戶端可以使用這個值判斷訊息被擷取的次數。

如果 visibilitytimeoutnumofmessages 參數超出範圍,服務會傳回狀態碼 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 儲存體的要求
狀態和錯誤碼