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 ユーザーガイド」の「オブジェクトからのコンテンツの選択」を参照してください。

Amazon S3 Select で SQL を使用する方法の詳細については、「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>

各メッセージは、prelude と data の 2 つのセクションで構成されています。prelude セクションは、1) メッセージの全バイト長と、2) すべてのヘッダーの合計バイト長で構成されています。data セクションには、1) ヘッダーと 2) ペイロードが含まれています。

各セクションは、4 バイトのビッグエンディアン整数チェックサム (CRC) で終わります。Amazon S3 Select は、CRC32 (別名 GZIP CRC32) を使用して、両方の CRC を計算します。CRC32 の詳細については、「GZIP ファイル形式仕様バージョン 4.3」を参照してください。

合計メッセージオーバーヘッド (prelude と両方のチェックサムを含む) は 16 バイトです。

注記

メッセージ内のすべての integer 値は、ネットワークバイト順、つまりビッグエンディアン順です。

次の図は、メッセージとヘッダーを構成するコンポーネントを示します。メッセージごとに複数のヘッダーがあることに注意してください。

全バイト長、ヘッダーバイト長、Prelude CRC、ヘッダー、ペイロード、およびメッセージ CRC を示すメッセージ構造の例。
注記

Amazon S3 Select の場合、ヘッダー値の型は常に 7 (type=String) です。この型では、ヘッダー値は 2 バイトのビッグエンディアン整数長、およびそのバイト長の UTF-8 文字列の 2 つのコンポーネントで構成されます。次の図は、Amazon S3 Select ヘッダーを構成するコンポーネントを示しています。

ヘッダー名のバイト長、ヘッダー名の文字列、ヘッダー値の型、値のバイト長、値文字列を示すヘッダー構造。

ペイロードのバイト長の計算 (この 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 ヘッダー:

    • 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」を参照してください。

レコードメッセージ

ヘッダー仕様

レコードメッセージには、以下のように 3 つのヘッダーが含まれています。

このレコードタイプのヘッダーを含むメッセージ構造の例。
ペイロード仕様

レコードメッセージのペイロードには、単一のレコード、部分的なレコード、または複数のレコードが含まれる場合があります。

継続メッセージ

ヘッダー仕様

継続メッセージには、以下のように 2 つのヘッダーが含まれています。

このレコードタイプのヘッダーを含むメッセージ構造の例。
ペイロード仕様

継続メッセージにはペイロードがありません。

進行状況メッセージ

ヘッダー仕様

進行状況メッセージには、以下のように 3 つのヘッダーが含まれています。

このレコードタイプのヘッダーを含むメッセージ構造の例。
ペイロード仕様

進行状況メッセージのペイロードは、リクエストの進行状況に関する情報を含む 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>

統計情報メッセージ

ヘッダー仕様

統計情報メッセージには、以下のように 3 つのヘッダーが含まれています。

このレコードタイプのヘッダーを含むメッセージ構造の例。
ペイロード仕様

統計情報メッセージのペイロードは、処理が完了した時点でのリクエストの統計に関する情報を含む 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>

終了メッセージ

ヘッダー仕様

終了メッセージには、以下のように 2 つのヘッダーが含まれています。

このレコードタイプのヘッダーを含むメッセージ構造の例。
ペイロード仕様

終了メッセージにはペイロードがありません。

リクエストレベルのエラーメッセージ

ヘッダー仕様

リクエストレベルのエラーメッセージには、以下のように 3 つのヘッダーが含まれています。

このレコードタイプのヘッダーを含むメッセージ構造の例。

考えられるエラーコードとエラーメッセージのリストについては、「SELECT Object Content エラーコードのリスト」を参照してください。

ペイロード仕様

リクエストレベルのエラーメッセージにはペイロードがありません。

関連リソース