Peek-Lock-Nachricht (nicht destruktiver Lesevorgang)

Artikel
08/05/2023

Diese Operation liest und sperrt eine Nachricht aus einer Warteschlange oder einem Abonnement zur Verarbeitung als atomarer Vorgang. Für die in der Beschreibung von Warteschlange/Abonnement angegebene Dauer der Sperre wird garantiert, dass diese Nachricht nicht an andere Empfänger (nur für dieselbe Warteschlange bzw. dasselbe Abonnement) ausgeliefert wird. Nach Ablauf der Sperre wird die Nachricht wieder für andere Empfänger verfügbar. Um die Verarbeitung der Nachricht abzuschließen, sollte der Empfänger einen Löschbefehl mit der aus dieser Operation erhaltenen Sperren-ID senden. Um die Verarbeitung der Nachricht aufzugeben und sie für andere Empfänger zu entsperren, sollte ein Befehl Nachricht entsperren ausgegeben werden, andernfalls kann die Sperrdauer ablaufen.

Diese Operation sollte in Anwendungen verwendet werden, die eine At-Least-Once-Zustellungsgarantie benötigen. Wenn der Empfänger die Nachricht nicht löscht, bevor die Verarbeitung erfolgreich ist, stellt dieser Vorgang sicher, dass ein anderer Empfänger die Verarbeitung nach Ablauf der Sperrdauer versuchen kann.

Anforderung

Methode	Anforderungs-URI	HTTP-Version
POST	`http{s}://{serviceNamespace}.servicebus.windows.net/{queuePath}/messages/head` oder `http{s}://{serviceNamespace}.servicebus.windows.net/{topicPath}/subscriptions/{subscriptionName}/messages/head\|HTTP/1.1`

Anforderungsheader

In der folgenden Tabelle werden erforderliche und optionale Anforderungsheader beschrieben. Zusätzlich zu den aufgelisteten Eigenschaften kann der Header auch benutzerdefinierte Eigenschaften enthalten. Siehe das Beispiel.

Anforderungsheader BESCHREIBUNG

Authorization

Anforderungsheader	BESCHREIBUNG
Authorization	Geben Sie einen der folgenden Tokenwerte an: Azure Active Directory (Azure AD) JSON-Webtoken (JWT) Beispiel: `Authorization: Bearer <Azure AD JWT token>`. Informationen zum Generieren eines Azure AD-Tokens finden Sie unter Authentifizieren von einer Anwendung. Ein SAS-Token. Beispiel: `Authorization: SharedAccessSignature sr=<NAMESPACE NAME>.servicebus.windows.net&sig=<SHARED ACCESS KEY>&se=<TOKEN EXPIRY INSTANT>&skn=<SHARED KEY NAME>`. Informationen zum Generieren eines SAS-Tokens finden Sie unter Generieren eines Shared Access Signature-Tokens und Generieren eines SAS-Tokens.

Geben Sie einen der folgenden Tokenwerte an:

Azure Active Directory (Azure AD) JSON-Webtoken (JWT)
Beispiel: Authorization: Bearer <Azure AD JWT token>.
Informationen zum Generieren eines Azure AD-Tokens finden Sie unter Authentifizieren von einer Anwendung.
Ein SAS-Token.
Beispiel: Authorization: SharedAccessSignature sr=<NAMESPACE NAME>.servicebus.windows.net&sig=<SHARED ACCESS KEY>&se=<TOKEN EXPIRY INSTANT>&skn=<SHARED KEY NAME>.
Informationen zum Generieren eines SAS-Tokens finden Sie unter Generieren eines Shared Access Signature-Tokens und Generieren eines SAS-Tokens.

Anforderungstext

Keine.

Antwort

Die Antwort enthält den HTTP-Statuscode, einen Satz von Antwortheadern und den Antworttext.

Antwortcodes

Code	BESCHREIBUNG
201	Nachricht erfolgreich abgerufen und gesperrt.
204	Keine Nachrichten in der angegebenen Zeitüberschreitungsperiode verfügbar.
400	Ungültige Anforderung.
401	Autorisierungsfehler
410	Angegebene Warteschlange bzw. Abonnement existiert nicht.
500	Interner Fehler.

Informationen zu status Codes finden Sie unter Status- und Fehlercodes.

Antwortheader

Die Antwort für diesen Vorgang umfasst die folgenden Header. Die Antwort kann außerdem weitere HTTP-Standardheader enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Antwortheader	BESCHREIBUNG
`Content-Type`	Legen Sie diese Option auf `application/atom+xml;type=entry;charset=utf-8` fest.
`Location`	Die URI der gesperrten Nachricht. Mit dieser URI können Sie die Nachricht freischalten oder löschen.
`BrokerProperties`	JSON-codiert `BrokerProperties` der empfangenen Nachricht. Die `LockToken` -Eigenschaft stellt die Sperr-ID für die zurückgegebene Nachricht dar. Die `SequenceNumber` -Eigenschaft stellt die Sequenznummer der zurückgegebenen Nachricht dar.

Antworttext

Der Antworttext ist der Nachrichtentext der abgerufenen Nachricht.

Beispiel

Die folgende HTTP-Anforderung sperrt und gibt eine Nachricht aus einer Warteschlange zurück:

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 gibt die folgende Antwort zurück. Die Nachricht enthält die benutzerdefinierten Eigenschaften Priority und 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

Weitere Informationen

Servicebus-HTTP-Client-Beispiel

Freigeben über