Put Message

Artículo
08/05/2023

La operación Put Message agrega un nuevo mensaje al final de la cola de mensajes. También se puede especificar un tiempo de espera de visibilidad para que el mensaje sea invisible hasta que expire el tiempo de espera de visibilidad. Un mensaje debe estar en un formato tal que se pueda incluir en una solicitud XML con codificación UTF-8. El mensaje codificado puede tener un tamaño de hasta 64 kibibytes (KiB) para la versión 2011-08-18 y posteriores, o 8 KiB para versiones anteriores.

Request

Puede construir la Put Message solicitud como se indica a continuación. Se recomienda usar HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento y myqueue por el nombre de la cola:

Método	URI de solicitud	Versión de HTTP
`POST`	`https://myaccount.queue.core.windows.net/myqueue/messages?visibilitytimeout=<int-seconds>&messagettl=<int-seconds>`	HTTP/1.1

Solicitud de servicio de almacenamiento emulada

Cuando realice una solicitud en el servicio de almacenamiento emulado, especifique el nombre de host del emulador y el puerto de 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
`POST`	`http://127.0.0.1:10001/devstoreaccount1/myqueue/messages?visibilitytimeout=<int-seconds>&messagettl=<int-seconds>`	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

Puede especificar los parámetros siguientes en el URI de solicitud:

Parámetro	Descripción
`visibilitytimeout=<int=seconds>`	Opcional. Especifica el nuevo valor de tiempo de espera de visibilidad, en segundos, en relación con la hora del servidor. Si se especifica, la solicitud se debe realizar mediante un `x-ms-version` de 2011-08-18 o posterior. Si no se especifica, el valor predeterminado es 0. El nuevo valor debe ser mayor o igual que 0 y no puede ser mayor que 7 días. El tiempo de espera de visibilidad de un mensaje no se puede establecer en un valor posterior a la fecha de expiración. Establezca `visibilitytimeout` en un valor menor que el valor de período de vida.
`messagettl=<int-seconds>`	Opcional. Especifica el intervalo del período de vida para el mensaje, en segundos. En versiones anteriores a 2017-07-29, el período máximo de vida permitido es de 7 días. Para la versión 2017-07-29 y posteriores, el período máximo de vida puede ser cualquier número positivo y `-1`, lo que indica que el mensaje no expira. Si se omite este parámetro, el período de vida predeterminado es de 7 días.
`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 Queue Service.

Encabezados de solicitud

Los encabezados de solicitud obligatorios y opcionales se describen en la tabla siguiente:

Encabezado de solicitud	Descripción
`Authorization`	Necesario. Especifica el esquema de autorización, el nombre de la cuenta y la firma. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
`Date` `or 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.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene los datos del mensaje en el formato XML siguiente. Tenga en cuenta que el contenido del mensaje debe estar en un formato que se pueda codificar con UTF-8.

<QueueMessage>  
    <MessageText>message-content</MessageText>  
</QueueMessage>

Solicitud de ejemplo

Request:  
POST https://myaccount.queue.core.windows.net/messages?visibilitytimeout=30&timeout=30 HTTP/1.1  
  
Headers:  
x-ms-version: 2011-08-18  
x-ms-date: Tue, 30 Aug 2011 01:03:21 GMT  
Authorization: SharedKey myaccount:sr8rIheJmCd6npMSx7DfAY3L//V3uWvSXOzUBCV9wnk=  
Content-Length: 100  
  
Body:  
<QueueMessage>  
<MessageText>PHNhbXBsZT5zYW1wbGUgbWVzc2FnZTwvc2FtcGxlPg==</MessageText>  
</QueueMessage>

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 201 (Creado).

Para obtener más información sobre los códigos de estado, vea Códigos de estado y de 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 solicitud	Descripción
`x-ms-request-id`	Identifica de forma única la solicitud que se realizó y puede usarla 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 Queue Service 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 a la que se inició la respuesta.
`x-ms-client-request-id`	Este encabezado 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

A partir de la versión 2016-05-31, la respuesta de la Put Message operación contiene la información del mensaje en el cuerpo de la respuesta. El formato XML del cuerpo devuelto se describe aquí.

El elemento MessageID es un valor de GUID que identifica el mensaje de la cola. Queue Storage asigna este valor al mensaje y es opaco para el cliente. Este valor se puede usar junto con el valor del elemento PopReceipt para eliminar o actualizar un mensaje de la cola. El valor de PopReceipt también es opaco para el cliente y es necesario cuando se usan las API Delete Message o Update Message.

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

<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>
    </QueueMessage>
</QueueMessagesList>

Respuesta de muestra

Response Status:
HTTP/1.1 200 OK
Response headers:
Transfer-Encoding: chunked
Content-Type: application/xml
x-ms-version: 2016-05-31
Date: Fri, 09 Oct 2016 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 2016 21:04:30 GMT</InsertionTime>
    <ExpirationTime>Fri, 16 Oct 2016 21:04:30 GMT</ExpirationTime>
    <PopReceipt>YzQ4Yzg1MDItYTc0Ny00OWNjLTkxYTUtZGM0MDFiZDAwYzEw</PopReceipt>
    <TimeNextVisible>Fri, 09 Oct 2016 23:29:20 GMT</TimeNextVisible>
   </QueueMessage>
</QueueMessagesList>

Authorization

El propietario de la cuenta puede realizar esta operación y cualquier persona con una firma de acceso compartido con permisos para realizar esta operación.

Comentarios

El tiempo de espera de visibilidad opcional especifica la hora en que el mensaje es invisible. Una vez expirado el tiempo de espera, el mensaje se vuelve visible. Si no especifica un tiempo de espera de visibilidad, se usa el valor predeterminado de 0.

El período de vida del mensaje opcional especifica cuánto tiempo permanece un mensaje en la cola. El mensaje se elimina de la cola cuando expira el período de vida.

Un mensaje debe estar en un formato tal que se pueda incluir en una solicitud XML con codificación UTF-8. Para incluir marcado en el mensaje, sus contenidos deben tener escape XML o codificación Base64. Se quita cualquier marcado XML del mensaje que no está codificado o con escape antes de que se agregue el mensaje a la cola.

Si el mensaje es demasiado grande, el servicio devuelve el código de estado 400 (Solicitud incorrecta).

Consulte también

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