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

更新消息

2025-10-22

该 Update Message 作更新消息的可见性超时。您还可以使用此作来更新消息的内容。消息的格式必须可以包含在具有 UTF-8 编码的 XML 请求中，并且编码消息的大小最大可达 64 KB。此作是在 Azure 队列存储 API 版本 2011-08-18 中引入的。

请求

您可以按如下方式构造 Update Message 请求。建议使用 HTTPS。将 myaccount 替换为存储帐户的名称，将 myqueue 替换为队列的名称。

方法	请求 URI	HTTP 版本
`PUT`	`https://myaccount.queue.core.windows.net/myqueue/messages/messageid?popreceipt=<string-value>&visibilitytimeout=<int-seconds>`	HTTP/1.1

模拟存储服务

SDK 1.6及以上版本支持此作。

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

方法	请求 URI	HTTP 版本
`PUT`	`http://127.0.0.1:10001/devstoreaccount1/myqueue/messages/messageid?popreceipt=<string-value>&visibilitytimeout=<int-seconds>`	HTTP/1.1

URI 参数

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

参数	Description
`popreceipt`	必填。指定从先前调用“ 获取消息” 或 “更新消息 ”作返回的有效弹出回执值。必须 `popreceipt` 是 URL 编码的。
`visibilitytimeout`	必填。指定相对于服务器时间的新可见性超时值（以秒为单位）。新值必须大于或等于 0，并且不能大于 7 天。消息的可见性超时不能设置为晚于到期时间的值。您可以更新邮件，直到邮件被删除或过期。
`timeout`	可选。该 `timeout` 参数以秒为单位表示。有关更多信息，请参阅设置队列存储作的超时。

请求标头

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

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

请求主体

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

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

响应

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

状态代码

成功的作将返回状态代码 204（无内容）。有关状态代码的信息，请参阅状态代码和错误代码。

响应标头

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

请求标头	Description
`x-ms-request-id`	此标头唯一标识发出的请求，并可用于对请求进行故障排除。更多信息，请参见 API作排查。
`x-ms-version`	指示用于运行请求的队列存储版本。对于针对版本 2009-09-19 及更高版本发出的请求，将返回此标头。
`Date`	UTC 日期/时间值，指示启动响应的时间。服务生成此值。
`x-ms-popreceipt`	队列消息的弹出式接收。
`x-ms-time-next-visible`	UTC 日期/时间值，表示消息在队列上可见的时间。
`x-ms-client-request-id`	您可以使用此标头对请求和相应的响应进行故障排除。如果请求中存在此标头，则此标头的值等于标头的 `x-ms-client-request-id` 值。该值最多为 1,024 个可见的 ASCII 字符。如果请求中不存在标头，则 `x-ms-client-request-id` 响应中将不存在此标头。

响应体

没有。

Authorization

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

示例请求和响应

以下请求将队列消息的可见性延长 30 秒并更新其内容。

PUT https://myaccount.queue.core.windows.net/myqueue/messages/663d89aa-d1d9-42a2-9a6a-fcf822a97d2c?popreceipt=AgAAAAEAAAApAAAAGIw6Q29bzAE%3d&visibilitytimeout=30&timeout=30 HTTP/1.1

使用以下标头发送请求：

x-ms-version: 2011-08-18  
x-ms-date: Mon, 29 Aug 2011 17:17:21 GMT  
Authorization: SharedKey myaccount:batcrWZ35InGCZeTUFWMdIQiOZPCW7UEyeGdDOg7WW4=  
Content-Length: 75

请求使用以下 XML 正文发送：

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

发送请求后，将返回以下响应：

HTTP/1.1 204 No Content  
Content-Length: 0  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: df34a7dd-3cbe-4206-a586-d6de3cf225a7  
x-ms-version: 2011-08-18  
x-ms-popreceipt: AwAAAAIAAAApAAAAINtMQ29bzAEBAAAA  
x-ms-time-next-visible: Mon, 29 Aug 2011 17:17:51 GMT  
Date: Mon, 29 Aug 2011 17:17:21 GMT

注解

Update Message如果队列中不存在指定的消息，或者指定的弹出回执与消息不匹配，则作将失败。

弹出收据由作或Update Message作返回Get Messages。弹出式收据在发生以下事件之一之前保持有效：

消息已过期。
邮件已使用收到的最后一个弹出回执（来自 Get Messages 或 Update Message）删除。
不可见时间已过，消息已通过请求出 Get Messages 队。当不可见时间过去时，消息将再次可见。如果它是由另一个 Get Messages 请求检索的，则返回的弹出式回执可用于删除或更新邮件。
该消息已更新为新的可见性超时。消息更新后，将返回新的弹出回执。

您可以使用该 Update Message 作来持续扩展队列消息的不可见性。如果希望辅助角色租用队列消息，则此功能可能很有用。例如，如果辅助角色调用 Get Messages 并识别出它需要更多时间来处理消息，则它可以不断延长消息的不可见性，直到处理完毕。如果辅助角色在处理过程中失败，最终该消息将再次可见，并且另一个辅助角色可以处理它。

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

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

另请参阅

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

通过