Descrição Respostas Recursos relacionados

Apêndice: resposta SelectObjectContent

Descrição

A operação do Amazon S3 Select filtra o conteúdo de um objeto do Amazon S3 com base em uma declaração de linguagem de consulta estruturada (SQL) simples. Como o tamanho da resposta dessa operação é desconhecido, o Amazon S3 Select transmite a resposta como uma série de mensagens e inclui um cabeçalho Transfer-Encoding com chunked como valor na resposta.

Para obter mais informações sobre o Amazon S3 Select, consulte Seleção de conteúdo de objetos no Guia do usuário do Amazon Simple Storage Service.

Para obter mais informações sobre o uso do SQL com o Amazon S3 Select, consulte Referência de SQL para o Amazon S3 Select e o Amazon Glacier Select no Guia do usuário do Amazon Simple Storage Service.

Respostas

Uma operação bem-sucedida do Amazon S3 Select retorna o código de status 200 OK.

Cabeçalhos de resposta

Essa implementação da operação usa somente os cabeçalhos de resposta que são comuns à maioria das respostas. Para obter mais informações, consulte Cabeçalhos de resposta comuns.

Corpo da resposta

Como o tamanho da resposta do Amazon S3 Select é desconhecido, o Amazon S3 transmite a resposta como uma série de mensagens e inclui um cabeçalho Transfer-Encoding com chunked como valor na resposta. O exemplo a seguir mostra o formato de resposta no nível superior:


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

Cada mensagem consiste em duas seções: o prelúdio e os dados. A seção de prelúdio consiste em 1) tamanho total de bytes da mensagem e 2) tamanho combinado de todos os cabeçalhos. A seção de dados consiste em 1) cabeçalhos e 2) uma carga útil.

Cada seção termina com uma soma de verificação (CRC) inteira big-endian de 4 bytes. O Amazon S3 Select usa CRC32 (geralmente chamado de GZIP CRC32) para calcular os dois CRCs. Para obter mais informações sobre CRC32, consulte Especificação do formato de arquivo GZIP versão 4.3.

O total de sobrecarga de mensagem, incluindo o prelúdio e ambas as somas de verificação, é de 16 bytes.

nota

Todos os valores de integer nas mensagens estão na ordem de bytes da rede ou na ordem big-endian.

O diagrama a seguir mostra os componentes que formam uma mensagem e um cabeçalho. Há vários cabeçalhos por mensagem.

Um exemplo de estrutura de mensagem mostrando o tamanho total de bytes, o tamanho em bytes do cabeçalho, o CRC da prelúdio, o cabeçalho, a carga útil e o CRC da mensagem.

nota

Para o Amazon S3 Select, o tipo de valor do cabeçalho é sempre 7 (type=String). Para esse tipo, o valor do cabeçalho consiste em dois componentes: um comprimento inteiro big-endian de 2 bytes e uma string UTF-8 com esse tamanho de byte. O diagrama a seguir mostra os componentes que formam os cabeçalhos do Amazon S3 Select.

Estrutura de cabeçalhos mostrando o tamanho em bytes do nome do cabeçalho, a string do nome do cabeçalho, o tipo do valor do cabeçalho, o tamanho em bytes do valor e a string do valor.

