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

放置消息

项目
06/27/2023

Put Message操作将新消息添加到消息队列后面。还可以指定可见性超时，使消息在可见性超时过期之前不可见。消息必须采用某种格式，以便可以包含在具有 UTF-8 编码的 XML 请求中。对于版本 2011-08-18 及更高版本， (KiB) ，编码的消息最多可以为 64 kibites，对于早期版本，则为 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 上指定以下参数：

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

请求标头

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

请求标头	说明
`Authorization`	必需。指定授权方案、帐户名称和签名。有关详细信息，请参阅授权对 Azure 存储的请求。
`Date` `or x-ms-date`	必需。指定请求的协调世界时 (UTC)。有关详细信息，请参阅授权对 Azure 存储的请求。
`x-ms-version`	可选。指定用于此请求的操作的版本。有关详细信息，请参阅 Azure 存储服务的版本控制。
`x-ms-client-request-id`	可选。提供客户端生成的不透明值，其中包含 1-kiB (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 协议规范。

请求标头	说明
`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`如果请求中不存在标头，则它不会出现在响应中。

响应正文

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

MessageID element is a GUID value that identifies the message in the queue. 此值由队列存储分配给消息，并且不透明地分配给客户端。此值可以与 PopReceipt 元素的值一起使用，以从队列中删除或更新消息。 PopReceipt 的值对客户端来说也是不透明的，在使用“删除消息”或“更新消息”API 时，该值是必需的。

InsertionTime、ExpirationTime 和 TimeNextVisible 元素表示为 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>

授权

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

注解

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

可选的消息生存时间指定消息在队列中的保留时间。生存期到期时，将从队列中删除消息。

消息必须采用某种格式，以便可以包含在具有 UTF-8 编码的 XML 请求中。若要在消息中包含标记，消息内容必须经过 XML 转义或进行 Base64 编码。在将消息添加到队列之前，将删除消息中未转义或编码的任何 XML 标记。

如果消息太大，服务将返回状态代码 400（错误的请求）。

另请参阅

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