附錄：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>

每則訊息包含兩個部分：序言和資料。前導區段包含 1) 訊息的總位元組長度，以及 2) 所有標頭的合併位元組長度。資料區段包含 1) 標頭，以及 2) 承載。

每個區段以 4 位元組大端整數檢查總和 (CRC) 結尾。Amazon S3 Select 使用 CRC32 （通常稱為 GZIP CRC32) 來計算這兩個 CRCs。如需 CRC32 的詳細資訊，請參閱 GZIP 檔案格式規格 4.3 版。

包括前導和兩個檢查總和在內的總訊息負荷為 16 個位元組。

注意

訊息內的所有integer值都採用網路位元組順序或大端順序。

下圖顯示構成訊息和標題的元件。請注意，每則訊息有多個標頭。

注意

對於 Amazon S3 Select，標頭值類型一律為 7 (type=String)。對於此類型，標頭值包含兩個元件：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

每則訊息都包含下列元件：

• Prelude：一律固定大小為 8 個位元組 （兩個欄位各 4 個位元組）：

  • 前四個位元組：總位元組長度：整個訊息的大端整數位元組長度 （包括 4 位元組總長度欄位本身）。

  • 第二四個位元組：標頭位元組長度：訊息標頭部分的大端整數位元組長度 （標頭長度欄位本身除外）。

• Prelude CRC：訊息的 prelude 部分 (CRC 本身除外） 的 4 位元組大端整數檢查總和 (CRC)。前置詞具有與訊息 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 物件內容錯誤代碼的清單區段中資料表的錯誤碼。

  • 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，回應可以是下列類型的訊息：

• 記錄訊息：可包含單一記錄、部分記錄或多個記錄。根據結果的大小，回應可以包含一或多個這些訊息。

• 持續訊息：Amazon S3 會定期傳送此訊息，以保持 TCP 連線開啟。這些訊息會隨機出現在回應中。用戶端必須偵測訊息類型並相應地進行處理。

• 進度訊息：如果請求，Amazon S3 會定期傳送此訊息。它包含已開始但尚未完成之查詢進度的相關資訊。

• 統計資料訊息：Amazon S3 會在請求結束時傳送此訊息。它包含有關查詢的統計資料。

• 結束訊息：表示請求已完成，而且不會再傳送任何訊息。在用戶端收到End訊息之前，您不應該假設請求已完成。

• RequestLevelError 訊息：如果請求因任何原因失敗，Amazon S3 會傳送此訊息。它包含失敗的錯誤代碼和錯誤訊息。如果 Amazon S3 傳送訊息RequestLevelError，則不會傳送訊息End。

以下各節會更詳細地說明每個訊息類型的結構。

如需使用此通訊協定的範例程式碼和單元測試，請參閱 GitHub 網站上的 AWS C 事件串流。

記錄訊息

標頭規格

記錄訊息包含三個標頭，如下所示：

承載規格

記錄訊息承載可以包含單一記錄、部分記錄或多個記錄。

持續訊息

標頭規格

持續訊息包含兩個標頭，如下所示：

承載規格

持續訊息沒有承載。

進度訊息

標頭規格

進度訊息包含三個標頭，如下所示：

承載規格

進度訊息承載是 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>

統計資料訊息

標頭規格

統計資料訊息包含三個標頭，如下所示：

承載規格

Stats 訊息承載是 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 物件內容錯誤代碼的清單。

承載規格

請求層級錯誤訊息沒有承載。

相關資源

• SelectObjectContent

• GetObject

• GetBucketLifecycleConfiguration

• PutBucketLifecycleConfiguration