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

放置消息

2025-10-22

该 Put Message 作会将新消息添加到消息队列的后面。还可以指定可见性超时，以使消息在可见性超时到期之前不可见。消息必须采用可以包含在采用 UTF-8 编码的 XML 请求中的格式。对于版本 2011-08-18 及更高版本，编码消息的大小最大为 64 KiB，对于早期版本，编码消息的大小最大为 8 KiB。

请求

可以按如下所示构造 Put Message 请求。建议使用 HTTPS。将 myaccount 替换为存储帐户的名称和 myqueue 队列的名称：

方法	请求 URI	HTTP 版本
`POST`	`https://myaccount.queue.core.windows.net/myqueue/messages?visibilitytimeout=<int-seconds>&messagettl=<int-seconds>`	HTTP/1.1 协议

模拟存储服务请求

当您对模拟存储服务发出请求时，请将模拟器主机名和队列存储端口指定为 127.0.0.1:10001，后跟模拟的存储帐户名称：

方法	请求 URI	HTTP 版本
`POST`	`http://127.0.0.1:10001/devstoreaccount1/myqueue/messages?visibilitytimeout=<int-seconds>&messagettl=<int-seconds>`	HTTP/1.1 协议

有关详细信息，请参阅使用 Azurite 模拟器进行本地 Azure 存储开发。

URI 参数

您可以在请求 URI 上指定以下参数：

参数	DESCRIPTION
`visibilitytimeout=<int=seconds>`	可选。指定相对于服务器时间的新可见性超时值（以秒为单位）。如果指定了，则必须使用 `x-ms-version` 2011-08-18 或更高版本发出请求。如果未指定，则默认值为 0。新值必须大于或等于 0，并且不能大于 7 天。消息的可见性超时不能设置为晚于到期日期的值。设置为 `visibilitytimeout` 小于 time-to-live 值的值。
`messagettl=<int-seconds>`	可选。指定消息的生存时间间隔（以秒为单位）。在 2017-07-29 之前的版本中，允许的最长生存时间为 7 天。对于版本 2017-07-29 及更高版本，最长生存时间可以是任何正数，并且 `-1`，这表示消息不会过期。如果省略此参数，则默认生存时间为 7 天。
`timeout`	可选。 `timeout` 参数以秒为单位表示。有关详细信息，请参阅设置队列服务操作的超时。

请求标头

下表描述了必需和可选的请求标头：

请求标头	DESCRIPTION
`Authorization`	必填。指定授权方案、帐户名称和签名。有关详细信息，请参阅授权对 Azure 存储的请求。
`Date` `or x-ms-date`	必填。指定请求的协调世界时（UTC）。有关详细信息，请参阅授权对 Azure 存储的请求。
`x-ms-version`	可选。指定要用于此请求的操作的版本。有关详细信息，请参阅 azure 存储服务版本控制。
`x-ms-client-request-id`	可选。提供客户端生成的不透明值，该值具有配置日志记录时日志中记录的 1-kibibyte （KiB）字符限制。强烈建议使用此标头将客户端活动与服务器接收的请求相关联。

请求主体

请求正文包含以下 XML 格式的消息数据。请注意，消息内容必须采用可使用 UTF-8 编码的格式。

<QueueMessage>  
    <MessageText>message-content</MessageText>  
</QueueMessage>

示例请求

Request:  
POST https://myaccount.queue.core.windows.net/messages?visibilitytimeout=30&timeout=30 HTTP/1.1  
  
Headers:  
x-ms-version: 2011-08-18  
x-ms-date: Tue, 30 Aug 2011 01:03:21 GMT  
Authorization: SharedKey myaccount:sr8rIheJmCd6npMSx7DfAY3L//V3uWvSXOzUBCV9wnk=  
Content-Length: 100  
  
Body:  
<QueueMessage>  
<MessageText>PHNhbXBsZT5zYW1wbGUgbWVzc2FnZTwvc2FtcGxlPg==</MessageText>  
</QueueMessage>

响应

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

状态代码

成功的作返回状态代码 201（已创建）。

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

响应标头

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

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

响应体

从版本 2016-05-31 开始，该作的 Put Message 响应在响应正文中包含消息信息。此处介绍了返回正文的 XML 格式。

该 MessageID 元素是标识队列中消息的 GUID 值。此值由 Queue Storage 分配给消息，并且对客户端不透明。此值可以与 PopReceipt 元素的值一起使用，以从队列中删除或更新消息。 PopReceipt 的值对客户端也是不透明的，当您使用 Delete Message 或 Update Message API 时，它是必需的。

、 InsertionTime和 ExpirationTimeTimeNextVisible 元素表示为 UTC 值，并按照 RFC 1123 中的说明进行格式设置。

<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>
    </QueueMessage>
</QueueMessagesList>

示例响应

Response Status:
HTTP/1.1 200 OK
Response headers:
Transfer-Encoding: chunked
Content-Type: application/xml
x-ms-version: 2016-05-31
Date: Fri, 09 Oct 2016 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 2016 21:04:30 GMT</InsertionTime>
    <ExpirationTime>Fri, 16 Oct 2016 21:04:30 GMT</ExpirationTime>
    <PopReceipt>YzQ4Yzg1MDItYTc0Ny00OWNjLTkxYTUtZGM0MDFiZDAwYzEw</PopReceipt>
    <TimeNextVisible>Fri, 09 Oct 2016 23:29:20 GMT</TimeNextVisible>
   </QueueMessage>
</QueueMessagesList>

授权

此作可由账户所有者和具有共享访问签名且有权执行此作的任何人执行。

注解

可选的 visibility time-out 指定消息不可见的时间。超时过期后，该消息将变为可见。如果未指定可见性超时，则使用默认值 0。

可选的 message time-to-live 指定消息在队列中保留的时间。当生存时间到期时，该消息将从队列中删除。

消息必须采用可以包含在采用 UTF-8 编码的 XML 请求中的格式。若要在邮件中包含标记，邮件的内容必须采用 Base64 编码。消息中任何未编码的 XML 标记都会导致消息无效。如果消息中包含无效字符（例如 0x1F），即使它是 XML 转义的，消息的后续读取也不会成功。

如果消息太大，服务将返回状态代码 400 （Bad Request）。

另请参阅

授权对 Azure 存储的请求
状态和错误代码
 队列服务错误代码

通过