啟動 Job (POST工作) - Amazon S3 Glacier
初始化封存或保存庫庫存擷取工作 請求回應範例相關章節

此頁面僅適用於使用 Vault 和 REST API 2012 年原始版本的 S3 Glacier 服務的現有客戶。

如果您要尋找封存儲存解決方案，建議您在 Amazon S3、S3 Glacier S3 Instant Retrieval、S3 Glacier Flexible Retrieval 和 S3 Glacier Deep Archive 中使用 S3 Glacier 儲存類別。若要進一步了解這些儲存選項，請參閱 Amazon S3 使用者指南 中的使用 S3 Glacier 儲存類別的 S3 Glacier 儲存類別和長期資料儲存。 Amazon S3 這些儲存類別使用 Amazon S3 API，適用於所有區域，並且可以在 Amazon S3 主控台中管理。它們提供 Storage Cost Analysis、Storage Lens、進階選用加密功能等功能。

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

啟動 Job (POST工作)

此作業會啟動下列類型的 Amazon S3 Glacier (S3 Glacier) 工作：

  • archive-retrieval：擷取封存

  • inventory-retrieval：清點保存庫

初始化封存或保存庫庫存擷取工作

擷取封存或保存庫庫存是非同步作業，需要您啟動工作。一旦啟動，就無法取消任務。擷取是兩個步驟：

  1. 使用 啟動 Job (POST工作) 操作啟動擷取任務。

    重要

    資料擷取政策可能導致啟動擷取作業請求失敗，並出現 PolicyEnforcedException。如需有關資料擷取政策的詳細資訊，請參閱 S3 Glacier 資料擷取政策。如需 PolicyEnforcedException 例外狀況的詳細資訊，請參閱 錯誤回應。

  2. 任務完成後，使用 「取得任務輸出」 (GET 輸出) 操作下載位元組。

以非同步方式執行擷取請求。當您開始擷取工作時，S3 Glacier 會建立工作並在回應中傳回工作 ID。當 S3 Glacier 完成工作時，您可以取得工作輸出 (封存或庫存資料)。如需有關取得任務輸出的詳細資訊，請參閱 「取得任務輸出」 (GET 輸出) 操作。

必須完成任務，才能取得其輸出。若要判斷任務何時完成，您有下列選項：

  • 使用 Amazon SNS 通知 — 您可以指定一個 Amazon SNS 主題，S3 Glacier 可以在任務完成後張貼通知。您可以為每個工作請求指定一個SNS主題。通知僅在 S3 Glacier 完成工作後傳送。除了為每個工作請求指定SNS主題外，您還可以規劃 Vault 的 Vault 通知，以便針對所有擷取傳送工作通知。如需詳細資訊，請參閱 設定文件庫通知組態 (PUT 通知的組態)。

  • 取得工作詳細資訊：工作進行中時，您可以提出 描述任務 (GET JobID) 請求以取得工作狀態資訊。但是，使用 Amazon SNS 通知來確定任務何時完成會更有效率。

注意

您透過通知取得的資訊，與您呼叫 描述任務 (GET JobID) 所取得的資訊相同。

如果針對特定事件，您同時在文件庫上新增通知組態，並在起始任務請求中指定一個SNS主題，S3 Glacier 會傳送兩個通知。如需詳細資訊，請參閱 設定文件庫通知組態 (PUT 通知的組態)。

此保存庫庫存

從您第一次將封存上傳到保存庫的那一天起，S3 Glacier 大約每天更新一次保存庫庫存。如果從上次清查以來，沒有新增或刪除文件庫的存檔，則清查日期不會更新。當您啟動文件庫庫存的任務時，S3 Glacier 會傳回產生的最後一個庫存，這是 point-in-time 快照，而非即時資料。

S3 Glacier 為保存庫建立第一個庫存後，通常需要半天到一天的時間才可以擷取庫存。

您可能沒有發現為每個存檔上傳擷取文件庫清查的好處。但是，假設您在用戶端上維護資料庫，該用戶端將上傳到 S3 Glacier 的封存相關中繼資料建立關聯。然後，您可能會發現文件庫清查的好處，可以視需要在資料庫中使用實際的文件庫清查來調節資訊。如需有關庫存任務輸出中傳回的資料欄位的詳細資訊，請參閱 回應內文。

庫存擷取範圍

您可以透過篩選在保存庫建立日期或設定限制來限制擷取到的保存庫庫存項目的數量。

透過封存建立日期進行篩選

您可以透過在啟動工作請求中指定這些參數的值，來擷取在 StartDate 和 EndDate 之間建立之封存的庫存項目。在 StartDate 之時或之後，以及 EndDate 之前所建立的封存被傳回。如果您只提供沒有 StartDate 的 EndDate ，則擷取 StartDate 或之後建立的所有封存的庫存。如果您只提供 EndDate 而沒有 StartDate，則擷取 EndDate 之時或之後所建立的所有封存的庫存。

