「取得任務輸出」 (GET 輸出) - Amazon S3 Glacier
描述請求回應範例相關章節

此頁面僅適用於使用文件庫的 S3 Glacier 服務的現有客戶，並且是 2012 年RESTAPI起的原始客戶。

如果您正在尋找存檔儲存解決方案，我們建議您使用 Amazon S3 中的 S3 Glacier 儲存類別、S3 冰川即時擷取、S3 冰川彈性擷取和 S3 Glacier Deep Archive。若要進一步了解這些儲存選項，請參閱 Amazon S3 使用者指南中的 S3 Glacier 儲存類別和使用 S3 Glacier 儲存類別的長期資料儲存。這些儲存類別使用 Amazon S3API，可在所有區域使用，並且可以在 Amazon S3 主控台中管理。它們提供了諸如存儲成本分析，存儲鏡頭，高級可選加密功能等功能。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

「取得任務輸出」 (GET 輸出)

描述

此操作可下載使用 啟動 Job (POST工作) 啟動的任務的輸出。根據您在啟動任務時所指定的任務類型，輸出將是存檔或文件庫清查的內容。

您可以透過指定位元組範圍來下載所有任務輸出或下載部分輸出。對於封存和庫存擷取任務，應根據取得任務輸出回應中的標題中傳回的大小來驗證下載的大小。

對於封存擷取任務，您還應該驗證大小是否符合預期。如果您下載部分輸出，則預期的大小取決於您指定的位元組範圍。例如，如果您指定 bytes=0-1048575 範圍，則應驗證下載大小為 1,048,576 位元組。如果您下載整個封存，則預期大小是您上傳至 Amazon S3 Glacier (S3 Glacier) 時的封存大小。預期大小也會從取得任務輸出回應的標題中傳回。

對於封存擷取任務，根據指定的位元組範圍而定，S3 Glacier 會傳回資料部分的檢查總和。為確保下載的部分是正確的資料，請計算用戶端上的檢查總和，驗證值是否符合，並驗證大小是否符合您所期望的。

S3 Glacier 完成任務後，任務 ID 至少在 24 小時內不會過期。也就是說，您可以在 S3 Glacier 完成任務後的 24 小時內下載任務輸出。

請求

語法

若要擷取任務輸出，請將 HTTP GET 請求傳送到特定任務的 output 的 URI。

GET /AccountId/vaults/VaultName/jobs/JobID/output HTTP/1.1
Host: glacier.Region.amazonaws.com
Date: Date
Authorization: SignatureValue
Range: ByteRangeToRetrieve
x-amz-glacier-version: 2012-06-01

注意

此 AccountId 值是擁有該文件庫之帳戶的 AWS 帳戶 ID。您可以指定 AWS 帳戶 ID 或選擇性使用 '-' (連字號)，在這種情況下，Amazon S3 會使用與用於簽署請求之憑證關聯的 AWS 帳戶 ID。如果您使用帳號 ID，請勿在 ID 中包含任何連字號 ('-')。

請求參數

此操作不使用請求參數。

請求標頭

除了所有操作通用的請求標頭之外，此操作還會使用下列請求標頭。如需常見請求標頭的資訊，請參閱常見請求標題。

名稱 描述 必要
Range

從輸出中擷取的位元組範圍。例如，如果想要下載第一個 1,048,576 位元組，請將範圍指定為 bytes=0-1048575。如需詳細資訊，請前往範圍標頭欄位定義。範圍與啟動任務請求中指定的任何範圍有關。在預設情況下，這個操作下載整個輸出。

如果任務輸出很大，則您可以使用 Range 請求標頭來擷取輸出的一部分。這可讓您可以以較小的位元組區塊下載整個輸出。例如，假設您有 1 GB 的任務輸出要下載，並且您決定一次下載 128 MB 的資料區塊，總共有八個「取得任務輸出」請求。您將使用以下程序下載任務輸出：

  1. 透過使用 Range 標頭指定適當的位元組範圍，下載 128 MB 的輸出。驗證是否收到了所有 128 MB 的資料。

  2. 與資料一起，回應將包括承載的檢查總和。您計算用戶端上承載的檢查總和，並將其與回應中收到的檢查總和進行比較，以確保接收到所有預期資料。

  3. 對所有八個 128 MB 輸出資料區塊重複步驟 1 和 2，每次指定適當的位元組範圍。

  4. 下載任務輸出的所有部分後，您有 8 個檢查總和值的清單。計算這些值的樹狀雜湊以尋找整個輸出的檢查總和。使用 描述任務 (GET JobID) 操作，取得為您提供輸出的任務的任務資訊。此回應包含存放在 S3 Glacier 中整個封存的檢查總和。您可以將此值與計算的檢查總和進行比較，以確保下載的整個存檔封存內容沒有錯誤。

