# 附录：SelectObjectContent 响应
## 说明
Amazon S3 Select 操作基于简单结构化查询语言（SQL）语句筛选 Amazon S3 对象的内容。鉴于此操作的响应大小是未知的，Amazon S3 Select 将响应作为一系列消息进行流式传输，并在响应中包含一个将 **chunked** 作为其值的 `Transfer-Encoding` 标头。
有关 Amazon S3 Select 的更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[从对象中选择内容](https://docs.aws.amazon.com/AmazonS3/latest/userguide/selecting-content-from-objects.html)。
有关将 SQL 与 Amazon S3 Select 结合使用的更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的 [Amazon S3 Select 和 Amazon Glacier Select 的 SQL 参考](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-glacier-select-sql-reference.html)。
## 响应
成功的 Amazon S3 Select 操作会返回 `200 OK` 状态代码。
### 响应标头
此操作的实施仅使用大多数响应通用的响应标头。有关更多信息，请参阅[通用响应标头](RESTCommonResponseHeaders.md)。
### 响应正文
鉴于 Amazon S3 Select 的响应大小是未知的，Amazon S3 将响应作为一系列消息进行流式传输，并在响应中包含一个将 **chunked** 作为其值的 `Transfer-Encoding` 标头。以下示例显示顶层的响应格式：
```
......
```
每个消息都包含两部分：前导信息和数据。前导信息部分包含：1) 消息的总字节长度，2) 所有标头的组合字节长度。数据部分包含：1) 标头，2) 有效载荷。
每个部分均以 4 字节大端整数校验和（CRC）结尾。Amazon S3 Select 使用 CRC32（通常称为 GZIP CRC32）来计算这两个 CRC。有关 CRC32 的更多信息，请参阅 [*GZIP 文件格式规范版本 4.3*](https://www.ietf.org/rfc/rfc1952.txt)。
总消息开销（包括前导信息和两个校验和）为 16 字节。
**注意**
消息中的所有 `integer` 值均按网络字节顺序或大端序排列。
下图显示了构成消息和标头的组件。请注意，每个消息有多个标头。
**注意**
对于 Amazon S3 Select，标头值类型始终为 7（类型=字符串）。对于这种类型，标头值由两部分组成：一个 2 字节的大端整数长度，以及一个具有该字节长度的 UTF-8 字符串。下图显示了构成 Amazon S3 Select 标头的组件。
有效载荷字节长度计算（这两种计算是等效的）：
+ 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
每个消息都包含以下组件：
+ **前导信息：**大小始终固定为 8 字节（两个各为 4 字节的字段）。
+ *前四个字节*：总字节长度：整个消息的大端整数字节长度（包括 4 字节总长度字段本身）。
+ *第二个四字节*：标头字节长度：消息标头部分的大端整数字节长度（不包括标头长度字段本身）。
+ **前导信息 CRC**：消息前导信息部分的 4 字节大端整数校验和（CRC）（不包括 CRC 本身）。前导信息具有不同于消息 CRC 的单独 CRC（请参阅下文），以确保可以立即检测到损坏的字节长度信息，而不会导致无法控制的缓冲行为。
+ **标头**：一组为消息添加注释的元数据，如消息类型、有效载荷格式等。消息可以有多个标头，因此消息的这一部分可能具有不同的字节长度，具体取决于消息类型。标头是键-值对，其中键和值都是 UTF-8 字符串。标头可按任何顺序出现在消息的标头部分内，并且任何给定的标头类型只能出现一次。
对于 Amazon S3 Select，以下是标头名称的列表和有效值的集合，具体取决于消息类型。
+ *MessageType 标头*：
+ HeaderName => ":message-type"
+ 有效的 HeaderValue => "error"、"event"
+ *EventType 标头*：
+ HeaderName => ":event-type"
+ 有效的 HeaderValue => "Records"、"Cont"、"Progress"、"Stats"、"End"
+ *ErrorCode 标头*：
+ HeaderName => ":error-code"
+ 有效的 HeaderValue => [SELECT 对象内容错误代码列表](ErrorResponses.md#SelectObjectContentErrorCodeList)部分的表中的错误代码。
+ *ErrorMessage 标头*：
+ HeaderName => ":error-message"
+ 有效的 HeaderValue => 服务返回的错误消息，有助于诊断请求级错误。
+ **有效载荷**：可以是任何内容。
+ **消息 CRC**：从消息开头到校验和开头的 4 字节大端整数校验和（CRC）（即消息中除消息 CRC 本身之外的所有内容）。
每个标头都包含以下组件。每个消息可能有多个标头。
+ **标头名称字节长度**：标头名称的字节长度。
+ **标头名称**：标头的名称，指示标头类型。有效值：":message-type" ":event-type" ":error-code" ":error-message"
+ **标头值类型**：指示标头值类型的枚举。对于 Amazon S3 Select，此值始终为 7。
+ **值字符串字节长度**：（对于 Amazon S3 Select）标头值字符串的字节长度。
+ **标头值字符串**：（对于 Amazon S3 Select）标头字符串的值。此字段的有效值因标头的类型而异。有关每种标头类型和消息类型的有效值，请参阅以下各节。
对于 Amazon S3 Select，响应可以是以下类型的消息：
+ **记录消息**：可以包含单条记录、不完整的记录或多条记录。根据结果的大小，响应可能包含一条或多条这样的消息。
+ **继续消息**：Amazon S3 会定期发送此消息，以使 TCP 连接保持打开状态。这些消息随机出现在响应中。客户端必须检测消息类型并相应地进行处理。
+ **进度消息**：如果收到请求，Amazon S3 会定期发送此消息。它包含有关已开始但尚未完成的查询的进度信息。
+ **统计数据消息**：Amazon S3 在请求结束时发送此消息。它包含有关查询的统计数据。
+ **结束消息**：表示请求已完成，将不再发送消息。在客户端收到 `End` 消息之前，您不应认为请求已完成。
+ **RequestLevelError 消息**：如果请求因任何原因而失败，Amazon S3 会发送此消息。它包含失败的错误代码和错误消息。如果 Amazon S3 发送了 `RequestLevelError` 消息，它就不会发送 `End` 消息。
以下各节更详细地介绍了每种消息类型的结构。
有关使用此协议的示例代码和单元测试，请参阅 GitHub 网站上的 [AWS C Event Stream](https://github.com/awslabs/aws-c-event-stream)。
#### 记录消息
##### 标头规范
记录消息包含三个标头，如下所示：
##### 有效载荷规范
记录消息有效载荷可以包含单条记录、不完整的记录或多条记录。
#### 继续消息
##### 标头规范
继续消息包含两个标头，如下所示：
##### 有效载荷规范
继续消息没有有效载荷。
#### 进度消息
##### 标头规范
进度消息包含三个标头，如下所示：
##### 有效载荷规范
进度消息有效载荷是一个 XML 文档，其中包含有关请求进度的信息。
+ *BytesScanned* => 解压缩前已处理的字节数（如果文件已压缩）。
+ *BytesProcessed* => 解压缩后已处理的字节数（如果文件已压缩）。
+ *BytesReturned* => Amazon S3 返回的记录有效载荷数据的当前字节数。
对于未压缩的文件，`BytesScanned` 和 `BytesProcessed` 相等。
示例：
```
```
#### 统计数据消息
##### 标头规范
统计数据消息包含三个标头，如下所示：
##### 有效载荷规范
统计数据消息有效载荷是一个 XML 文档，其中包含处理完成时请求的统计数据。
+ *BytesScanned* => 解压缩前已处理的字节数（如果文件已压缩）。
+ *BytesProcessed* => 解压缩后已处理的字节数（如果文件已压缩）。
+ *BytesReturned* => Amazon S3 返回的记录有效载荷数据的总字节数。
对于未压缩的文件，`BytesScanned` 和 `BytesProcessed` 相等。
示例：
```
512
1024
1024
```
#### 结束消息
##### 标头规范
结束消息包含两个标头，如下所示：
##### 有效载荷规范
结束消息没有有效载荷。
#### 请求级错误消息
##### 标头规范
请求级错误消息包含三个标头，如下所示：
有关可能的错误代码和错误消息的列表，请参阅 [SELECT 对象内容错误代码列表](ErrorResponses.md#SelectObjectContentErrorCodeList)。
##### 有效载荷规范
请求级错误消息没有有效载荷。
## 相关资源
+ [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)