Peek Messages

  • Articolo

L'operazione Peek Messages recupera uno o più messaggi dalla parte anteriore della coda, ma non modifica la visibilità del messaggio.

Richiesta

È possibile costruire la Peek Messages richiesta come indicato di seguito. È consigliabile usare HTTPS. Sostituire myaccount con il nome dell'account di archiviazione e sostituire myqueue con il nome della coda:

Metodo URI richiesta Versione HTTP
GET https://myaccount.queue.core.windows.net/myqueue/messages?peekonly=true HTTP/1.1

Richiesta del servizio di archiviazione emulata

Quando si effettua una richiesta con il servizio di archiviazione emulato, specificare il nome host dell'emulatore e la porta del servizio Code come 127.0.0.1:10001, seguita dal nome dell'account di archiviazione emulato:

Metodo URI richiesta Versione HTTP
GET http://127.0.0.1:10001/devstoreaccount1/myqueue/messages?peekonly=true HTTP/1.1

Per altre informazioni, vedere Usare l'emulatore Azurite per lo sviluppo locale di Archiviazione di Azure.

Parametri URI

Nell'URI richiesta è possibile specificare i seguenti parametri.

Parametro Descrizione
numofmessages Facoltativa. Valore intero diverso da zero che specifica il numero di messaggi da osservare nella coda, fino a un massimo di 32. Per impostazione predefinita, un singolo messaggio viene osservato dalla coda con questa operazione.
timeout Facoltativa. Il parametro timeout viene espresso in secondi. Per altre informazioni, vedere Impostare timeout per le operazioni del servizio code.

Intestazioni della richiesta

Le intestazioni di richiesta obbligatorie e facoltative sono descritte nella tabella seguente:

Intestazione della richiesta Descrizione
Authorization Obbligatorio. Specifica lo schema di autorizzazione, il nome dell'account e la firma. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
Date o x-ms-date Obbligatorio. Specifica la data per la richiesta nel fuso orario UTC (Coordinated Universal Time). Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
x-ms-version Facoltativa. Specifica la versione dell'operazione da usare per questa richiesta. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.
x-ms-client-request-id Facoltativa. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log quando la registrazione è configurata. È consigliabile usare questa intestazione per correlare le attività lato client con le richieste ricevute dal server. Per altre informazioni, vedere Monitorare l'archiviazione code di Azure.

Testo della richiesta

Nessuno.

Risposta

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

Codice stato

Un'operazione completata correttamente restituisce 200 (OK).

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

Intestazioni di risposta

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

Intestazione risposta Descrizione
x-ms-request-id Identifica in modo univoco la richiesta effettuata e puoi usarla per risolvere la risoluzione dei problemi della richiesta. Per altre informazioni, vedere Risolvere i problemi relativi alle operazioni api.
x-ms-version Versione del servizio Code usata per eseguire la richiesta. Restituito per le richieste effettuate rispetto alla versione 2009-09-19 e successive.
Date Valore di data/ora UTC generato dal servizio, che indica l'ora in cui è stata avviata la risposta.
x-ms-client-request-id Può essere usato per risolvere i problemi delle richieste e delle relative risposte corrispondenti. Il valore di questa intestazione è uguale al valore dell'intestazione x-ms-client-request-id se presente nella richiesta e il valore non contiene più di 1.024 caratteri ASCII visibili. Se l'intestazione x-ms-client-request-id non è presente nella richiesta, non sarà presente nella risposta.

Corpo della risposta

La risposta XML per l'operazione Peek Messages viene restituita nel formato seguente.

L'elemento MessageID è un valore GUID che identifica il messaggio nella coda. Questo valore viene assegnato al messaggio dal servizio di accodamento e risulta opaco al client.

Gli elementi InsertionTime e ExpirationTime vengono rappresentati come valori UTC e formattati come descritto in RFC 1123.

L'elemento DequeueCount presenta un valore 1 la prima volta che il messaggio viene rimosso dalla coda. Questo valore viene incrementato ogni volta che il messaggio viene rimosso dalla coda.

Nota

