View a markdown version of this page

附录：SelectObjectContent 响应 - Amazon Simple Storage Service
说明响应相关资源

附录：SelectObjectContent 响应

说明

Amazon S3 Select 操作基于简单结构化查询语言（SQL）语句筛选 Amazon S3 对象的内容。鉴于此操作的响应大小是未知的，Amazon S3 Select 将响应作为一系列消息进行流式传输，并在响应中包含一个将 chunked 作为其值的 Transfer-Encoding 标头。

有关 Amazon S3 Select 的更多信息，请参阅《Amazon Simple Storage Service 用户指南》中的从对象中选择内容。

有关将 SQL 与 Amazon S3 Select 结合使用的更多信息，请参阅《Amazon Simple Storage Service 用户指南》中的 Amazon S3 Select 和 Amazon Glacier Select 的 SQL 参考。

响应

成功的 Amazon S3 Select 操作会返回 200 OK 状态代码。

响应标头

此操作的实施仅使用大多数响应通用的响应标头。有关更多信息，请参阅通用响应标头。

响应正文

鉴于 Amazon S3 Select 的响应大小是未知的，Amazon S3 将响应作为一系列消息进行流式传输，并在响应中包含一个将 chunked 作为其值的 Transfer-Encoding 标头。以下示例显示顶层的响应格式：

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

每个消息都包含两部分：前导信息和数据。前导信息部分包含：1) 消息的总字节长度，2) 所有标头的组合字节长度。数据部分包含：1) 标头，2) 有效载荷。

每个部分均以 4 字节大端整数校验和（CRC）结尾。Amazon S3 Select 使用 CRC32（通常称为 GZIP CRC32）来计算这两个 CRC。有关 CRC32 的更多信息，请参阅 GZIP 文件格式规范版本 4.3。

总消息开销（包括前导信息和两个校验和）为 16 字节。

注意

消息中的所有 integer 值均按网络字节顺序或大端序排列。

下图显示了构成消息和标头的组件。请注意，每个消息有多个标头。

示例消息结构，显示总字节长度、标头字节长度、前导信息 CRC、标头、有效载荷和消息 CRC。
注意

对于 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 标头：

    • 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。

记录消息

标头规范

记录消息包含三个标头，如下所示：

包含此记录类型的标头的消息结构示例。
有效载荷规范

记录消息有效载荷可以包含单条记录、不完整的记录或多条记录。

继续消息

标头规范

继续消息包含两个标头，如下所示：

包含此记录类型的标头的消息结构示例。
有效载荷规范

继续消息没有有效载荷。

进度消息

标头规范

进度消息包含三个标头，如下所示：

包含此记录类型的标头的消息结构示例。
有效载荷规范

进度消息有效载荷是一个 XML 文档，其中包含有关请求进度的信息。

  • BytesScanned => 解压缩前已处理的字节数（如果文件已压缩）。

  • BytesProcessed => 解压缩后已处理的字节数（如果文件已压缩）。

  • BytesReturned => Amazon S3 返回的记录有效载荷数据的当前字节数。

对于未压缩的文件，BytesScanned 和 BytesProcessed 相等。

示例：

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

统计数据消息

标头规范

统计数据消息包含三个标头，如下所示：

包含此记录类型的标头的消息结构示例。
有效载荷规范

统计数据消息有效载荷是一个 XML 文档，其中包含处理完成时请求的统计数据。

  • BytesScanned => 解压缩前已处理的字节数（如果文件已压缩）。

  • BytesProcessed => 解压缩后已处理的字节数（如果文件已压缩）。

  • BytesReturned => Amazon S3 返回的记录有效载荷数据的总字节数。

对于未压缩的文件，BytesScanned 和 BytesProcessed 相等。

示例：

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

结束消息

标头规范

结束消息包含两个标头，如下所示：

包含此记录类型的标头的消息结构示例。
有效载荷规范

结束消息没有有效载荷。

请求级错误消息

标头规范

请求级错误消息包含三个标头，如下所示：

包含此记录类型的标头的消息结构示例。

有关可能的错误代码和错误消息的列表，请参阅 SELECT 对象内容错误代码列表。

有效载荷规范

请求级错误消息没有有效载荷。

相关资源