Descripción Respuestas Activos relacionados

Apéndice: respuesta de SelectObjectContent

Descripción

La operación de Amazon S3 Select filtra el contenido de un objeto de Amazon S3 en función de una instrucción de lenguaje de consulta estructurado (SQL) simple. Dado que se desconoce el tamaño de la respuesta de esta operación, Amazon S3 Select transmite la respuesta como una serie de mensajes e incluye un encabezado Transfer-Encoding con chunked como su valor en la respuesta.

Para obtener más información sobre Amazon S3 Select, consulte Selección de contenido de objetos en la Guía del usuario de Amazon Simple Storage Service.

Para obtener más información acerca del uso de SQL con Amazon S3 Select, consulte Referencia de SQL para Amazon S3 Select y Amazon Glacier Select en la Guía del usuario de Amazon Simple Storage Service.

Respuestas

Si la operación de Amazon S3 Select se realiza correctamente, se devuelve el código de estado 200 OK.

Encabezados de respuesta

Esta implementación de la operación solo usa encabezados de respuesta que sean comunes a la mayoría de las respuestas. Para obtener más información, consulte Encabezados de respuesta comunes.

Cuerpo de respuesta

Dado que se desconoce el tamaño de la respuesta de Amazon S3 Select, Amazon S3 transmite la respuesta como una serie de mensajes e incluye un encabezado Transfer-Encoding con chunked como su valor en la respuesta. En el ejemplo siguiente, se muestra el formato de respuesta en el nivel superior:


<Message 1>
<Message 2>
<Message 3>
......
<Message n>

Cada mensaje se compone de dos secciones: el preludio y los datos. La sección de preludio contiene 1) la longitud total en bytes del mensaje y 2) la longitud en bytes combinada de todos los encabezados. La sección de datos contiene 1) los encabezados y 2) una carga útil.

Cada sección termina con una suma de comprobación de enteros big-endian de 4 bytes (CRC). Amazon S3 Select utiliza CRC32 (a menudo denominado CRC32 de GZIP) para calcular ambos CRC. Para obtener más información sobre CRC32, consulte GZIP file format specification version 4.3.

La carga total del mensaje incluido el preludio y las dos sumas de comprobación es de 16 bytes.

nota

Todos los valores de integer de los mensajes están en orden de bytes de red o en orden big-endian.

En el siguiente diagrama, se muestran los componentes que conforman un mensaje y un encabezado. Tenga en cuenta que hay varios encabezados por mensaje.

Una estructura de mensaje de ejemplo que muestra la longitud total de bytes, la longitud de bytes del encabezado, el CRC del preludio, el encabezado, la carga útil y el CRC del mensaje.

nota

En Amazon S3 Select, el tipo de valor del encabezado es siempre 7 (type=String). Para este tipo, el valor del encabezado consta de dos componentes: una longitud de enteros big-endian de 2 bytes y una cadena UTF-8 que tiene esa longitud de bytes. En el siguiente diagrama, se muestran los componentes que conforman encabezados de Amazon S3 Select.

Estructura de encabezados que muestra la longitud en bytes del nombre del encabezado, la cadena del nombre del encabezado, el tipo de valor del encabezado, la longitud en bytes del valor y la cadena de valores.

Cálculos de longitud de bytes de carga útil (estos dos cálculos son equivalentes):

payload_length = total_length - header_length - sizeOf(total_length) - sizeOf(header_length) - sizeOf(prelude_crc) - sizeOf(message_crc)
payload_length = total_length - header_length - 16

Cada mensaje contiene los siguientes componentes:

