# Apêndice: resposta SelectObjectContent
<a name="RESTSelectObjectAppendix"></a>

## Descrição
<a name="RESTSelectObjectAppendix-description"></a>

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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/selecting-content-from-objects.html) 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-glacier-select-sql-reference.html) no *Guia do usuário do Amazon Simple Storage Service*.

## Respostas
<a name="RESTSelectObjectAppendix-responses"></a>

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

### Cabeçalhos de resposta
<a name="RESTSelectObjectAppendix-responses-response-headers"></a>

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](RESTCommonResponseHeaders.md).

### Corpo da resposta
<a name="RESTSelectObjectAppendix-responses-response-elements"></a>

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*](https://www.ietf.org/rfc/rfc1952.txt).

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.](http://docs.aws.amazon.com/pt_br/AmazonS3/latest/developerguide/images/s3select-frame-diagram-frame-overview.png)


**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.](http://docs.aws.amazon.com/pt_br/AmazonS3/latest/developerguide/images/s3select-frame-diagram-headers-overview.png)


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](ErrorResponses.md#SelectObjectContentErrorCodeList).
  + *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](https://github.com/awslabs/aws-c-event-stream) no site do GitHub.

#### Mensagem de registros
<a name="s3select-frametype-record"></a>

##### Especificação do cabeçalho
<a name="s3select-frametype-record-header"></a>

As mensagens de registros contêm três cabeçalhos, da seguinte forma:

![Um exemplo de estrutura de mensagem incluindo os cabeçalhos desse tipo de registro.](http://docs.aws.amazon.com/pt_br/AmazonS3/latest/developerguide/images/s3select-frame-diagram-record.png)


##### Especificação da carga útil
<a name="s3select-frametype-record-payload"></a>

As cargas úteis de mensagens de registros podem conter um único registro, registros parciais ou vários registros.

#### Mensagem de continuação
<a name="s3select-frametype-cont"></a>

##### Especificação do cabeçalho
<a name="s3select-frametype-cont-header"></a>

As mensagens de continuação contêm dois cabeçalhos, da seguinte forma:

![Um exemplo de estrutura de mensagem incluindo os cabeçalhos desse tipo de registro.](http://docs.aws.amazon.com/pt_br/AmazonS3/latest/developerguide/images/s3select-frame-diagram-cont.png)


##### Especificação da carga útil
<a name="s3select-frametype-cont-payload"></a>

As mensagens de continuação não têm carga útil.

#### Mensagem de andamento
<a name="s3select-frametype-progress"></a>

##### Especificação do cabeçalho
<a name="s3select-frametype-progress-header"></a>

As mensagens de andamento contêm três cabeçalhos, da seguinte forma:

![Um exemplo de estrutura de mensagem incluindo os cabeçalhos desse tipo de registro.](http://docs.aws.amazon.com/pt_br/AmazonS3/latest/developerguide/images/s3select-frame-diagram-progress.png)


##### Especificação da carga útil
<a name="s3select-frametype-progress-payload"></a>

A carga útil da mensagem de andamento é um documento XML com informações sobre o andamento de uma solicitação.
+ *BytesScanned* => Número de bytes que foram processados antes de serem descompactados (se o arquivo estiver compactado).
+ *BytesProcessed* => Número de bytes que foram processados após serem descompactados (se o arquivo estiver compactado).
+ *BytesReturned* => Número atual de bytes de dados de carga útil de registros retornados pelo Amazon S3.

Para arquivos não compactados, `BytesScanned` e `BytesProcessed` são iguais.



Exemplo:

```
<?xml version="1.0" encoding="UTF-8"?>
<Progress>
     <BytesScanned>512</BytesScanned>
     <BytesProcessed>1024</BytesProcessed>
     <BytesReturned>1024</BytesReturned>
</Progress>
```

#### Mensagem de estatísticas
<a name="s3select-frametype-stats"></a>

##### Especificação do cabeçalho
<a name="s3select-frametype-stats-header"></a>

As mensagens de estatísticas contêm três cabeçalhos, da seguinte forma:

![Um exemplo de estrutura de mensagem incluindo os cabeçalhos desse tipo de registro.](http://docs.aws.amazon.com/pt_br/AmazonS3/latest/developerguide/images/s3select-frame-diagram-stats.png)


##### Especificação da carga útil
<a name="s3select-frametype-stats-payload"></a>

A carga útil da mensagem de estatísticas é um documento XML com informações sobre as estatísticas de uma solicitação quando o processamento é concluído.
+ *BytesScanned* => Número de bytes que foram processados antes de serem descompactados (se o arquivo estiver compactado).
+ *BytesProcessed* => Número de bytes que foram processados após serem descompactados (se o arquivo estiver compactado).
+ *BytesReturned* => Número total de bytes de dados de carga útil de registros retornados pelo Amazon S3.

Para arquivos não compactados, `BytesScanned` e `BytesProcessed` são iguais.



Exemplo:

```
<?xml version="1.0" encoding="UTF-8"?>
<Stats>
     <BytesScanned>512</BytesScanned>
     <BytesProcessed>1024</BytesProcessed>
     <BytesReturned>1024</BytesReturned>
</Stats>
```

#### Mensagem final
<a name="s3select-frametype-end"></a>

##### Especificação do cabeçalho
<a name="s3select-frametype-end-header"></a>

As mensagens finais contêm dois cabeçalhos, da seguinte forma:

![Um exemplo de estrutura de mensagem incluindo os cabeçalhos desse tipo de registro.](http://docs.aws.amazon.com/pt_br/AmazonS3/latest/developerguide/images/s3select-frame-diagram-end.png)


##### Especificação da carga útil
<a name="s3select-frametype-end-payload"></a>

As mensagens finais não têm carga útil.

#### Mensagem de erro no nível da solicitação
<a name="s3select-frametype-requestlevel-error"></a>

##### Especificação do cabeçalho
<a name="s3select-frametype-requestlevel-error-header"></a>

As mensagens de erro no nível da solicitação contêm três cabeçalhos, da seguinte forma:

![Um exemplo de estrutura de mensagem incluindo os cabeçalhos desse tipo de registro.](http://docs.aws.amazon.com/pt_br/AmazonS3/latest/developerguide/images/s3select-frame-diagram-error.png)


Para obter uma lista de possíveis códigos de erro e mensagens de erro, consulte a [Lista de códigos de erro de conteúdo do objeto SELECT](ErrorResponses.md#SelectObjectContentErrorCodeList).

##### Especificação da carga útil
<a name="s3select-frametype-requestlevel-error-payload"></a>

As mensagens de erro no nível da solicitação não têm carga útil.

## Recursos relacionados
<a name="RESTSelectObjectAppendix-responses-related-resources-post-res"></a>
+  [SelectObjectContent](https://docs.aws.amazon.com/AmazonS3/latest/API/API_SelectObjectContent.html) 
+  [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) 
+  [GetBucketLifecycleConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLifecycleConfiguration.html) 
+  [PutBucketLifecycleConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketLifecycleConfiguration.html)