查看訊息

發行項
08/05/2023

作業 Peek Messages 會從佇列前端擷取一或多個訊息，但不會改變訊息的可見度。

要求

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

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

模擬儲存體服務要求

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

方法	要求 URI	HTTP 版本
`GET`	`http://127.0.0.1:10001/devstoreaccount1/myqueue/messages?peekonly=true`	HTTP/1.1

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

URI 參數

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

參數	描述
`numofmessages`	選擇性。這是非零整數值，可指定從佇列查看的訊息數目 (32 則為上限)。根據預設，使用此作業會從佇列查看單一訊息。
`timeout`	選擇性。 `timeout` 參數以秒為單位。如需詳細資訊，請參閱設定佇列服務作業的逾時。

要求標頭

下表說明必要的和選擇性要求標頭：

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

要求本文

無。

回應

回應包括 HTTP 狀態碼、一組 XML 回應標頭，以及回應主體。

狀態碼

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

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

回應標頭

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

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

回應本文

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

MessageID 項目是用來識別在佇列中之訊息的 GUID 值。這個值是由佇列服務指派，對用戶端是不透明的。

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

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

注意

DequeueCount只有在佇列服務版本 2009-09-19 建立佇列時，才會在回應本文中傳回元素。

<QueueMessagesList>  
    <QueueMessage>  
      <MessageId>string-message-id</MessageId>  
      <InsertionTime>insertion-time</InsertionTime>  
      <ExpirationTime>expiration-time</ExpirationTime>  
      <DequeueCount>integer</DequeueCount>  
      <MessageText>message-body</MessageText>  
    </QueueMessage>  
</QueueMessagesList>

注意

此回應與取得訊息作業的回應不同，因為它不包含 PopReceipt 或 TimeNextVisible 元素。

範例回應

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Fri, 16 Sep 2011 22:51:18 GMT  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
  
Response Body:  
<?xml version="1.0" encoding="utf-8"?>  
<QueueMessagesList>  
  <QueueMessage>  
    <MessageId>06eba214-8107-4412-a7f6-710a9baff647</MessageId>  
    <InsertionTime>Fri, 09 Oct 2009 18:59:54 GMT</InsertionTime>  
    <ExpirationTime>Fri, 16 Sep 2009 18:59:54 GMT</ExpirationTime>  
    <DequeueCount>1</DequeueCount>  
    <MessageText>PHRlc3Q+dGhpcyBpcyBhIHRlc3QgbWVzc2FnZTwvdGVzdD4=</MessageText>  
  </QueueMessage>  
</QueueMessagesList>

授權

此作業可由帳戶擁有者以及具有執行此作業許可權的共用存取簽章的任何人執行。

備註

在 peekonly 設為 true 的情況下，從佇列擷取訊息時，不會變更訊息的可見性。訊息仍可供佇列的其他取用者使用，直到用戶端使用取得訊息作業擷取訊息為止。要求訊息的用戶端不會收到包含回應的快顯收據，因此無法刪除訊息。

只有可見的訊息可以使用作業來 Peek Messages 擷取。請注意，可以擷取的訊息數目上限為 32。

第一次呼叫 Get Messages 以擷取訊息時，其 DequeueCount 屬性設為 1。如果未刪除，且後續會再次擷取，則會 DequeueCount 遞增屬性。用戶端可以使用此值來判斷已擷取訊息的次數。

注意

的 Peek Messages 呼叫不會遞增的值 DequeueCount ，但會傳回這個值供用戶端讀取。

如果 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 儲存體的要求
 狀態和錯誤碼
 佇列服務錯誤碼