L'elemento DequeueCount viene restituito nel corpo della risposta solo se la coda è stata creata con il servizio code versione 2009-09-19.

<QueueMessagesList>  
    <QueueMessage>  
      <MessageId>string-message-id</MessageId>  
      <InsertionTime>insertion-time</InsertionTime>  
      <ExpirationTime>expiration-time</ExpirationTime>  
      <DequeueCount>integer</DequeueCount>  
      <MessageText>message-body</MessageText>  
    </QueueMessage>  
</QueueMessagesList>

Nota

Questa risposta è diversa dalla risposta per l'operazione Get Messages in che non contiene gli PopReceipt elementi o TimeNextVisible .

Risposta di esempio

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Fri, 16 Sep 2011 22:51:18 GMT  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
  
Response Body:  
<?xml version="1.0" encoding="utf-8"?>  
<QueueMessagesList>  
  <QueueMessage>  
    <MessageId>06eba214-8107-4412-a7f6-710a9baff647</MessageId>  
    <InsertionTime>Fri, 09 Oct 2009 18:59:54 GMT</InsertionTime>  
    <ExpirationTime>Fri, 16 Sep 2009 18:59:54 GMT</ExpirationTime>  
    <DequeueCount>1</DequeueCount>  
    <MessageText>PHRlc3Q+dGhpcyBpcyBhIHRlc3QgbWVzc2FnZTwvdGVzdD4=</MessageText>  
  </QueueMessage>  
</QueueMessagesList>

Autorizzazione

Questa operazione può essere eseguita dal proprietario dell'account e da chiunque abbia una firma di accesso condiviso che dispone dell'autorizzazione per eseguire questa operazione.

Commenti

Quando un messaggio viene recuperato dalla coda con peekonly impostato su true, la visibilità del messaggio rimane invariata. Il messaggio rimane disponibile per altri consumer della coda fino a quando un client recupera il messaggio usando l'operazione Recupera messaggi . Il client che richiede il messaggio non riceve una ricevuta popup con la risposta e pertanto non può eliminare il messaggio.

È possibile recuperare solo i messaggi visibili con l'operazione Peek Messages . Si noti che il numero massimo di messaggi che possono essere recuperati è 32.

Quando un messaggio viene recuperato per la prima volta con una chiamata a Get Messages, la proprietà DequeueCount è impostata su 1. Se non viene eliminato e viene recuperato di nuovo, la DequeueCount proprietà viene incrementata. Il client può usare questo valore per determinare il numero di volte in cui è stato recuperato un messaggio.

Nota

Una chiamata a non incrementa Peek Messages il valore di DequeueCount, ma restituisce questo valore per la lettura del client.

Se il parametro numofmessages non è compreso nell'intervallo, il servizio restituisce il codice di stato 400 (richiesta non valida), insieme a informazioni di errore aggiuntive, come illustrato nell'esempio seguente:

HTTP/1.1 400 One of the query parameters specified in the request URI is outside the permissible range.  
Connection: Keep-Alive  
Content-Length: 455  
Via: 1.1 TK5-PRXY-22  
Date: Wed, 02 May 2012 19:37:23 GMT  
Content-Type: application/xml  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: 6a03526c-ca2c-4358-a63a-b5d096988533  
x-ms-version: 2011-08-18  
  
<?xml version="1.0" encoding="utf-8"?>  
   <Error>  
      <Code>OutOfRangeQueryParameterValue</Code>  
      <Message>One of the query parameters specified in the request URI is outside the permissible range.  
               RequestId:6a03526c-ca2c-4358-a63a-b5d096988533  
               Time:2012-05-02T19:37:24.2438463Z  
      </Message>  
      <QueryParameterName>numofmessages</QueryParameterName>  
      <QueryParameterValue>0</QueryParameterValue>  
      <MinimumAllowed>1</MinimumAllowed>  
      <MaximumAllowed>32</MaximumAllowed>  
   </Error>

Vedi anche

Autorizzare le richieste ad Archiviazione di Azure
Stato e codici errore
Codici di errore del servizio code