Obtener mensajes

La operación Get Messages recupera uno o varios mensajes de la parte delantera de la cola.

Request

La solicitud Get Messages se puede construir como sigue. Se recomienda usar HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento y reemplace por myqueue el nombre de la cola:

Método	URI de solicitud	Versión de HTTP
GET	https://myaccount.queue.core.windows.net/myqueue/messages	HTTP/1.1

Solicitud del servicio de almacenamiento emulado

Cuando realice una solicitud en el servicio de almacenamiento emulado, especifique el nombre de host del emulador y el puerto de Azure Queue Storage como 127.0.0.1:10001, seguido del nombre de la cuenta de almacenamiento emulada:

Método	URI de solicitud	Versión de HTTP
GET	http://127.0.0.1:10001/devstoreaccount1/myqueue/messages	HTTP/1.1

Para más información, consulte Uso del emulador de Azurite para desarrollo y pruebas locales de Azure Storage.

Parámetros del identificador URI

Se pueden especificar los parámetros adicionales siguientes en el URI de solicitud.

Parámetro	Descripción
numofmessages	Opcional. Valor entero distinto de cero que especifica el número de mensajes que se deben recuperar de la cola, hasta un máximo de 32. Si hay menos mensajes visibles, se devuelven los mensajes visibles. De forma predeterminada, con esta operación se recupera un solo mensaje de la cola.
visibilitytimeout	Opcional. Especifica el nuevo valor de tiempo de espera de visibilidad, en segundos, en relación con la hora del servidor. El valor predeterminado es 30 segundos. Un valor especificado debe ser mayor o igual que 1 segundo y no puede ser mayor que 7 días o mayor que 2 horas en versiones del protocolo REST anteriores a 2011-08-18. El tiempo de espera de visibilidad de un mensaje se puede establecer en un valor posterior a la hora de expiración.
timeout	Opcional. El parámetro timeout se expresa en segundos. Para más información, consulte Establecimiento de tiempos de espera para las operaciones de Azure Queue Storage.

Encabezados de solicitud

En la tabla siguiente se describen los encabezados de solicitud requeridos y opcionales.

Encabezado de solicitud	Descripción
Authorization	Necesario. Especifica el esquema de autorización, el nombre de cuenta y la firma. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
Date o x-ms-date	Necesario. Especifica la hora universal coordinada (UTC) de la solicitud. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
x-ms-version	Opcional. Especifica la versión de la operación que se utiliza para esta solicitud. Para obtener más información, vea Versiones de los servicios de Azure Storage.
x-ms-client-request-id	Opcional. Proporciona un valor opaco generado por el cliente con un límite de caracteres de 1 kibibyte (KiB) que se registra en los registros cuando se configura el registro. Se recomienda encarecidamente usar este encabezado para correlacionar las actividades del lado cliente con las solicitudes que recibe el servidor. Para más información, consulte Supervisión de Azure Queue Storage.

Cuerpo de la solicitud

Ninguno.

Response

La respuesta incluye un código de estado HTTP y un conjunto de encabezados de respuesta.

status code

Una operación correcta devuelve el código de estado 200 Correcto.

Para obtener más información sobre los códigos de estado, consulte Códigos de estado y error.

Encabezados de respuesta

La respuesta para esta operación incluye los encabezados siguientes. La respuesta también puede incluir otros encabezados HTTP estándar. Todos los encabezados estándar se ajustan a la especificación del protocolo HTTP/1.1.

Encabezado de respuesta	Descripción
x-ms-request-id	Identifica de forma única la solicitud que se realizó y se puede usar para solucionar problemas de la solicitud. Para más información, consulte Solución de problemas de operaciones de API.
x-ms-version	Indica la versión de Azure Queue Storage que se usó para ejecutar la solicitud. Este encabezado se devuelve para las solicitudes realizadas en la versión 2009-09-19 y posteriores.
Date	Valor de fecha y hora UTC generado por el servicio, que indica la hora en que se inició la respuesta.
x-ms-client-request-id	Se puede usar para solucionar problemas de solicitudes y respuestas correspondientes. El valor de este encabezado es igual al valor del x-ms-client-request-id encabezado si está presente en la solicitud y el valor no contiene más de 1024 caracteres ASCII visibles. Si el x-ms-client-request-id encabezado no está presente en la solicitud, no estará presente en la respuesta.

Response body

El código XML de respuesta para la operación Get Messages se devuelve con el formato siguiente.

El elemento MessageID es un valor de GUID que identifica el mensaje de la cola. Azure Queue Storage asigna este valor al mensaje y es opaco para el cliente. Puede usar el valor junto con el PopReceipt valor del elemento para eliminar un mensaje de la cola después de recuperarlo mediante la Get Messages operación . El valor de PopReceipt también es opaco para el cliente. Su único propósito es asegurarse de que se puede eliminar un mensaje con la operación Eliminar mensaje .

Los elementos InsertionTime, ExpirationTime y TimeNextVisible se representan como valores UTC con el formato descrito en RFC 1123.

