Memulai Tugas (POST jobs)

Operasi ini memulai tipe tugas Amazon S3 Glacier (S3 Glacier) berikut:

• archive-retrieval— Mengambil arsip.

• inventory-retrieval— Menyediakan vault.

Memulai Tugas Pengambilan Arsip atau Inventaris Vault

Mengambil arsip atau inventaris vault adalah operasi asinkron yang mengharuskan Anda memulai tugas. Setelah dimulai, tugas tidak dapat dibatalkan. Pengambilan adalah proses dua langkah:

1. Mulai tugas pengambilan menggunakan operasi Memulai Tugas (POST jobs).

   penting

   Kebijakan pengambilan data dapat menyebabkan permintaan mulai tugas pengambilan Anda gagal dengan PolicyEnforcedException. Untuk informasi selengkapnya tentang kebijakan pengambilan data, lihat Kebijakan Pengambilan Data Gletser S3. Untuk informasi selengkapnya tentang pengecualian PolicyEnforcedException, lihat Respons Kesalahan.

2. Setelah tugas selesai, unduh byte menggunakan operasi Mendapatkan Output Tugas (GET output).

Permintaan pengambilan dijalankan secara asinkron. Ketika Anda memulai tugas pengambilan, S3 Glacier membuat tugas dan mengembalikan ID tugas dalam respons. Ketika S3 Glacier menyelesaikan tugas, Anda bisa mendapatkan output tugas (arsip atau data inventaris). Untuk informasi tentang mendapatkan output tugas, lihat operasi Mendapatkan Output Tugas (GET output).

Tugas harus selesai sebelum Anda bisa mendapatkan outputnya. Untuk menentukan kapan tugas selesai, Anda memiliki opsi berikut:

• Gunakan notifikasi Amazon SNS— Anda dapat menentukan topik Amazon Simple Notification Service (Amazon SNS) tempat S3 Glacier dapat mengirim notifikasi setelah tugas selesai. Anda dapat menentukan topik SNS per permintaan tugas. Notifikasi hanya dikirim setelah S3 Glacier menyelesaikan tugas. Selain menentukan topik SNS per permintaan tugas, Anda dapat mengonfigurasi notifikasi vault untuk vault sehingga notifikasi tugas dikirim untuk semua pengambilan. Untuk informasi selengkapnya, lihat Menetapkan Konfigurasi Notifikasi Vault (PUT notification-configuration).

• Dapatkan detail tugas— Anda dapat membuat permintaan Mendeskripsikan Tugas (GET JobID) untuk mendapatkan informasi status tugas saat tugas sedang berlangsung. Namun, penggunaan notifikasi Amazon SNS untuk menentukan kapan tugas selesai lebih efisien.

catatan

Informasi yang Anda dapatkan melalui notifikasi sama dengan yang Anda dapatkan dengan memanggil Mendeskripsikan Tugas (GET JobID).

Jika untuk peristiwa spesifik, Anda menambahkan kedua konfigurasi notifikasi di vault dan juga menentukan topik SNS dalam permintaan mulai tugas Anda, S3 Glacier mengirimkan kedua notifikasi. Untuk informasi selengkapnya, lihat Menetapkan Konfigurasi Notifikasi Vault (PUT notification-configuration).

Inventaris Vault

S3 Glacier memperbarui inventaris vault sekitar sekali sehari, dimulai pada hari Anda pertama kali mengunggah arsip ke vault. Jika tidak ada penambahan arsip atau penghapusan vault sejak inventaris terakhir, tanggal inventaris tidak diperbarui. Ketika Anda memulai tugas untuk inventaris vault, S3 Glacier mengembalikan inventaris terakhir yang dihasilkan, yang merupakan point-in-time snapshot dan bukan data waktu nyata.

Setelah S3 Glacier membuat inventaris pertama untuk vault, biasanya diperlukan waktu setengah hari dan sampai satu hari sebelum inventaris tersedia untuk diambil.

Anda mungkin merasa mengambil inventaris vault untuk setiap unggahan arsip tidak berguna. Namun, misalkan Anda menyimpan basis data di metadata yang terkait sisi klien tentang arsip yang Anda unggah ke S3 Glacier. Selanjutnya, Anda mungkin merasa inventaris vault berguna untuk mencocokkan informasi, jika perlu, dalam basis data Anda dengan inventaris vault aktual. Untuk informasi selengkapnya tentang bidang data yang dikembalikan dalam output tugas, lihat Isi Respons.