Preludio: siempre tiene un tamaño fijo de 8 bytes (dos campos de 4 bytes cada uno):
- Primeros cuatro bytes: longitud total de bytes: se trata de la longitud en bytes indicada en números enteros big-endian de todo el mensaje (incluido el propio campo de longitud total de 4 bytes).
- Segundos cuatro bytes: longitud en bytes de los encabezados: longitud en bytes de enteros big-endian de la parte de los encabezados del mensaje (sin incluir el propio campo de longitud de los encabezados).
CRC del preludio: suma de comprobación de enteros big-endian de 4 bytes (CRC) de la parte del preludio del mensaje (sin incluir la propia CRC). El preludio tiene una CRC independiente de la CRC del mensaje (ver abajo) y que garantiza que la información dañada sobre la longitud de bytes se puede detectar de forma inmediata, sin generar comportamiento del almacenamiento en búfer compulsivo.
Encabezados: un conjunto de metadatos que actúan como comentarios del mensaje; por ejemplo, el tipo de mensaje, el formato de carga útil, etc. Los mensajes pueden tener varios encabezados, por lo que esta parte del mensaje puede tener longitudes de bytes diferentes según el tipo de mensaje. Los encabezados son pares clave-valor en los que la clave y el valor son cadenas UTF-8. Los encabezados pueden aparecer en cualquier orden en la parte del mensaje de los encabezados y cada tipo de encabezado solamente puede aparecer una vez.

Para Amazon S3 Select, a continuación, se muestra una lista de nombres de encabezados y el conjunto de valores válidos en función del tipo de mensaje.
- Encabezado MessageType:
  - HeaderName => “:message-type”
  - HeaderValues válidos => “error”, “event”
- Encabezado EventType:
  - HeaderName => “:event-type”
  - HeaderValues válidos => “Records”, “Cont”, “Progress”, “Stats”, “End”
- Encabezado ErrorCode:
  - HeaderName => “:error-code”
  - HeaderValues válidos => Código de error de la tabla de la sección Lista de códigos de error de contenido de objeto SELECT.
- Encabezado ErrorMessage:
  - HeaderName => “:error-message”
  - HeaderValues válidos => Mensaje de error devuelto por el servicio para ayudar a diagnosticar los errores por solicitud.
Carga útil: puede ser cualquier cosa.
CRC del mensaje: suma de comprobación de enteros big-endian de 4 bytes (CRC) desde el principio del mensaje hasta el inicio de la suma de comprobación (es decir, todo lo que contiene el mensaje, excepto la propia CRC del mensaje).

Cada encabezado contiene los siguientes componentes. Puede haber varios encabezados por mensaje.

Longitud en bytes del nombre de encabezado: longitud de bytes del nombre del encabezado.
Nombre de encabezado: nombre del encabezado que indica el tipo de encabezado. Valores válidos: “:message-type” “:event-type” “:error-code” “:error-message”
Tipo de valor del encabezado: enumeración que indica el tipo de valor del encabezado. Para Amazon S3 Select, siempre es 7.
Longitud en bytes de cadena de valores: (para Amazon S3 Select) longitud en bytes de la cadena de valores del encabezado.
Cadena de valores del encabezado: (para Amazon S3 Select) valor de la cadena del encabezado. Los valores válidos de este campo varían en función del tipo de encabezado. Consulte las secciones siguientes para ver los valores válidos para cada tipo de encabezado y tipo de mensaje.

Para Amazon S3 Select, las respuestas pueden ser mensajes de los siguientes tipos:

Mensaje de registros: puede contener un registro único, registros parciales o varios registros. En función del tamaño del resultado, una respuesta puede contener uno o más de estos mensajes.
Mensaje de continuación: Amazon S3 envía este mensaje periódicamente para mantener abierta la conexión TCP. Estos mensajes aparecen en las respuestas de forma aleatoria. El cliente debe detectar el tipo de mensaje y procesarlo en consecuencia.
Mensaje de progreso: Amazon S3 envía este mensaje periódicamente, si se solicita. Contiene información acerca del progreso de una consulta que se ha iniciado, pero aún no se ha completado.
Mensaje de estadísticas: Amazon S3 envía este mensaje al final de la solicitud. Contiene estadísticas sobre la consulta.
Mensaje final: indica que la solicitud está completa y que no se enviarán más mensajes. No debe suponer que la solicitud está completa hasta que el cliente reciba un mensaje End.
Mensaje RequestLevelError: Amazon S3 envía este mensaje si la solicitud ha producido un error por alguna razón. Contiene el código de error y el mensaje de error. Si Amazon S3 envía un mensaje RequestLevelError, no envía ningún mensaje End.

En las siguientes secciones, se explica con más detalle la estructura de cada tipo de mensaje.

Para ver ejemplos de código y pruebas unitarias que utilizan este protocolo, consulte AWS C Event Stream en el sitio web de GitHub.