Blocco di visualizzazione di un messaggio (lettura non distruttiva)

Articolo
08/05/2023

Questa operazione recupera e blocca automaticamente un messaggio da una coda o sottoscrizione per l'elaborazione. Il messaggio non verrà consegnato ad altri ricevitori (solo nella stessa coda o sottoscrizione) per tutta la durata del blocco specificata nella descrizione della coda/sottoscrizione. Alla scadenza del blocco, il messaggio diventa disponibile per altri ricevitori. Per completare l'elaborazione del messaggio, il ricevitore deve eseguire un comando di eliminazione con l'ID di blocco ricevuto da questa operazione. Per abbandonare l'elaborazione del messaggio e sbloccarla per altri ricevitori, è necessario eseguire un comando Sblocca messaggio ; in caso contrario, il periodo di durata del blocco può scadere.

Questa operazione deve essere usata in applicazioni che richiedono livelli di sicurezza del recapito di tipo 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 richiesta	Versione HTTP
POST	`http{s}://{serviceNamespace}.servicebus.windows.net/{queuePath}/messages/head` oppure `http{s}://{serviceNamespace}.servicebus.windows.net/{topicPath}/subscriptions/{subscriptionName}/messages/head\|HTTP/1.1`

Intestazioni richiesta

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

Intestazione della richiesta Descrizione

Autorizzazione

Intestazione della richiesta	Descrizione
Autorizzazione	Specificare uno dei valori di token seguenti: Token JSON Token JSON (JWT) di Azure Active Directory (Azure AD). Esempio: `Authorization: Bearer <Azure AD JWT token>`. Per informazioni sulla generazione di un token di Azure AD, vedere Eseguire l'autenticazione da un'applicazione. Un 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 JSON Token JSON (JWT) di Azure Active Directory (Azure AD).
Esempio: Authorization: Bearer <Azure AD JWT token>.
Per informazioni sulla generazione di un token di Azure AD, vedere Eseguire l'autenticazione da un'applicazione.
Un 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

Nella risposta sono inclusi un codice di stato HTTP, un set di intestazioni della risposta e il corpo della risposta.

Codici di risposta

Codice	Descrizione
201	Messaggio recuperato e bloccato.
204	Nessun messaggio disponibile nel periodo di timeout specificato.
400	Richiesta non valida.
401	Errore di autorizzazione.
410	Coda o sottoscrizione specificata inesistente.
500	Errore interno.

Per informazioni sui codici di stato, vedere Codici di stato e di errore.

Intestazioni della risposta

Nella risposta per questa operazione sono incluse le intestazioni riportate di seguito; inoltre, possono essere incluse intestazioni HTTP standard aggiuntive. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1.

Intestazione di risposta	Descrizione
`Content-Type`	Impostare su `application/atom+xml;type=entry;charset=utf-8`.
`Location`	URI del messaggio bloccato. Questo URI può essere usato per sbloccare o eliminare il messaggio.
`BrokerProperties`	Codifica `BrokerProperties` JSON del messaggio ricevuto. La `LockToken` proprietà rappresenta l'ID di blocco per il messaggio restituito. La `SequenceNumber` proprietà 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

Vedere anche

Esempio di client HTTP del bus di servizio

Condividi tramite