Cálculos de tamanho em bytes da carga útil (esses dois cálculos são 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 mensagem contém os seguintes componentes:

Prelúdio: sempre com tamanho fixo de 8 bytes (dois campos de 4 bytes cada):
- Primeiros quatro bytes: tamanho total em bytes: tamanho em bytes do inteiro big-endian da mensagem inteira (incluindo o próprio campo de tamanho total de 4 bytes).
- Segundos quatro bytes: tamanho em bytes dos cabeçalhos: tamanho em bytes do inteiro big-endian da parte de cabeçalhos da mensagem (excluindo o próprio campo de tamanho dos cabeçalhos).
CRC do prelúdio: soma de verificação do inteiro big-endian (CRC) de 4 bytes da parte do prelúdio da mensagem (excluindo a própria CRC). O prelúdio tem uma CRC separada da CRC da mensagem (veja abaixo) para garantir que informações corrompidas de tamanho em bytes possam ser detectadas imediatamente, sem causar comportamentos de buffer patológicos.
Cabeçalhos: conjunto de metadados que anotam a mensagem, como o tipo de mensagem, o formato da carga útil, e assim por diante. As mensagens podem ter vários cabeçalhos, portanto, essa parte da mensagem pode ter tamanhos em bytes diferentes, dependendo do tipo de mensagem. Cabeçalhos são pares de chave-valor, onde a chave e o valor são strings UTF-8. Os cabeçalhos podem aparecer em qualquer ordem na parte dos cabeçalhos da mensagem, e qualquer tipo de cabeçalho pode aparecer apenas uma vez.

Para o Amazon S3 Select, confira a seguir uma lista de nomes de cabeçalho e o conjunto de valores válidos, dependendo do tipo de mensagem.
- Cabeçalho MessageType:
  - HeaderName => ":message-type"
  - HeaderValues válidos => "error", "event"
- Cabeçalho EventType:
  - HeaderName => ":event-type"
  - HeaderValues válidos => "Records", "Cont", "Progress", "Stats", "End"
- Cabeçalho ErrorCode:
  - HeaderName => ":error-code"
  - HeaderValues válidos => Código de erro da tabela na seção Lista de códigos de erro de conteúdo do objeto SELECT.
- Cabeçalho ErrorMessage:
  - HeaderName => ":error-message"
  - HeaderValues válidos => Mensagem de erro retornada pelo serviço para ajudar a diagnosticar erros no nível da solicitação.
Carga útil: pode ser qualquer coisa.
CRC da mensagem: soma de verificação do inteiro big-endian (CRC) de 4 bytes do início da mensagem até o início da soma de verificação (ou seja, tudo na mensagem, exceto a própria CRC da mensagem).

Cada cabeçalho contém os seguintes componentes. Pode haver vários cabeçalhos por mensagem.

Tamanho em bytes do nome do cabeçalho: tamanho em bytes do nome do cabeçalho.
Nome do cabeçalho: o nome do cabeçalho que indica o tipo de cabeçalho. Valores válidos: ":message-type" ":event-type" ":error-code" ":error-message"
Tipo de valor de cabeçalho: enumeração que indica o tipo de valor de cabeçalho. Para o Amazon S3 Select, esse valor é sempre 7.
Tamanho em bytes da string de valor: (para o Amazon S3 Select) tamanho em bytes da string de valor do cabeçalho.
String de valor do cabeçalho: (para o Amazon S3 Select) valor da string do cabeçalho. Os valores válidos para esse campo variam de acordo com o tipo do cabeçalho. Consulte as seções abaixo para ver os valores válidos para cada tipo de cabeçalho e cada tipo de mensagem.

Para o Amazon S3 Select, as respostas podem ser mensagens dos seguintes tipos:

Mensagem de registros: pode conter um único registro, registros parciais ou vários registros. Dependendo do tamanho do resultado, uma resposta pode conter uma ou mais dessas mensagens.
Mensagem de continuação: o Amazon S3 envia periodicamente essa mensagem para manter a conexão TCP aberta. Essas mensagens aparecem aleatoriamente nas respostas. O cliente deve detectar o tipo de mensagem e processar conforme necessário.
Mensagem de andamento: o Amazon S3 envia essa mensagem periodicamente, se solicitada. Ela contém informações sobre o andamento de uma consulta que foi iniciada, mas ainda não foi concluída.
Mensagem de estatísticas: o Amazon S3 envia essa mensagem no final da solicitação. Ela contém estatísticas sobre a consulta.
Mensagem final: indica que a solicitação foi concluída e que nenhuma outra mensagem será enviada. Você não deve presumir que a solicitação foi concluída até o cliente receber uma mensagem End.
Mensagem RequestLevelError: o Amazon S3 enviará essa mensagem se a solicitação falhar por algum motivo. Ela contém o código de erro e a mensagem de erro da falha. Se o Amazon S3 enviar uma mensagem RequestLevelError, ele não enviará uma mensagem End.

As seções a seguir explicam a estrutura de cada tipo de mensagem com mais detalhes.

Para obter exemplos de código e testes de unidade que usam esse protocolo, consulte AWS C Event Stream no site do GitHub.