查看並鎖定訊息 (非破壞性讀取)

發行項
08/05/2023

此作業會自動擷取和鎖定佇列或訂閱中的訊息，以進行處理。在佇列/訂閱描述中指定的鎖定期間，訊息保證不會傳遞給其他接收者 (僅在相同的佇列或訂閱上)。鎖定過期之後，其他接收者就可以使用訊息。為了完成訊息的處理，接收者應該發出刪除命令與從此作業接收的鎖定識別碼。若要放棄處理訊息並解除鎖定其他接收者，應該發出解除鎖定訊息命令，否則鎖定期間可能會過期。

此作業應該用於需要「至少一次」傳送保證的應用程式。如果接收者在處理成功之前未刪除訊息，此作業可確保另一個接收者能夠在鎖定期間到期後嘗試處理。

要求

方法	要求 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 通訊協定規格。

回應標頭	Description
`Content-Type`	設定為 `application/atom+xml;type=entry;charset=utf-8`。
`Location`	已鎖定訊息的 URI。您可以使用此 URI 來解除鎖定或刪除訊息。
`BrokerProperties`	已 `BrokerProperties` 接收訊息的 JSON 編碼。屬性 `LockToken` 代表所傳回訊息的鎖定識別碼。屬性 `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

另請參閱

服務匯流排 HTTP 用戶端範例

共用方式為