# 付録: 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)」を参照してください。 Amazon S3 Select で SQL を使用する方法の詳細については、「*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` ヘッダーを含めます。次の例は、トップレベルのレスポンス形式を示しています。 ``` ...... ``` 各メッセージは、prelude と data の 2 つのセクションで構成されています。prelude セクションは、1) メッセージの全バイト長と、2) すべてのヘッダーの合計バイト長で構成されています。data セクションには、1) ヘッダーと 2) ペイロードが含まれています。 各セクションは、4 バイトのビッグエンディアン整数チェックサム (CRC) で終わります。Amazon S3 Select は、CRC32 (別名 GZIP CRC32) を使用して、両方の CRC を計算します。CRC32 の詳細については、「[*GZIP ファイル形式仕様バージョン 4.3*](https://www.ietf.org/rfc/rfc1952.txt)」を参照してください。 合計メッセージオーバーヘッド (prelude と両方のチェックサムを含む) は 16 バイトです。 **注記** メッセージ内のすべての `integer` 値は、ネットワークバイト順、つまりビッグエンディアン順です。 次の図は、メッセージとヘッダーを構成するコンポーネントを示します。メッセージごとに複数のヘッダーがあることに注意してください。 ![全バイト長、ヘッダーバイト長、Prelude CRC、ヘッダー、ペイロード、およびメッセージ CRC を示すメッセージ構造の例。](http://docs.aws.amazon.com/ja_jp/AmazonS3/latest/developerguide/images/s3select-frame-diagram-frame-overview.png) **注記** Amazon S3 Select の場合、ヘッダー値の型は常に 7 (type=String) です。この型では、ヘッダー値は 2 バイトのビッグエンディアン整数長、およびそのバイト長の UTF-8 文字列の 2 つのコンポーネントで構成されます。次の図は、Amazon S3 Select ヘッダーを構成するコンポーネントを示しています。 ![ヘッダー名のバイト長、ヘッダー名の文字列、ヘッダー値の型、値のバイト長、値文字列を示すヘッダー構造。](http://docs.aws.amazon.com/ja_jp/AmazonS3/latest/developerguide/images/s3select-frame-diagram-headers-overview.png) ペイロードのバイト長の計算 (この 2 つの計算は同等です): + 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 各メッセージには、以下のコンポーネントが含まれます。 + **Prelude:** 常に 8 バイト の固定サイズ (4 バイト × 2 フィールド)。 + *最初の 4 バイト*: 全バイト長: メッセージ全体のビッグエンディアン整数バイト長 (4 バイトの合計長フィールド自体を含む)。 + *次の 4 バイト*: ヘッダーバイト長: メッセージのヘッダー部分のビッグエンディアン整数バイト長 (ヘッダー長フィールド自体を除く)。 + **Prelude CRC:** メッセージの prelude 部分 (CRC 自体を除く) の 4 バイトのビッグエンディアン整数チェックサム (CRC)。異常なバッファリング動作を引き起こすことなく、破損したバイト長の情報を即時に検出できるように、prelude にはメッセージ CRC とは別の CRC があります (下記を参照)。 + **ヘッダー**: メッセージの種類、ペイロードの形式など、メッセージに注釈を付けるメタデータのセット。メッセージには複数のヘッダーを含めることができるため、メッセージのこの部分はメッセージタイプに応じて異なるバイト長を持つことができます。ヘッダーはキーと値のペアで、キーと値はどちらも UTF-8 文字列です。ヘッダーは、メッセージのヘッダー部分に任意の順序で表示することができ、同じタイプのヘッダーは一度だけしか表示できません。 Amazon S3 Select の場合、以下はメッセージタイプに応じたヘッダー名と有効な値のセットのリストです。 + *MessageType ヘッダー*: + HeaderName => ":message-type" + 有効な HeaderValues => "error"、"event" + *EventType ヘッダー*: + HeaderName => ":event-type" + 有効な HeaderValues => "Records"、"Cont"、"Progress"、"Stats"、"End" + *ErrorCode ヘッダー*: + HeaderName => ":error-code" + 有効な HeaderValues => [SELECT Object Content エラーコードのリスト](ErrorResponses.md#SelectObjectContentErrorCodeList) セクションのテーブルからのエラーコード。 + *ErrorMessage ヘッダー*: + HeaderName => ":error-message" + 有効な HeaderValues => リクエストレベルのエラーの診断に役立つ、サービスによって返されるエラーメッセージ。 + **ペイロード**: 何でも構いません。 + **メッセージ 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 の場合、レスポンスは次のタイプのメッセージになります。 + **レコードメッセージ**: 単一のレコード、部分的なレコード、または複数のレコードが含まれる場合があります。結果のサイズに応じて、レスポンスにはこれらのメッセージが 1 つ以上含まれる場合があります。 + **継続メッセージ**: 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)」を参照してください。 #### レコードメッセージ ##### ヘッダー仕様 レコードメッセージには、以下のように 3 つのヘッダーが含まれています。 ![このレコードタイプのヘッダーを含むメッセージ構造の例。](http://docs.aws.amazon.com/ja_jp/AmazonS3/latest/developerguide/images/s3select-frame-diagram-record.png) ##### ペイロード仕様 レコードメッセージのペイロードには、単一のレコード、部分的なレコード、または複数のレコードが含まれる場合があります。 #### 継続メッセージ ##### ヘッダー仕様 継続メッセージには、以下のように 2 つのヘッダーが含まれています。 ![このレコードタイプのヘッダーを含むメッセージ構造の例。](http://docs.aws.amazon.com/ja_jp/AmazonS3/latest/developerguide/images/s3select-frame-diagram-cont.png) ##### ペイロード仕様 継続メッセージにはペイロードがありません。 #### 進行状況メッセージ ##### ヘッダー仕様 進行状況メッセージには、以下のように 3 つのヘッダーが含まれています。 ![このレコードタイプのヘッダーを含むメッセージ構造の例。](http://docs.aws.amazon.com/ja_jp/AmazonS3/latest/developerguide/images/s3select-frame-diagram-progress.png) ##### ペイロード仕様 進行状況メッセージのペイロードは、リクエストの進行状況に関する情報を含む XML ドキュメントです。 + *BytesScanned* => 圧縮解除前に処理されたバイト数 (ファイルが圧縮されている場合)。 + *BytesProcessed* => 圧縮解除後に処理されたバイト数 (ファイルが圧縮されている場合)。 + *BytesReturned* => Amazon S3 によって返されるレコードペイロードデータの現在のバイト数。 非圧縮ファイルの場合、`BytesScanned` と `BytesProcessed` は等しくなります。 例: ``` 512 1024 1024 ``` #### 統計情報メッセージ ##### ヘッダー仕様 統計情報メッセージには、以下のように 3 つのヘッダーが含まれています。 ![このレコードタイプのヘッダーを含むメッセージ構造の例。](http://docs.aws.amazon.com/ja_jp/AmazonS3/latest/developerguide/images/s3select-frame-diagram-stats.png) ##### ペイロード仕様 統計情報メッセージのペイロードは、処理が完了した時点でのリクエストの統計に関する情報を含む XML ドキュメントです。 + *BytesScanned* => 圧縮解除前に処理されたバイト数 (ファイルが圧縮されている場合)。 + *BytesProcessed* => 圧縮解除後に処理されたバイト数 (ファイルが圧縮されている場合)。 + *BytesReturned* => Amazon S3 によって返されるレコードペイロードデータの合計バイト数。 非圧縮ファイルの場合、`BytesScanned` と `BytesProcessed` は等しくなります。 例: ``` 512 1024 1024 ``` #### 終了メッセージ ##### ヘッダー仕様 終了メッセージには、以下のように 2 つのヘッダーが含まれています。 ![このレコードタイプのヘッダーを含むメッセージ構造の例。](http://docs.aws.amazon.com/ja_jp/AmazonS3/latest/developerguide/images/s3select-frame-diagram-end.png) ##### ペイロード仕様 終了メッセージにはペイロードがありません。 #### リクエストレベルのエラーメッセージ ##### ヘッダー仕様 リクエストレベルのエラーメッセージには、以下のように 3 つのヘッダーが含まれています。 ![このレコードタイプのヘッダーを含むメッセージ構造の例。](http://docs.aws.amazon.com/ja_jp/AmazonS3/latest/developerguide/images/s3select-frame-diagram-error.png) 考えられるエラーコードとエラーメッセージのリストについては、「[SELECT Object Content エラーコードのリスト](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)