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

获取消息

项目
06/27/2023

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

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

请求正文

无。

响应

响应包括 HTTP 状态代码和一组响应标头。

状态代码

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

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

响应头

此操作的响应包括以下标头。该响应还可能包括其他标准 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` 并且该值包含的可见 ASCII 字符不超过 1，024 个，则此标头的值等于标头的值。 `x-ms-client-request-id`如果请求中不存在标头，则响应中不会显示该标头。

响应正文

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

MessageID element is a GUID value that identifies the message in the queue. 此值由 Azure 队列存储分配给消息，对客户端是不透明的。在使用操作检索消息后，可以将值与元素的值 PopReceipt 一起使用，以从队列中删除 Get Messages 消息。的值 PopReceipt 对客户端而言也是不透明的。它的唯一用途是确保可以使用“删除消息”操作删除消息。

InsertionTime、ExpirationTime 和 TimeNextVisible 元素表示为 UTC 值，并按 RFC 1123 中所述进行格式设置。

第一次将消息取消排队时，DequeueCount 元素的值为 1。随后每次将该消息取消排队时，此值都会递增。

注意

DequeueCount仅当队列是使用 Azure 队列存储版本 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>

授权

帐户所有者以及使用有权执行此操作的共享访问签名的任何人可以执行此操作。

注解

以用于放置消息操作的格式检索消息内容。

在从队列检索消息时，响应包括消息和 pop 接收方值，这是删除该消息所必需的。消息不会自动从队列中删除，但在检索到消息后，其他客户端在参数指定的 visibilitytimeout 时间间隔内不可见。

如果检索多条消息，每条消息都具有关联的 Pop 回执。可以同时检索的最大消息数为 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 存储的请求
 状态和错误代码