限制每個擷取的庫存項目

您可以透過在啟動工作請求中設定 Limit 參數，來限制傳回的庫存項目數量。庫存任務輸出包含達到指定 Limit 的庫存項目。如果有更多的庫存項目可用，則結果會進行分頁。在任務完成後，您可以使用 描述任務 (GET JobID) 操作來取得您在後續的啟動任務請求中使用的標記。標記指示要擷取下一組庫存項目的起點。您可以透過使用之前描述工作輸出中的標記重複建立啟動工作請求來瀏覽整個庫存。這樣做一直到您從描述任務取得傳回空標記，表示沒有更多的庫存項目可用。

您可以將 Limit 參數與日期範圍參數一起使用。

遠端封存擷取

您可以為整個封存或封存範圍啟動封存擷取。在遠端封存擷取的情況下，指定要傳回的位元組範圍或整個封存。指定的範圍必須符合百萬位元組 (MB)。換言之，範圍起始值必須可被 1 MB 整除，並且範圍結束值加上 1 必須可整除 1 MB 或等於封存的結束。如果遠端封存擷取不符合 MB，則此操作將傳回 400 回應。此外，為了確保使用取得任務輸 (「取得任務輸出」 (GET 輸出)) 下載的資料取得檢查總和值，該範圍必須必須符合樹狀雜湊。如需有關樹狀雜湊符合範圍的詳細資訊，請參閱 下載資料時接收檢查總和。

急件、標準和大量方案

當啟動封存擷取工作時，可以在請求內文的 Tier 欄位中指定下列選項之一：

  • Expedited：當您偶爾需要緊急要求還原封存時，急件讓您快速存取資料。對於幾乎最大型的封存 (250 MB 以上)，使用急件方案所存取的資料，通常會在 1-5 分鐘內即可使用。

  • Standard：讓您能以標準方案在幾小時內存取任何封存。使用標準方案存取的資料通常 3 -5 小時內可用。若未指定方案選項，這會是任務請求的預設選項。

  • Bulk：大量是 S3 Glacier 的最低成本方案，無須太多費用即可於一天內擷取大量資料 (甚至達到數 PB)。使用大量方案存取的資料通常 5 -12 小時內可用。

如需有關急件和大量擷取的詳細資訊，請參閱 使用 AWS 主控台擷取 S3 Glacier 封存。

請求

若要啟動工作，您可以使用該HTTPPOST方法，並將請求範圍限定在 Vault 的jobs子資源中。您可以在請求的JSON文件中指定工作請求的詳細資訊。任務類型是由 Type 欄位指定的。您可以選擇性地指定一個SNSTopic欄位，指出 S3 Glacier 可在任務完成後張貼通知的 Amazon SNS 主題。

注意

要將通知發佈到 AmazonSNS，您必須自行創建主題（如果該主題尚未存在）。S3 Glacier 不會為您建立主題。該主題必須有權接收來自 S3 Glacier 保存庫的發布。S3 Glacier 不驗證保存庫是否具有發布到該主題的許可。如果未設定適當的權限，即使任務完成後，您也可能不會收到通知。

語法

以下是啟動任務的請求語法。

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

{
   "jobParameters": { 
      "ArchiveId": "string",
      "Description": "string",
      "Format": "string",
      "InventoryRetrievalParameters": { 
         "EndDate": "string",
         "Limit": "string",
         "Marker": "string",
         "StartDate": "string"
      },
      "OutputLocation": { 
         "S3": { 
            "AccessControlList": [ 
               { 
                  "Grantee": { 
                     "DisplayName": "string",
                     "EmailAddress": "string",
                     "ID": "string",
                     "Type": "string",
                     "URI": "string"
                  },
                  "Permission": "string"
               }
            ],
            "BucketName": "string",
            "CannedACL": "string",
            "Encryption": { 
               "EncryptionType": "string",
               "KMSContext": "string",
               "KMSKeyId": "string"
            },
            "Prefix": "string",
            "StorageClass": "string",
            "Tagging": { 
               "string" : "string" 
            },
            "UserMetadata": { 
               "string" : "string" 
            }
         }
      },
      "RetrievalByteRange": "string",
      "SelectParameters": { 
         "Expression": "string",
         "ExpressionType": "string",
         "InputSerialization": { 
            "csv": { 
               "Comments": "string",
               "FieldDelimiter": "string",
               "FileHeaderInfo": "string",
               "QuoteCharacter": "string",
               "QuoteEscapeCharacter": "string",
               "RecordDelimiter": "string"
            }
         },
         "OutputSerialization": { 
            "csv": { 
               "FieldDelimiter": "string",
               "QuoteCharacter": "string",
               "QuoteEscapeCharacter": "string",
               "QuoteFields": "string",
               "RecordDelimiter": "string"
            }
         }
      },
      "SNSTopic": "string",
      "Tier": "string",
      "Type": "string"
   }
}
注意

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

