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

扫视-锁定消息（非破坏性读取）

项目
07/19/2023

此操作以原子方式检索并锁定队列或订阅中要处理的消息。在队列/订阅描述所指定的锁定持续期内，保证不会将该消息传送给其他接收方（仅限位于同一队列或订阅中的接收方）。锁过期后，就会向其他接收方提供该消息。若要完成消息的处理，接收方应使用从此操作中收到的锁 ID 发出一个删除命令。若要放弃处理消息并为其他接收方解锁消息，应发出 “解锁消息” 命令，否则锁定持续时间可能会过期。

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

请求

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

请求标头

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

请求标头说明

授权

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

指定以下标记值之一：

Azure Active Directory (Azure AD) JSON Web 令牌 (JWT) 令牌。
示例：Authorization: Bearer <Azure AD JWT token>。
有关生成 Azure AD 令牌的信息，请参阅从应用程序进行身份验证。
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

另请参阅

Service Bus HTTP 客户端示例

通过