你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

查看消息

项目
06/27/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

有关详细信息，请参阅使用 Azurite 模拟器进行本地 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-kibite (KiB) 配置日志记录时记录在日志中的字符限制。强烈建议使用此标头将客户端活动与服务器接收的请求相关联。有关详细信息，请参阅监视 Azure 队列存储。

请求正文

无。

响应

响应包括 HTTP 状态代码、一组响应标头和 XML 响应正文。

状态代码

此操作成功后返回状态代码 200（正常）。

有关状态代码的详细信息，请参阅状态和错误代码。

响应头

此操作的响应包括以下标头。响应还包含其他标准 HTTP 标头。所有标准标头都符合 HTTP/1.1 协议规范。

响应标头	说明
`x-ms-request-id`	唯一标识发出的请求，并可用于对请求进行故障排除。有关详细信息，请参阅 API 操作疑难解答。
`x-ms-version`	用于执行请求的队列服务版本。针对版本 2009-09-19 及更高版本发出的请求返回。
`Date`	由服务生成的 UTC 日期/时间值，指示启动响应的时间。
`x-ms-client-request-id`	可用于对请求及其相应响应进行故障排除。如果请求中存在标头， `x-ms-client-request-id` 并且该值包含的可见 ASCII 字符不超过 1，024 个，则此标头的值等于标头的值。 `x-ms-client-request-id`如果请求中不存在标头，则响应中不会显示该标头。

响应正文

将用以下格式返回Peek Messages操作的响应 XML。

MessageID element is a GUID value that identifies the message in the queue. 此值由队列服务分配给消息，对客户端不透明。

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 存储的请求
 状态和错误代码
 队列服务错误代码