請求主體

請求接受請求主體中JSON格式的以下數據。

jobParameters

提供指定任務資訊的選項。

類型：jobParameters物件

必要：是

回應

S3 Glacier 建立此工作。在回應中，它會傳回工作URI的。

語法

HTTP/1.1 202 Accepted
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Location: location
x-amz-job-id: jobId
x-amz-job-output-path: jobOutputPath

回應標頭

標頭 描述
Location

工作的相對URI路徑。您可以使用此URI路徑來尋找工作狀態。如需詳細資訊，請參閱 描述任務 (GET JobID)。

類型：字串

預設：無
x-amz-job-id

任務的 ID。此值也包含在 Location 標頭中。

類型：字串

預設：無
x-amz-job-output-path

儲存選取結果的位置的路徑。

類型：字串

預設：無

回應內文

此作業不會傳回任何回應內文。

錯誤

除了所有 Amazon S3 Glacier 作業常見的可能錯誤以外，此作業還包括下列一或多個錯誤。如需 Amazon S3 Glacier 錯誤和錯誤代碼清單的相關資訊，請參閱錯誤回應。

代碼 描述 HTTP狀態碼 Type
InsufficientCapacityException 如果沒有足夠的能力處理此急件請求，則退回。此錯誤僅適用於急件擷取，而不適用於標準或大量擷取。 503 Service Unavailable Server

範例

範例請求：啟動封存擷取任務

POST /-/vaults/examplevault/jobs 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

{
  "Type": "archive-retrieval",
  "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId",
  "Description": "My archive description",
  "SNSTopic": "arn:aws:sns:us-west-2:111111111111:Glacier-ArchiveRetrieval-topic-Example",
  "Tier" : "Bulk"
}

以下是一個請求內文的範例，該請求指定各種封存擷取使用 RetrievalByteRange 欄位。

{
  "Type": "archive-retrieval",
  "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId",
  "Description": "My archive description",
  "RetrievalByteRange": "2097152-4194303",
  "SNSTopic": "arn:aws:sns:us-west-2:111111111111:Glacier-ArchiveRetrieval-topic-Example",
  "Tier" : "Bulk"
}

回應範例

HTTP/1.1 202 Accepted
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Wed, 10 Feb 2017 12:00:00 GMT
Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID
x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID

範例請求：啟動庫存擷取任務

以下請求將啟動一個庫存擷取工作，以便從 examplevault 保存庫中取得封存清單。請求主體CSV中的Format設定值表示以CSV格式傳回詳細目錄。

POST /-/vaults/examplevault/jobs HTTP/1.1
Host: glacier.us-west-2.amazonaws.com
x-amz-Date: 20170210T120000Z
Content-Type: application/x-www-form-urlencoded
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

{
  "Type": "inventory-retrieval",
  "Description": "My inventory job",
  "Format": "CSV",  
  "SNSTopic": "arn:aws:sns:us-west-2:111111111111:Glacier-InventoryRetrieval-topic-Example"
}

回應範例

HTTP/1.1 202 Accepted
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Wed, 10 Feb 2017 12:00:00 GMT 
Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID
x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID

範例請求：通過使用一組限制的日期篩選和後續請求來擷取庫存項目的下一頁，啟動庫存擷取任務。

以下請求透過使用日期篩選和設定限制來啟動保存庫庫存擷取工作。


{
    "ArchiveId": null, 
    "Description": null, 
    "Format": "CSV", 
    "RetrievalByteRange": null, 
    "SNSTopic": null, 
    "Type": "inventory-retrieval", 
    "InventoryRetrievalParameters": {
        "StartDate": "2013-12-04T21:25:42Z",
        "EndDate": "2013-12-05T21:25:42Z", 
        "Limit" : "10000"
    }, 
}

以下的請求範例，後續請求使用來自 描述任務 (GET JobID) 所取得的標記來擷取庫存項目的下一頁。

{
    "ArchiveId": null, 
    "Description": null, 
    "Format": "CSV", 
    "RetrievalByteRange": null, 
    "SNSTopic": null, 
    "Type": "inventory-retrieval", 
    "InventoryRetrievalParameters": {
        "StartDate": "2013-12-04T21:25:42Z",
        "EndDate": "2013-12-05T21:25:42Z", 
        "Limit": "10000",
        "Marker": "vyS0t2jHQe5qbcDggIeD50chS1SXwYMrkVKo0KHiTUjEYxBGCqRLKaiySzdN7QXGVVV5XZpNVG67pCZ_uykQXFMLaxOSu2hO_-5C0AtWMDrfo7LgVOyfnveDRuOSecUo3Ueq7K0"
    }, 
}

回應範例

HTTP/1.1 202 Accepted
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Wed, 10 Feb 2017 12:00:00 GMT 
Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID
x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID
x-amz-job-output-path: test/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/

相關章節