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>

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

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

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

注意

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

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

顯示總位元組長度、標頭位元組長度、預先排除 crc、標頭、承載和訊息 crc 的訊息結構範例。
注意

對於 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 標頭：

    • 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 物件內容錯誤代碼的清單。

承載規格

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

相關資源