Halaman ini menjelaskan cara membuat permintaan upload yang dapat dilanjutkan di Cloud Storage JSON dan XML API. Protokol ini memungkinkan Anda melanjutkan operasi upload setelah kegagalan komunikasi mengganggu aliran data.
Untuk mengetahui informasi tentang cara menggunakan upload yang dapat dilanjutkan di Google Cloud CLI dan library klien, lihat Cara alat dan API menggunakan upload yang dapat dilanjutkan.
Peran yang diperlukan
Untuk mendapatkan izin yang diperlukan guna melakukan upload yang dapat dilanjutkan, minta administrator untuk memberi Anda salah satu peran berikut:
Untuk upload yang menyertakan Object Retention Lock, minta administrator untuk memberi Anda peran IAM Storage Object Admin (
roles/storage.objectAdmin
) untuk bucket.Untuk semua kasus lainnya, minta administrator untuk memberi Anda peran IAM Storage Object User (
roles/storage.objectUser
) untuk bucket.
Peran bawaan ini berisi izin yang diperlukan untuk mengupload objek ke bucket untuk kasus masing-masing. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:
Izin yang diperlukan
storage.objects.create
storage.objects.delete
- Izin ini hanya diperlukan untuk upload yang menimpa objek yang ada.
storage.objects.setRetention
- Izin ini hanya diperlukan untuk upload yang menyertakan Kunci Retensi Objek.
Anda juga bisa mendapatkan izin ini dengan peran standar atau peran khusus lainnya.
Untuk informasi tentang cara memberikan peran pada bucket, lihat Menggunakan IAM dengan bucket.
Memulai sesi upload yang dapat dilanjutkan
Untuk memulai sesi upload yang dapat dilanjutkan:
JSON API
Menginstal dan melakukan inisialisasi gcloud CLI , yang memungkinkan Anda membuat token akses untuk header
Authorization
.Atau, buat file JSON yang berisi metadata yang ingin Anda tetapkan pada objek yang Anda upload. Misalnya, file JSON berikut menetapkan metadata
contentType
objek yang ingin Anda upload keimage/png
:{ "contentType": "image/png" }
Gunakan
cURL
untuk memanggil JSON API dengan permintaanPOST
Object:curl -i -X POST --data-binary @METADATA_LOCATION \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "Content-Length: INITIAL_REQUEST_LENGTH" \ "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=resumable&name=OBJECT_NAME"
Dengan keterangan:
METADATA_LOCATION
adalah jalur lokal ke file JSON yang berisi metadata opsional yang Anda tentukan di langkah sebelumnya. Jika Anda tidak menyertakan file metadata, kecualikan file ini, beserta header--data-binary @
danContent-Type
.INITIAL_REQUEST_LENGTH
adalah jumlah byte dalam isi permintaan awal ini, misalnya79
.BUCKET_NAME
adalah nama bucket tempat Anda mengupload objek. Misalnya,my-bucket
.OBJECT_NAME
adalah nama yang dienkode ke URL yang ingin Anda berikan kepada objek. Misalnya,pets/dog.png
, dienkode ke URL sebagaipets%2Fdog.png
. Hal ini tidak diperlukan jika Anda menyertakanname
dalam file metadata objek di Langkah 2.
Jika telah mengaktifkan Cross-Origin Resource Sharing (CORS), Anda juga harus menyertakan header
Origin
dalam permintaan upload ini dan permintaan-permintaan berikutnya.Header opsional yang dapat Anda tambahkan ke permintaan, yang mencakup
X-Upload-Content-Type
danX-Upload-Content-Length
.Jika berhasil, respons akan menyertakan kode status
200
.Simpan URI sesi yang dapat dilanjutkan yang diberikan dalam header
Location
respons terhadap permintaanPOST
Object Anda.URI ini digunakan dalam permintaan berikutnya untuk mengupload data objek.
XML API
Menginstal dan melakukan inisialisasi gcloud CLI , yang memungkinkan Anda membuat token akses untuk header
Authorization
.Gunakan
cURL
untuk memanggil XML API dengan permintaan ObjekPOST
yang isinya kosong:curl -i -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Length: 0" \ -H "Content-Type: OBJECT_CONTENT_TYPE" \ -H "x-goog-resumable: start" \ "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"
Dengan keterangan:
OBJECT_CONTENT_TYPE
adalah jenis konten objek. Misalnya,image/png
. Jika jenis konten tidak ditentukan, sistem Cloud Storage akan menetapkan metadataContent-Type
untuk objek tersebut menjadiapplication/octet-stream
.BUCKET_NAME
adalah nama bucket tempat Anda mengupload objek. Misalnya,my-bucket
.OBJECT_NAME
adalah nama yang dienkode ke URL yang ingin Anda berikan kepada objek. Misalnya,pets/dog.png
, dienkode ke URL sebagaipets%2Fdog.png
.
Jika telah mengaktifkan Cross-Origin Resource Sharing (CORS), Anda juga harus menyertakan header
Origin
dalam permintaan upload ini dan permintaan-permintaan berikutnya.Jika berhasil, respons akan menyertakan pesan status
201
.Simpan URI sesi yang dapat dilanjutkan yang diberikan dalam header
Location
respons terhadap permintaanPOST
Object Anda.URI ini digunakan dalam permintaan berikutnya untuk mengupload data objek.
Mengupload data
Setelah Anda memulai upload yang dapat dilanjutkan, ada dua cara untuk mengupload data objek:
- Dalam satu potongan: Pendekatan ini biasanya merupakan pendekatan terbaik, karena memerlukan lebih sedikit permintaan sehingga memiliki performa yang lebih baik.
- Dalam beberapa potongan: Gunakan pendekatan ini jika Anda perlu mengurangi jumlah data yang ditransfer dalam satu permintaan, seperti saat ada batas waktu tetap untuk setiap permintaan, atau jika Anda tidak tahu ukuran total upload pada saat upload dimulai.
Mengupload potongan tunggal
Untuk mengupload data dalam satu bagian:
JSON API
Gunakan
cURL
untuk memanggil JSON API dengan permintaanPUT
Object:curl -i -X PUT --data-binary @OBJECT_LOCATION \ -H "Content-Length: OBJECT_SIZE" \ "SESSION_URI"
Dengan keterangan:
OBJECT_LOCATION
adalah jalur lokal ke objek Anda. Misalnya,Desktop/dog.png
.OBJECT_SIZE
adalah jumlah byte dalam objek Anda. Misalnya,20000000
.SESSION_URI
adalah nilai yang ditampilkan di headerLocation
saat Anda memulai upload yang dapat dilanjutkan.
Atau, Anda dapat menyertakan header yang diawali dengan
X-Goog-Meta-
guna menambahkan metadata kustom untuk objek tersebut sebagai bagian dari permintaan ini.
XML API
Gunakan
cURL
untuk memanggil XML API dengan permintaanPUT
Object:curl -i -X PUT --data-binary @OBJECT_LOCATION \ -H "Content-Length: OBJECT_SIZE" \ "SESSION_URI"
Dengan keterangan:
OBJECT_LOCATION
adalah jalur lokal ke objek Anda. Misalnya,Desktop/dog.png
.OBJECT_SIZE
adalah jumlah byte dalam objek Anda. Misalnya,20000000
.SESSION_URI
adalah nilai yang ditampilkan di headerLocation
saat Anda memulai upload yang dapat dilanjutkan.
Jika upload selesai sepenuhnya, Anda akan menerima respons 200 OK
atau 201 Created
, beserta metadata apa pun yang terkait dengan resource.
Jika permintaan upload terhenti, atau jika Anda menerima respons 5xx
, ikuti prosedur di Melanjutkan upload yang terhenti.
Mengupload beberapa potongan
Untuk mengupload data dalam beberapa potongan:
JSON API
Buat sepotong data dari keseluruhan data yang ingin Anda upload.
Ukuran potongan harus merupakan kelipatan dari 256 KiB (256 x 1024 byte), kecuali jika itu adalah potongan terakhir yang menyelesaikan proses upload. Ukuran potongan yang lebih besar biasanya membuat proses upload lebih cepat, tetapi perhatikan bahwa ada konsekuensi antara kecepatan dan penggunaan memori. Sebaiknya gunakan minimal 8 MiB untuk ukuran bagian.
Gunakan
cURL
untuk memanggil JSON API dengan permintaanPUT
Object:curl -i -X PUT --data-binary @CHUNK_LOCATION \ -H "Content-Length: CHUNK_SIZE" \ -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \ "SESSION_URI"
Dengan keterangan:
CHUNK_LOCATION
adalah jalur lokal ke bagian yang saat ini Anda upload.CHUNK_SIZE
adalah jumlah byte yang Anda upload dalam permintaan saat ini. Misalnya,8388608
.CHUNK_FIRST_BYTE
adalah byte awal dalam objek secara keseluruhan yang berisi bagian yang Anda upload.CHUNK_LAST_BYTE
adalah byte akhir dalam objek keseluruhan yang berisi bagian yang Anda upload.TOTAL_OBJECT_SIZE
adalah total ukuran objek yang Anda upload.SESSION_URI
adalah nilai yang ditampilkan di headerLocation
saat Anda memulai upload yang dapat dilanjutkan.
Misalnya,
Content-Range
adalahContent-Range: bytes 0-8388607/20000000
. LihatContent-Range
untuk mengetahui informasi selengkapnya tentang header ini.Jika permintaan berhasil, server akan merespons dengan
308 Resume Incomplete
. Respons berisi headerRange
.Ulangi langkah-langkah di atas untuk setiap potongan data yang tersisa yang ingin diupload, menggunakan nilai yang lebih besar yang terdapat dalam header
Range
dari setiap respons untuk menentukan tempat memulai setiap potongan berikutnya; Anda sebaiknya tidak berasumsi bahwa server menerima semua byte yang dikirim dalam permintaan tertentu.Atau, dalam permintaan akhir dari upload yang dapat dilanjutkan, Anda dapat menyertakan header yang diawali dengan
X-Goog-Meta-
untuk menambahkan metadata kustom bagi objek tersebut.
XML API
Buat sepotong data dari keseluruhan data yang ingin Anda upload.
Ukuran potongan harus merupakan kelipatan dari 256 KiB (256 x 1024 byte), kecuali jika itu adalah potongan terakhir yang menyelesaikan proses upload. Ukuran potongan yang lebih besar biasanya membuat proses upload lebih cepat, tetapi perhatikan bahwa ada konsekuensi antara kecepatan dan penggunaan memori. Sebaiknya gunakan minimal 8 MiB untuk ukuran bagian.
Gunakan
cURL
untuk memanggil XML API dengan permintaanPUT
Object:curl -i -X PUT --data-binary @CHUNK_LOCATION \ -H "Content-Length: CHUNK_SIZE" \ -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \ "SESSION_URI"
Dengan keterangan:
CHUNK_LOCATION
adalah jalur lokal ke bagian yang saat ini Anda upload.CHUNK_SIZE
adalah jumlah byte yang Anda upload dalam permintaan saat ini. Misalnya,8388608
.CHUNK_FIRST_BYTE
adalah byte awal dalam objek secara keseluruhan yang berisi bagian yang Anda upload.CHUNK_LAST_BYTE
adalah byte akhir dalam objek keseluruhan yang berisi bagian yang Anda upload.TOTAL_OBJECT_SIZE
adalah total ukuran objek yang Anda upload.SESSION_URI
adalah nilai yang ditampilkan di headerLocation
saat Anda memulai upload yang dapat dilanjutkan.
Misalnya,
Content-Range
adalahContent-Range: bytes 0-8388607/20000000
. LihatContent-Range
untuk mengetahui informasi selengkapnya tentang header ini.Jika permintaan berhasil, server akan merespons dengan
308 Resume Incomplete
. Respons berisi headerRange
.Ulangi langkah-langkah di atas untuk setiap potongan data yang tersisa yang ingin diupload, menggunakan nilai yang lebih besar yang terdapat dalam header
Range
dari setiap respons untuk menentukan tempat memulai setiap potongan berikutnya; Anda sebaiknya tidak berasumsi bahwa server menerima semua byte yang dikirim dalam permintaan tertentu.
Setelah upload selesai sepenuhnya, Anda akan menerima respons 200 OK
atau 201 Created
, beserta metadata apa pun yang terkait dengan resource.
Jika salah satu proses upload potongan terhenti, atau jika Anda menerima respons 5xx
, Anda harus mengirim ulang potongan yang terhenti secara keseluruhan atau melanjutkan upload yang terhenti dari posisi terakhirnya.
Memeriksa status upload yang dapat dilanjutkan
Jika upload yang dapat dilanjutkan terhenti, atau Anda tidak yakin proses upload selesai, Anda dapat memeriksa status upload:
JSON API
Gunakan
cURL
untuk memanggil JSON API dengan permintaanPUT
Object:curl -i -X PUT \ -H "Content-Length: 0" \ -H "Content-Range: bytes */OBJECT_SIZE" \ "SESSION_URI"
Dengan keterangan:
OBJECT_SIZE
adalah total jumlah byte dalam objek Anda. Jika Anda tidak mengetahui ukuran penuh objek, gunakan*
untuk nilai ini.SESSION_URI
adalah nilai yang ditampilkan di headerLocation
saat Anda memulai upload yang dapat dilanjutkan.
XML API
Gunakan
cURL
untuk memanggil XML API dengan permintaanPUT
Object:curl -i -X PUT \ -H "Content-Length: 0" \ -H "Content-Range: bytes */OBJECT_SIZE" \ "SESSION_URI"
Dengan keterangan:
OBJECT_SIZE
adalah total jumlah byte dalam objek Anda. Jika Anda tidak mengetahui ukuran penuh objek, gunakan*
untuk nilai ini.SESSION_URI
adalah nilai yang ditampilkan di headerLocation
saat Anda memulai upload yang dapat dilanjutkan.
Respons 200 OK
atau 201 Created
menunjukkan bahwa upload telah
selesai, dan tidak diperlukan tindakan lebih lanjut.
Respons 308 Resume Incomplete
menunjukkan bahwa Anda perlu melanjutkan
upload data.
- Jika Cloud Storage belum mempertahankan byte apa pun, respons
308
tidak memiliki headerRange
. Dalam kasus ini, Anda harus memulai upload dari awal. - Jika tidak, respons
308
memiliki headerRange
, yang menentukan byte yang telah dipertahankan Cloud Storage sejauh ini. Gunakan nilai ini saat melanjutkan upload yang terputus.
Melanjutkan upload yang terhenti
Jika permintaan upload dihentikan sebelum menerima respons, atau jika Anda menerima respons 503
atau 500
, Anda harus melanjutkan upload yang terhenti dari posisi terakhirnya. Untuk melanjutkan upload yang terhenti:
JSON API
Periksa status upload yang dapat dilanjutkan.
Simpan nilai yang lebih tinggi dari header
Range
, yang ada dalam respons, ke pemeriksaan status Anda. Jika respons tidak memiliki headerRange
, Cloud Storage belum mempertahankan byte apa pun, dan Anda harus mengupload dari awal.Pastikan data objek yang akan Anda upload dimulai pada byte setelah nilai atas di header
Range
.Jika permintaan yang terhenti berisi header yang diawali dengan
X-Goog-Meta-
, sertakan header tersebut dalam permintaan untuk melanjutkan upload.Gunakan
cURL
untuk memanggil JSON API dengan permintaanPUT
Object yang melanjutkan dari byte setelah nilai dalam headerRange
:curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \ -H "Content-Length: UPLOAD_SIZE_REMAINING" \ -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \ "SESSION_URI"
Dengan keterangan:
PARTIAL_OBJECT_LOCATION
adalah jalur lokal ke bagian data yang tersisa yang ingin Anda upload.UPLOAD_SIZE_REMAINING
adalah jumlah byte yang Anda upload dalam permintaan saat ini. Misalnya, jika mengupload sisa objek dengan total ukuran 20000000 yang terhenti setelah byte 0-42 diupload, maka nilainya adalahUPLOAD_SIZE_REMAINING
19999957
.NEXT_BYTE
adalah bilangan bulat berikutnya setelah nilai yang Anda simpan di langkah 2. Misalnya, jika42
adalah nilai yang lebih besar pada langkah 2, nilai untukNEXT_BYTE
adalah43
.LAST_BYTE
adalah byte akhir yang terdapat dalam permintaanPUT
ini. Misalnya, untuk menyelesaikan upload objek dengan total ukuran20000000
, nilai untukLAST_BYTE
adalah19999999
.TOTAL_OBJECT_SIZE
adalah total ukuran objek yang Anda upload. Misalnya,20000000
.SESSION_URI
adalah nilai yang ditampilkan di headerLocation
saat Anda memulai upload yang dapat dilanjutkan.
XML API
Periksa status upload yang dapat dilanjutkan.
Simpan nilai yang lebih tinggi dari header
Range
, yang ada dalam respons, ke pemeriksaan status Anda. Jika respons tidak memiliki headerRange
, Cloud Storage belum mempertahankan byte apa pun, dan Anda harus mengupload dari awal.Pastikan data objek yang akan Anda upload dimulai pada byte setelah nilai atas di header
Range
.Gunakan
cURL
untuk memanggil XML API dengan permintaanPUT
Object yang melanjutkan dari byte setelah nilai dalam headerRange
:curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \ -H "Content-Length: UPLOAD_SIZE_REMAINING" \ -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \ "SESSION_URI"
Dengan keterangan:
PARTIAL_OBJECT_LOCATION
adalah jalur lokal ke bagian data yang tersisa yang ingin Anda upload.UPLOAD_SIZE_REMAINING
adalah jumlah byte yang Anda upload dalam permintaan saat ini. Misalnya, jika mengupload sisa objek dengan total ukuran 20000000 yang terhenti setelah byte 0-42 diupload, maka nilainya adalahUPLOAD_SIZE_REMAINING
19999957
.NEXT_BYTE
adalah bilangan bulat berikutnya setelah nilai yang Anda simpan di langkah 2. Misalnya, jika42
adalah nilai yang lebih besar pada langkah 2, nilai untukNEXT_BYTE
adalah43
.LAST_BYTE
adalah byte akhir yang terdapat dalam permintaanPUT
ini. Misalnya, untuk menyelesaikan upload objek dengan total ukuran20000000
, nilai untukLAST_BYTE
adalah19999999
.TOTAL_OBJECT_SIZE
adalah total ukuran objek yang Anda upload. Misalnya,20000000
.SESSION_URI
adalah nilai yang ditampilkan di headerLocation
saat Anda memulai upload yang dapat dilanjutkan.
Anda dapat melanjutkan upload sebanyak yang diperlukan selama URI sesi
aktif; URI sesi akan berakhir setelah seminggu. Saat data berhasil
diupload, Cloud Storage akan merespons dengan kode status
200 OK
atau 201 created
.
Membatalkan upload
Untuk membatalkan upload yang dapat dilanjutkan yang tidak selesai dan mencegah tindakan lebih lanjut pada upload tersebut:
JSON API
Gunakan
cURL
untuk memanggil JSON API dengan permintaanDELETE
:curl -i -X DELETE -H "Content-Length: 0" \ "SESSION_URI"
Dengan keterangan:
SESSION_URI
adalah nilai yang ditampilkan di headerLocation
saat Anda memulai upload yang dapat dilanjutkan.
Jika berhasil, respons akan berisi kode status 499
. Upaya mendatang untuk membuat kueri atau melanjutkan hasil upload dalam respons 4xx
.
XML API
Gunakan
cURL
untuk memanggil XML API dengan permintaanDELETE
:curl -i -X DELETE -H "Content-Length: 0" \ "SESSION_URI"
Dengan keterangan:
SESSION_URI
adalah nilai yang ditampilkan di headerLocation
saat Anda memulai upload yang dapat dilanjutkan.
Jika berhasil, respons akan berisi kode status 204
, dan upaya
mendatang untuk membuat kueri atau melanjutkan upload juga akan menghasilkan respons 204
.
Penanganan Kegagalan
Dalam keadaan yang jarang terjadi, permintaan untuk melanjutkan upload yang terputus mungkin gagal dengan error '4xx' yang tidak dapat dicoba ulang karena izin di bucket telah berubah, atau karena pemeriksaan integritas pada objek yang diupload terakhir mendeteksi ketidakcocokan. Jika hal ini terjadi, coba upload lagi dengan memulai sesi upload yang dapat dilanjutkan baru.
Langkah selanjutnya
- Pelajari upload yang dapat dilanjutkan lebih lanjut.
- Baca ringkasan untuk JSON API dan XML API.
- Upload streaming dengan ukuran yang tidak diketahui.
- Membuat batch beberapa permintaan ke JSON API Cloud Storage.