Peek-Lock Message (Non-Destructive Read)

This operation atomically retrieves and locks a message from a queue or subscription for processing. The message is guaranteed not to be delivered to other receivers (on the same queue or subscription only) during the lock duration specified in the queue/subscription description. When the lock expires, the message becomes available to other receivers. In order to complete processing of the message, the receiver should issue a delete command with the lock ID received from this operation. To abandon processing of the message and unlock it for other receivers, an Unlock Message command should be issued, otherwise the lock duration period can expire.

This operation should be used in applications that require At-Least-Once delivery assurances. If the receiver doesn't delete the message before processing succeeds, this operation ensures that another receiver is able to attempt processing after the lock duration period expires.

Request

Method Request URI HTTP Version
POST https://{serviceNamespace}.servicebus.windows.net/{queuePath}/messages/head

or

https://{serviceNamespace}.servicebus.windows.net/{topicPath}/subscriptions/{subscriptionName}/messages/head		 HTTP/1.1

Query Parameters

Parameter Description
timeout Optional. The time to wait for a message, specified as integer seconds (for example, timeout=1) or an XML duration (for example, timeout=PT1S). The default is 5 seconds. If no message is available within that period, the response is 204 No Content.

Request Headers

The following table describes required and optional request headers. In addition to the listed properties, the header can contain custom properties. See the example.

Request Header Description
Authorization Specify one of the following token values:
  • Microsoft Entra JSON Web Token (JWT) token.
    Example: Authorization: Bearer <Azure AD JWT token>.
    For information on generating a Microsoft Entra token, see Authenticate from an application.
  • A SAS token.
    Example: Authorization: SharedAccessSignature sr=<NAMESPACE NAME>.servicebus.windows.net&sig=<SHARED ACCESS KEY>&se=<TOKEN EXPIRY INSTANT>&skn=<SHARED KEY NAME>.
    For information on generating a SAS token, see Generate a Shared Access Signature token and Generate SAS token.

Request Body

None.

Response

The response includes an HTTP status code, a set of response headers, and the response body.

Response Codes

Code Description
201 Message successfully retrieved and locked.
204 No messages available within the specified time-out period.
400 Bad request.
401 Authorization failure.
410 Specified queue or subscription doesn't exist.
500 Internal error.

For information about status codes, see Status and Error Codes.

Response Headers

The response for this operation includes the following headers. The response might also include more standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response Header Description
Content-Type For a retrieved message, matches the content type stored with the message, when set. For example, a message sent with Content-Type: text/plain is returned as text/plain.
Location The URI of the locked message. Use this URI unchanged to unlock, delete, or renew the lock, with the HTTP method for that operation.
BrokerProperties JSON-encoded BrokerProperties of the received message. The LockToken property represents the lock ID for the returned message. The SequenceNumber property represents the sequence number of the returned message.

Response Body

The response body is the message body of the retrieved message.

Example

The following HTTP request locks and returns message from a queue:

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

Service Bus returns the following response. The message contains the custom properties Priority and Customer:

HTTP/1.1 201 Created  
Transfer-Encoding: chunked  
Content-Type: text/plain
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
  • Last updated on