類型：字串

預設：無

限制條件：無

 否

請求主體

此操作沒有請求內文。

回應

語法

對於傳回所有任務資料的擷取請求，任務輸出回應將傳回 200 OK 回應程式碼。當請求部分內容時，例如，如果您在請求中指定了 Range 標頭，，則會傳回回應的程式碼 206 Partial Content。

HTTP/1.1 200 OK
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: ContentType
Content-Length: Length
x-amz-sha256-tree-hash: ChecksumComputedByAmazonGlacier

[Body containing job output.]

回應標頭

標頭 描述
Content-Range

S3 Glacier 傳回的位元組範圍。如果只下載部分輸出，則回應將提供 S3 Glacier 傳回的位元組範圍。

例如，bytes 0-1048575/8388608 從 8 MB中傳回第一個 1 MB。

如需有關 Content-Range 標頭的詳細資訊，請參閱內容 - 範圍標頭欄位定義。

類型：字串
Content-Type

內容類型取決於任務輸出是存檔還是文件庫清查。

  • 對於封存資料，內容類型為 application/octet-stream。

  • 對於文件庫清查，如果您在啟動任務時請求了 CSV 格式，則內容類型為 text/csv。否則，在預設情況下，文件庫清查做為 JSON 傳回，並且內容類型為 application/json。

類型：字串
x-amz-sha256-tree-hash​

在回應中資料的檢查總和。只有在擷取封存擷取任務的輸出時才傳回此標頭。此外, 當啟動任務請求中請求的擷取資料範圍與樹狀雜湊符合，並且在「取得任務輸出」中下載的範圍也與樹狀雜湊符合時，會出現此標頭。如需有關樹狀雜湊符合範圍的詳細資訊，請參閱 下載資料時接收檢查總和。

例如，如果在啟動任務請求中指定了要擷取的樹狀雜湊符合範圍 (包括整個封存)，則在下列情況下，您將收到下載資料的檢查總和：

  • 您可以取得擷取資料的整個範圍。

  • 您請求位元組範圍的擷取資料，其大小為百萬位元組 (1024 KB) 乘以 2 的冪，並且以請求範圍的大小的倍數開始和結束。例如，如果您有 3.1 MB 的擷取資料，並且您指定了一個從 1 MB 開始到 2 MB 結束的範圍，則 x-amz-sha256-tree-hash 將做為回應標頭傳回。

  • 您請求傳回擷取資料的範圍，該範圍到達傳回資料的結尾，而該範圍的開始是擷取範圍大小的倍數，四捨五入到下一個為 2 的冪位，但不小於 1 百萬位元組 (1024 KB)。例如，如果您有 3.1 MB 的擷取資料，並且您指定了一個從 2 MB 開始，並以 3.1 MB 結束 (資料的結尾) 的範圍，則 x-amz-sha256-tree-hash 將做為回應標頭傳回。

類型：字串

回應內文

S3 Glacier 在回應內文中傳回任務輸出。根據任務類型，輸出可以是存檔內容或文件庫清查。在文件庫清查情況下，根據預設，會以下列 JSON 內文傳回清查清單。

{
 "VaultARN": String,
 "InventoryDate": String,
 "ArchiveList": [
      {"ArchiveId": String,
       "ArchiveDescription": String,
       "CreationDate": String,
       "Size": Number,
       "SHA256TreeHash": String
      },
      ...
    ]
}

如果您在啟動文件庫清查任務時請求以逗號分隔值 (CSV) 輸出格式，則在內文中以 CSV 格式傳回文件庫清查。CSV 格式有五個欄「ArchiveId」、」 ArchiveDescription」、」 CreationDate」、「Size」和「SHA256TreeHash」，其定義與相應的 JSON 欄位相同。

注意

在傳回的 CSV 格式中，欄位可能會以整個欄位用雙引號括起來。包含逗號或雙引號的欄位一律以雙引號括起來。例如，my archive description,1 做為 "my archive description,1" 傳回。在傳回的雙引號所括起的欄位中的雙引號字元，是藉由在其前面加上反斜線字元逸出。例如，my archive description,1"2 做為 "my archive description,1\"2" 傳回，my archive description,1\"2 做為 "my archive description,1\\"2" 傳回。反斜線字元不會逸出。

JSON 回應內文包含以下 JSON 欄位。

ArchiveDescription

封存的說明。

類型：字串

