messaggio Peek-Lock (lettura non distruttiva)

Articolo
03/19/2025

Questa operazione recupera e blocca in modo atomico un messaggio da una coda o una sottoscrizione per l'elaborazione. Il messaggio non deve essere recapitato ad altri ricevitori (solo nella stessa coda o sottoscrizione) durante la durata del blocco specificata nella descrizione della coda o della sottoscrizione. Alla scadenza del blocco, il messaggio diventa disponibile per altri ricevitori. Per completare l'elaborazione del messaggio, il ricevitore deve eseguire un comando delete con l'ID di blocco ricevuto da questa operazione. Per abbandonare l'elaborazione del messaggio e sbloccarla per altri ricevitori, deve essere eseguito un comando sblocca messaggio; in caso contrario, il periodo di durata del blocco può scadere.

Questa operazione deve essere usata nelle applicazioni che richiedono garanzie di recapito con at-least-once. Se il ricevitore non elimina il messaggio prima che l'elaborazione abbia esito positivo, questa operazione garantisce che un altro ricevitore sia in grado di tentare l'elaborazione dopo la scadenza del periodo di durata del blocco.

Richiesta

Metodo	URI della richiesta	Versione HTTP
INSERISCI	`http{s}://{serviceNamespace}.servicebus.windows.net/{queuePath}/messages/head` o `http{s}://{serviceNamespace}.servicebus.windows.net/{topicPath}/subscriptions/{subscriptionName}/messages/head\|HTTP/1.1`

Intestazioni della richiesta

Nella tabella seguente vengono descritte le intestazioni di richiesta obbligatorie e facoltative. Oltre alle proprietà elencate, l'intestazione può contenere proprietà personalizzate. Vedere l'esempio.

Intestazione richiesta Descrizione

Autorizzazione

Intestazione richiesta	Descrizione
Autorizzazione	Specificare uno dei valori di token seguenti: Token JWT (Microsoft Entra JSON Web Token). Esempio: `Authorization: Bearer <Azure AD JWT token>`. Per informazioni sulla generazione di un token Microsoft Entra, vedere Authenticate from an application. Token di firma di accesso condiviso. Esempio: `Authorization: SharedAccessSignature sr=<NAMESPACE NAME>.servicebus.windows.net&sig=<SHARED ACCESS KEY>&se=<TOKEN EXPIRY INSTANT>&skn=<SHARED KEY NAME>`. Per informazioni sulla generazione di un token di firma di accesso condiviso, vedere Generare un token di firma di accesso condiviso e Generare un token di firma di accesso condiviso.

Specificare uno dei valori di token seguenti:

Token JWT (Microsoft Entra JSON Web Token).
Esempio: Authorization: Bearer <Azure AD JWT token>.
Per informazioni sulla generazione di un token Microsoft Entra, vedere Authenticate from an application.
Token di firma di accesso condiviso.
Esempio: Authorization: SharedAccessSignature sr=<NAMESPACE NAME>.servicebus.windows.net&sig=<SHARED ACCESS KEY>&se=<TOKEN EXPIRY INSTANT>&skn=<SHARED KEY NAME>.
Per informazioni sulla generazione di un token di firma di accesso condiviso, vedere Generare un token di firma di accesso condiviso e Generare un token di firma di accesso condiviso.

Corpo della richiesta

Nessuno.

Risposta

La risposta include un codice di stato HTTP, un set di intestazioni di risposta e il corpo della risposta.

Codici di risposta

Codice	Descrizione
201	Messaggio recuperato e bloccato correttamente.
204	Nessun messaggio disponibile entro il periodo di timeout specificato.
400	Richiesta non valida.
401	Errore di autorizzazione.
410	La coda o la sottoscrizione specificata non esiste.
500	Errore interno.

Per informazioni sui codici di stato, vedere Status and Error Codes.

Intestazioni di risposta

La risposta per questa operazione include le intestazioni seguenti. La risposta potrebbe includere anche intestazioni HTTP più standard. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1 .

Intestazione della risposta	Descrizione
`Content-Type`	Impostare su `application/atom+xml;type=entry;charset=utf-8`.
`Location`	URI del messaggio bloccato. È possibile usare questo URI per sbloccare o eliminare il messaggio.
`BrokerProperties`	`BrokerProperties` con codifica JSON del messaggio ricevuto. La proprietà `LockToken` rappresenta l'ID di blocco per il messaggio restituito. La proprietà `SequenceNumber` rappresenta il numero di sequenza del messaggio restituito.

Corpo della risposta

Il corpo della risposta è il corpo del messaggio recuperato.

Esempio

La richiesta HTTP seguente blocca e restituisce un messaggio da una coda:

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

Il bus di servizio restituisce la risposta seguente. Il messaggio contiene le proprietà personalizzate Priority e 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

Condividi tramite