El elemento DequeueCount tiene el valor 1 la primera vez que el mensaje se quita de la cola. Este valor se incrementa cada vez que el mensaje se quita de la cola posteriormente.

Nota

El DequeueCount elemento se devuelve en el cuerpo de la respuesta solo si la cola se creó mediante Azure Queue Storage versión 2009-09-19.

<QueueMessagesList>  
    <QueueMessage>  
      <MessageId>string-message-id</MessageId>  
      <InsertionTime>insertion-time</InsertionTime>  
      <ExpirationTime>expiration-time</ExpirationTime>  
      <PopReceipt>opaque-string-receipt-data</PopReceipt>  
      <TimeNextVisible>time-next-visible</TimeNextVisible>  
      <DequeueCount>integer</DequeueCount>  
      <MessageText>message-body</MessageText>  
    </QueueMessage>  
</QueueMessagesList>  

Respuesta de muestra

Response Status:  
HTTP/1.1 200 OK  
Response Headers:  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Fri, 16 Sep 2011 21:04:30 GMT  
Server: Windows-Azure-Queue/1.0 Microsoft-HTTPAPI/2.0  
  
Response Body:  
<?xml version="1.0" encoding="utf-8"?>  
<QueueMessagesList>  
  <QueueMessage>  
    <MessageId>5974b586-0df3-4e2d-ad0c-18e3892bfca2</MessageId>  
    <InsertionTime>Fri, 09 Oct 2009 21:04:30 GMT</InsertionTime>  
    <ExpirationTime>Fri, 16 Oct 2009 21:04:30 GMT</ExpirationTime>  
    <PopReceipt>YzQ4Yzg1MDItYTc0Ny00OWNjLTkxYTUtZGM0MDFiZDAwYzEw</PopReceipt>  
    <TimeNextVisible>Fri, 09 Oct 2009 23:29:20 GMT</TimeNextVisible>  
    <DequeueCount>1</DequeueCount>  
    <MessageText>PHRlc3Q+dGhpcyBpcyBhIHRlc3QgbWVzc2FnZTwvdGVzdD4=</MessageText>  
  </QueueMessage>  
</QueueMessagesList>  

Authorization

Esta operación la puede realizar el propietario de la cuenta y cualquiera que tenga una firma de acceso compartido con permiso para realizar esta operación.

Comentarios

El contenido del mensaje se recupera en el formato que se usó para la operación Put Message .

Cuando un mensaje se recupera de la cola, la respuesta incluye el mensaje y un valor de recepción de confirmación, que es necesario para eliminar dicho mensaje. El mensaje no se elimina automáticamente de la cola, pero después de recuperarlo, no es visible para otros clientes durante el intervalo de tiempo especificado por el visibilitytimeout parámetro .

Si se recuperan varios mensajes, cada mensaje tiene asociada una confirmación de recepción. El número máximo de mensajes que se pueden recuperar al mismo tiempo es 32.

Se espera que el cliente que recupere el mensaje elimine el mensaje después de que se haya procesado y antes de la hora especificada por el TimeNextVisible elemento de la respuesta, que se calcula en función del valor del visibilitytimeout parámetro . El valor de visibilitytimeout se agrega a la hora en que se recupera el mensaje para determinar el valor de TimeNextVisible.

Debido a la asimetría del reloj, un mensaje que se recupera con un determinado visibilitytimeout puede volver a aparecer antes de que haya transcurrido el tiempo de espera especificado. Tenga en cuenta que un cliente puede deducir que un mensaje ya ha sido puesto en cola por un cliente diferente en función de la recepción pop, que es única para cada puesta en cola de un mensaje. Si la recepción pop de un cliente ya no funciona para eliminar o actualizar un mensaje, y el cliente recibe un error 404 (no encontrado), otro cliente ha puesto en cola el mensaje.

Normalmente, cuando un consumidor recupera un mensaje a través Get Messagesde , ese mensaje se reserva para su eliminación hasta que expire el intervalo visibilitytimeout . Pero este comportamiento no está garantizado. Una vez expirado el intervalo visibilitytimeout , el mensaje vuelve a ser visible para otros consumidores. Si el mensaje no se recupera y elimina posteriormente por otro consumidor, el consumidor original puede eliminar el mensaje mediante el recibo pop original.

Cuando un mensaje se recupera por primera vez, su propiedad DequeueCount se establece en 1. Si no se elimina y posteriormente se recupera de nuevo, se incrementa la DequeueCount propiedad . El cliente puede utilizar este valor para determinar cuántas veces se ha recuperado un mensaje.

Si el parámetro visibilitytimeout o numofmessages está fuera del intervalo, el servicio devuelve el código de estado 400 (solicitud incorrecta), junto con información de error adicional, como se muestra en el ejemplo siguiente.

  
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>  
  

Consulte también

Códigos de error de Azure Queue Storage
Autorización de solicitudes a Azure Storage
Estado y códigos de error