封存

封存的 ID。

類型：字串

ArchiveList

封存中繼資料的陣列。陣列中的每個物件表示文件庫中包含的一個存檔的中繼資料。

類型：陣列

CreationDate

建立封存的 UTC 日期和時間。

類型：ISO 8601 日期格式的字串表示法，例如，2013-03-20T17:03:43.221Z。

InventoryDate

在文件庫變更後完成的文件庫的最後清查的 UTC 日期和時間。儘管 S3 Glacier 每天準備一次文件庫庫存，但只有在自上次清點以來已對文件庫進行封存新增或刪除時，才更新清點日期。

類型：ISO 8601 日期格式的字串表示法，例如，2013-03-20T17:03:43.221Z。

SHA256TreeHash

封存的樹狀雜湊。

類型：字串

大小

封存的大小 (位元組)。

類型：數字

VaultARN

請求封存擷取的 Amazon Resource Name (ARN) 資源。

類型：字串

錯誤

如需 Amazon S3 Glacier 例外和錯誤訊息的詳細資訊，請參閱錯誤回應。

範例

以下範例顯示對擷取封存的任務的請求。

範例 1：下載輸出

本範例擷取 S3 Glacier 為回應啟動封存擷取任務請求而準備的資料。

範例請求 

GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/output HTTP/1.1
Host: glacier.us-west-2.amazonaws.com
x-amz-Date: 20170210T120000Z
x-amz-glacier-version: 2012-06-01
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2

回應範例

以下是封存擷取作業的範例回應。請注意，Content-Type 標頭是 application/octet-stream，並且 x-amz-sha256-tree-hash 標頭包含在回應中，這表示傳回所有任務資料。

HTTP/1.1 200 OK
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
x-amz-sha256-tree-hash: beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60
Date: Wed, 10 Feb 2017 12:00:00 GMT
Content-Type: application/octet-stream
Content-Length: 1048576

[Archive data.]

以下是庫存擷取任務的範例回應。請注意，Content-Type 標頭是 application/json。另請注意，回應不包含 x-amz-sha256-tree-hash 標頭。

HTTP/1.1 200 OK
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Wed, 10 Feb 2017 12:00:00 GMT
Content-Type: application/json
Content-Length: 906

{
 "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault",
 "InventoryDate": "2011-12-12T14:19:01Z",
 "ArchiveList": [
   {
     "ArchiveId": "DMTmICA2n5Tdqq5BV2z7og-A20xnpAPKt3UXwWxdWsn_D6auTUrW6kwy5Qyj9xd1MCE1mBYvMQ63LWaT8yTMzMaCxB_9VBWrW4Jw4zsvg5kehAPDVKcppUD1X7b24JukOr4mMAq-oA",
     "ArchiveDescription": "my archive1",
     "CreationDate": "2012-05-15T17:19:46.700Z",
     "Size": 2140123,
     "SHA256TreeHash": "6b9d4cf8697bd3af6aa1b590a0b27b337da5b18988dbcc619a3e608a554a1e62"
   },
   {
     "ArchiveId": "2lHzwhKhgF2JHyvCS-ZRuF08IQLuyB4265Hs3AXj9MoAIhz7tbXAvcFeHusgU_hViO1WeCBe0N5lsYYHRyZ7rrmRkNRuYrXUs_sjl2K8ume_7mKO_0i7C-uHE1oHqaW9d37pabXrSA",
     "ArchiveDescription": "my archive2",
     "CreationDate": "2012-05-15T17:21:39.339Z",
     "Size": 2140123,
     "SHA256TreeHash": "7f2fe580edb35154041fa3d4b41dd6d3adaef0c85d2ff6309f1d4b520eeecda3"
   }
  ]
}

範例 2：僅下載部分輸出

本範例僅擷取 S3 Glacier 為回應啟動封存擷取任務請求而準備的封存部分。請求使用可選的 Range 標頭只擷取前 1,024 位元組。

範例請求 

GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/output HTTP/1.1
Host: glacier.us-west-2.amazonaws.com
x-amz-Date: 20170210T120000Z
Range: bytes=0-1023	
x-amz-glacier-version: 2012-06-01
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2

回應範例

以下成功回應顯示 206 Partial Content 回應。在這種情況下，回應也包含 Content-Range 標頭，該標頭指定了 S3 Glacier 傳回的位元組範圍。

HTTP/1.1 206 Partial Content
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Wed, 10 Feb 2017 12:00:00 GMT
Content-Range: bytes 0-1023/8388608
Content-Type: application/octet-stream
Content-Length: 1024

[Archive data.]