Pengambilan Inventaris Rentang

Anda dapat membatasi jumlah item inventaris yang diambil dengan memfilter tanggal pembuatan arsip atau dengan menetapkan batas.

Memfilter berdasarkan Tanggal Pembuatan Arsip

Anda dapat mengambil item inventaris untuk arsip yang dibuat antara StartDate dan EndDate dengan menentukan nilai untuk parameter ini dalam permintaan Mulai Tugas. Arsip yang dibuat di atau setelah StartDate dan sebelum EndDate dikembalikan. Jika Anda hanya memberikan StartDate tanpa EndDate, Anda mengambil inventaris untuk semua arsip yang dibuat pada atau setelah StartDate. Jika Anda hanya memberikan EndDate tanpa StartDate, Anda mengambil inventaris untuk semua arsip yang dibuat sebelum EndDate.

Membatasi Item Inventaris per Pengambilan

Anda dapat membatasi jumlah item inventaris yang dikembalikan dengan mengatur parameter Limit dalam permintaan Mulai Tugas. Output tugas inventaris berisi item inventaris sampai dengan Limit yang ditentukan. Jika ada lebih banyak item inventarus yang tersedia, hasilnya adalah pemberian nomor halaman. Setelah tugas selesai, Anda dapat menggunakan operasi Mendeskripsikan Tugas (GET JobID) untuk mendapatkan penanda yang Anda gunakan dalam permintaan Mulai Tugas berikut. Penanda menunjukkan titik awal untuk mengambil sekumpulan item inventaris berikutnya. Anda dapat menelusuri seluruh inventaris dengan berulang kali membuat permintaan Mulai Tugas dengan penanda dari output Jelaskan Tugas sebelumnya. Anda melakukannya sampai Anda mendapatkan penanda dari Jelaskan Tugas yang mengembalikan nol, menunjukkan tidak ada item lainnya yang tersedia.

Anda dapat menggunakan parameter Limit bersama-sama dengan parameter rentang tanggal.

Pengambilan Arsip Berkisar

Anda dapat memulai pengambilan arsip untuk seluruh arsip atau rentang arsip. Dalam hal pengambilan arsip berkisar, Anda menentukan rentang byte untuk dikembalikan atau seluruh arsip. Rentang yang ditentukan harus megabyte (MB) selaras. Dengan kata lain, rentang awal nilai harus habis dibagi 1 MB dan rentang nilai akhir ditambah 1 harus habis dibagi 1 MB atau sama dengan akhir arsip. Jika pengambilan arsip berkisar bukan megabyte selaras, operasi ini mengembalikan respons 400. Selain itu, untuk memastikan Anda mendapatkan nilai checksum untuk data yang Anda unduh menggunakan Dapatkan Output Tugas (Mendapatkan Output Tugas (GET output)), rentang harus berupa tree-hash selaras. Untuk informasi selengkapnya tentang rentang tree-hash selaras, lihat Menerima Checksum Saat Mengunduh Data.

Tingkat Dipercepat, Standar, dan Massal.

Saat memulai tugas pengambilan arsip, Anda dapat menentukan salah satu opsi berikut diTier bidang isi permintaan:

• Expedited— Expedited memungkinkan Anda mengakses data Anda dengan cepat saat ada permintaan mendesak untuk memulihkan arsip. Untuk semua, kecuali arsip terbesar (250 MB+), data yang diakses menggunakan tingkat Dipercepat biasanya disediakan dalam waktu 1–5 menit.

• Standard – Standar memungkinkan Anda mengakses salah satu arsip Anda dalam beberapa jam. Data yang diakses menggunakan tingkat Standar biasanya tersedia dalam 3–5 jam. Ini adalah opsi default untuk permintaan tugas yang tidak menentukan opsi tingkat.

• Bulk – Massal adalah tingkat dengan biaya terendah untuk S3 Glacier, memungkinkan Anda mengambil data dalam jumlah besar, bahkan petabyte, dengan harga terjangkau dalam sehari. Data yang diakses menggunakan tingkat Massal biasanya tersedia dalam 5–12 jam.

Untuk informasi selengkapnya tentang pengambilan yang dipercepat dan massal, lihat Mengambil Arsip Gletser S3 Menggunakan Konsol AWS.

Permintaan

