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

Peek-Lock 消息（非破坏性读取）

2025-03-19

此作以原子方式从队列或订阅中检索和锁定消息以供处理。在队列/订阅说明中指定的锁定持续时间内，保证不会将消息传送到其他接收方（仅在同一队列或订阅上）。锁过期后，消息将可供其他接收方使用。为了完成消息处理，接收方应发出包含从此作收到的锁 ID 的删除命令。若要放弃处理消息并为其他接收方解锁消息，应发出解锁消息命令，否则锁定持续时间可能会过期。

此作应在需要 “至少一次” 传递保证的应用程序中使用。如果接收方在处理成功之前未删除消息，则此作可确保另一个接收方能够在锁定持续时间到期后尝试处理。

请求

方法	请求 URI	HTTP 版本
发布	`http{s}://{serviceNamespace}.servicebus.windows.net/{queuePath}/messages/head` 或 `http{s}://{serviceNamespace}.servicebus.windows.net/{topicPath}/subscriptions/{subscriptionName}/messages/head\|HTTP/1.1`

请求标头

下表描述了必需和可选的请求标头。除了列出的属性，标头还可以包含自定义属性。请参阅示例。

请求标头描述

授权

请求标头	描述
授权	指定以下标记值之一： Microsoft Entra JSON Web 令牌（JWT）令牌。示例：`Authorization: Bearer <Azure AD JWT token>`。有关生成Microsoft Entra 令牌的信息，请参阅从应用程序进行身份验证。 SAS 令牌。示例：`Authorization: SharedAccessSignature sr=<NAMESPACE NAME>.servicebus.windows.net&sig=<SHARED ACCESS KEY>&se=<TOKEN EXPIRY INSTANT>&skn=<SHARED KEY NAME>`。有关生成 SAS 令牌的信息，请参阅生成共享访问签名令牌，生成 SAS 令牌。

指定以下标记值之一：

Microsoft Entra JSON Web 令牌（JWT）令牌。
示例：Authorization: Bearer <Azure AD JWT token>。
有关生成Microsoft Entra 令牌的信息，请参阅从应用程序进行身份验证。
SAS 令牌。
示例：Authorization: SharedAccessSignature sr=<NAMESPACE NAME>.servicebus.windows.net&sig=<SHARED ACCESS KEY>&se=<TOKEN EXPIRY INSTANT>&skn=<SHARED KEY NAME>。
有关生成 SAS 令牌的信息，请参阅生成共享访问签名令牌，生成 SAS 令牌。

请求正文

没有。

响应

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

响应代码

法典	描述
201	已成功检索和锁定消息。
204	在指定的超时时间段内没有可用的消息。
400	请求错误。
401	授权失败。
410	指定的队列或订阅不存在。
500	内部错误。

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

响应标头

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

响应标头	描述
`Content-Type`	设置为 `application/atom+xml;type=entry;charset=utf-8`。
`Location`	锁定消息的 URI。可以使用此 URI 解锁或删除消息。
`BrokerProperties`	收到的消息的 JSON 编码 `BrokerProperties`。 `LockToken` 属性表示返回的消息的锁 ID。 `SequenceNumber` 属性表示返回的消息的序列号。

响应正文

响应正文是检索到的消息的消息正文。

例

以下 HTTP 请求锁定并从队列返回消息：

POST https://your-namespace.servicebus.windows.net/HttpClientSampleQueue/messages/head?timeout=60 HTTP/1.1  
Authorization: SharedAccessSignature sr=your-namespace&sig=Fg8yUyR4MOmXfHfj55f5hY4jGb8x2Yc%2b3%2fULKZYxKZk%3d&se=1404256819&skn=RootManageSharedAccessKey  
Host: your-namespace.servicebus.windows.net  
Content-Length: 0

服务总线返回以下响应。该消息包含自定义属性 Priority 和 Customer：

HTTP/1.1 201 Created  
Transfer-Encoding: chunked  
Content-Type: application/atom+xml;type=entry;charset=utf-8  
Location: https://your-namespace.servicebus.windows.net/httpclientsamplequeue/messages/2/7da9cfd5-40d5-4bb1-8d64-ec5a52e1c547  
Server: Microsoft-HTTPAPI/2.0  
BrokerProperties: {"DeliveryCount":1,"EnqueuedSequenceNumber":0,"EnqueuedTimeUtc":"Wed, 02 Jul 2014 01:32:27 GMT","Label":"M1","LockToken":"7da9cfd5-40d5-4bb1-8d64-ec5a52e1c547","LockedUntilUtc":"Wed, 02 Jul 2014 01:33:27 GMT","MessageId":"31907572164743c38741631acd554d6f","SequenceNumber":2,"State":"Active","TimeToLive":10}  
Priority: "High"  
Customer: "12345,ABC"  
Date: Wed, 02 Jul 2014 01:32:27 GMT  
  
12  
This is a message.  
0

通过