Untuk memulai tugas, Anda menggunakan metode POST HTTP dan mencakup permintaan untuk subsumber daya jobs vault. Anda menentukan detail permintaan tugas dalam dokumen JSON dari permintaan Anda. Tipe tugas ditentukan dengan bidang Type. Anda secara opsional dapat menentukan bidang SNSTopic untuk menunjukkan topik Amazon SNS tempat S3 Glacier dapat mengirimkan notifikasi setelah menyelesaikan tugas.

catatan

Untuk mengirim notifikasi ke Amazon SNS, Anda harus membuat topik sendiri jika belum ada. S3 Glacier tidak membuat topik untuk Anda. Topik harus memiliki izin untuk menerima publikasi dari vault S3 Glacier. S3 Glacier tidak memverifikasi apakah vault memiliki izin untuk menerbitkan ke topik. Jika izin tidak dikonfigurasi dengan tepat, Anda mungkin tidak menerima notifikasi bahkan setelah tugas selesai.

Sintaksis

Berikut ini adalah sintaks permintaan untuk memulai tugas.

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"
   }
}
			

catatan

Nilai AccountId adalah ID Akun AWS dari akun yang memiliki vault. Anda dapat menentukan ID Akun AWS atau secara opsional satu '-' (tanda hubung), dalam hal ini, Amazon S3 Glacier menggunakan ID Akun AWS yang terkait dengan kredensial yang digunakan untuk menandatangani permintaan. Jika Anda menggunakan ID akun, jangan sertakan tanda hubung ('-') di ID.

Isi Permintaan

Permintaan menerima data berikut dalam format JSON dalam isi permintaan.

jobParameters

Menyediakan opsi untuk menentukan informasi tugas.

Tipe: Objek jobParameters

Wajib: Ya

Respons

S3 Glacier membuat tugas. Sebagai respons, S3 Glacier mengembalikan URI tugas.

Sintaksis

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

Header Respons

Header	Deskripsi
Location	Jalur URI relatif dari tugas. Anda dapat menggunakan jalur URI ini untuk menemukan status tugas. Untuk informasi selengkapnya, lihat Mendeskripsikan Tugas (GET JobID). Tipe: String Default: Tidak ada
x-amz-job-id	ID tugas. Nilai ini juga disertakan sebagai bagian dari header Location. Tipe: String Default: Tidak ada
x-amz-job-output-path	Jalur ke lokasi tempat hasil pilih disimpan. Tipe: String Default: Tidak ada

Isi Respons

Operasi ini tidak mengembalikan isi respons.

Kesalahan

Operasi ini mencakup satu atau beberapa kesalahan berikut, selain kemungkinan kesalahan umum untuk semua operasi Amazon S3 Glacier. Untuk informasi tentang kesalahan Amazon S3 Glacier dan daftar kode kesalahan, lihat Respons Kesalahan.

Kode	Deskripsi	Kode Status HTTP	Tipe
InsufficientCapacityException	Dikembalikan jika kapasitas tidak memadai untuk memproses permintaan yang dipercepat ini. Kesalahan ini hanya berlaku untuk pengambilan yang dipercepat dan bukan untuk pengambilan standar atau massal.	503 Service Unavailable	Server

Contoh

Contoh Permintaan: Memulai tugas pengambilan arsip

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"
}

Berikut adalah contoh isi permintaan yang menentukan rentang arsip yang diambil menggunakan bidang 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"
}

Contoh Respons

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

Contoh Permintaan: Memulai tugas pengambilan inventaris

Permintaan berikut memulai tugas pengambilan inventaris untuk mendapatkan daftar arsip dari vault examplevault. Format yang ditetapkan ke CSV dalam isi permintaan menunjukkan inventaris dikembalikan dalam 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"
}

Contoh Respons

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

Contoh Permintaan: Memulai tugas pengambilan inventaris menggunakan penyaringan tanggal dengan batas yang ditetapkan, dan permintaan berikutnya untuk mengambil halaman item inventaris berikutnya.

Permintaan berikut memulai tugas pengambilan inventaris vault menggunakan penyaringan tanggal dan menetapkan batas.

{
    "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"
    }, 
}

Permintaan berikut adalah contoh dari permintaan berikutnya untuk mengambil halaman item inventaris berikutnya menggunakan penanda yang diperoleh dari Mendeskripsikan Tugas (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"
    }, 
}

Contoh Respons

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/

Bagian Terkait

• Mendeskripsikan Tugas (GET JobID)

• Mendapatkan Output Tugas (GET output)

• Identity and Access Management untuk Amazon S3 Glacier