Melakukan upload yang dapat dilanjutkan

Ringkasan

Halaman ini menjelaskan cara membuat permintaan upload yang dapat dilanjutkan di JSON dan XML API Cloud Storage. 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.

Izin yang diperlukan

JSON API

Untuk menyelesaikan panduan ini menggunakan JSON API, Anda harus memiliki izin IAM yang sesuai. Jika bucket yang ingin Anda upload ada dalam project yang tidak Anda buat, Anda mungkin perlu meminta pemilik project untuk memberi Anda peran yang berisi izin yang diperlukan.

Guna mengetahui daftar izin yang diperlukan untuk tindakan tertentu, lihat Izin IAM untuk metode JSON.

Untuk daftar peran yang relevan, lihat Peran Cloud Storage. Atau, Anda dapat membuat peran khusus yang memiliki izin khusus dan terbatas.

Memulai sesi upload yang dapat dilanjutkan

Untuk memulai sesi upload yang dapat dilanjutkan:

JSON API

1. Dapatkan token akses otorisasi dari OAuth 2.0 Playground. Konfigurasikan Playground agar menggunakan kredensial OAuth Anda sendiri. Untuk mendapatkan petunjuk, lihat Autentikasi API.

2. Atau, buat file JSON yang berisi metadata yang ingin ditetapkan pada objek yang Anda upload. Misalnya, file JSON berikut menetapkan metadata contentType objek yang ingin Anda upload ke image/png:

   {
       "contentType": "image/png"
   }

3. Gunakan cURL untuk memanggil JSON API dengan permintaan POST Object:

   curl -i -X POST --data-binary @METADATA_LOCATION \
       -H "Authorization: Bearer OAUTH2_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 pada langkah sebelumnya. Jika Anda tidak menyertakan file metadata, kecualikan file ini, beserta header --data-binary @ dan Content-Type.
   • OAUTH2_TOKEN adalah token akses yang Anda buat pada Langkah 1.
   • INITIAL_REQUEST_LENGTH adalah jumlah byte dalam isi permintaan awal ini, misalnya 79. Tidak diperlukan jika Anda menggunakan potongan encoding transfer.
   • BUCKET_NAME adalah nama bucket tempat Anda akan 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 sebagai pets%2Fdog.png. Langkah ini tidak diperlukan jika Anda menyertakan name dalam file metadata objek pada 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 dan X-Upload-Content-Length.

   Jika berhasil, respons akan menyertakan kode status 200.

4. Simpan URI sesi yang dapat dilanjutkan yang diberikan dalam header Location respons terhadap permintaan POST Object Anda.

   URI ini digunakan dalam permintaan berikutnya untuk mengupload data objek.

   Perhatian: Berhati-hatilah saat membagikan URI sesi yang dapat dilanjutkan, karena URI ini dapat digunakan oleh siapa saja untuk mengupload data ke bucket target tanpa autentikasi lebih lanjut.

XML API

1. Dapatkan token akses otorisasi dari OAuth 2.0 Playground. Konfigurasikan Playground agar menggunakan kredensial OAuth Anda sendiri. Untuk mendapatkan petunjuk, lihat Autentikasi API.

2. Gunakan cURL untuk memanggil XML API dengan permintaan POST Object yang isinya kosong:

   curl -i -X POST -H "Authorization: Bearer OAUTH2_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:

   • OAUTH2_TOKEN adalah token akses yang Anda buat pada Langkah 1.
   • OBJECT_CONTENT_TYPE adalah jenis konten objek. Misalnya, image/png. Jika jenis konten tidak ditentukan, sistem Cloud Storage akan menetapkan metadata Content-Type untuk objek tersebut menjadi application/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 sebagai pets%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.

3. Simpan URI sesi yang dapat dilanjutkan yang diberikan dalam header Location respons terhadap permintaan POST Object Anda.

   URI ini digunakan dalam permintaan berikutnya untuk mengupload data objek.

   Perhatian: Berhati-hatilah saat membagikan URI sesi yang dapat dilanjutkan, karena URI ini dapat digunakan oleh siapa saja untuk mengupload data ke bucket target tanpa autentikasi lebih lanjut.

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 potongan:

JSON API

1. Gunakan cURL untuk memanggil JSON API dengan permintaan PUT 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 dalam header Location 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

1. Gunakan cURL untuk memanggil XML API dengan permintaan PUT 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 dalam header Location saat Anda memulai upload yang dapat dilanjutkan.

Jika upload selesai secara keseluruhan, 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 dalam Melanjutkan upload yang terhenti.

Mengupload beberapa potongan

Untuk mengupload data dalam beberapa potongan:

JSON API

1. 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 potongan.

2. Gunakan cURL untuk memanggil JSON API dengan permintaan PUT 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 potongan yang sedang Anda upload.
   • CHUNK_SIZE adalah jumlah byte yang Anda upload dalam permintaan saat ini. Misalnya, 8388608.
   • CHUNK_FIRST_BYTE adalah byte awal dalam objek keseluruhan yang dimuat oleh potongan yang Anda upload.
   • CHUNK_LAST_BYTE adalah byte akhir dalam objek keseluruhan yang dimuat oleh potongan yang Anda upload.
   • TOTAL_OBJECT_SIZE adalah total ukuran objek yang Anda upload.
   • SESSION_URI adalah nilai yang ditampilkan dalam header Location saat Anda memulai upload yang dapat dilanjutkan.

   Misalnya, Content-Range adalah Content-Range: bytes 0-8388607/20000000. Lihat Content-Range untuk mengetahui informasi selengkapnya tentang header ini.

   Jika permintaan berhasil, server akan merespons dengan 308 Resume Incomplete. Respons berisi header Range.

3. 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

1. 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 potongan.

2. Gunakan cURL untuk memanggil XML API dengan permintaan PUT 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 potongan yang sedang Anda upload.
   • CHUNK_SIZE adalah jumlah byte yang Anda upload dalam permintaan saat ini. Misalnya, 8388608.
   • CHUNK_FIRST_BYTE adalah byte awal dalam objek keseluruhan yang dimuat oleh potongan yang Anda upload.
   • CHUNK_LAST_BYTE adalah byte akhir dalam objek keseluruhan yang dimuat oleh potongan yang Anda upload.
   • TOTAL_OBJECT_SIZE adalah total ukuran objek yang Anda upload.
   • SESSION_URI adalah nilai yang ditampilkan dalam header Location saat Anda memulai upload yang dapat dilanjutkan.

   Misalnya, Content-Range adalah Content-Range: bytes 0-8388607/20000000. Lihat Content-Range untuk mengetahui informasi selengkapnya tentang header ini.

   Jika permintaan berhasil, server akan merespons dengan 308 Resume Incomplete. Respons berisi header Range.

3. 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 secara keseluruhan, 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

1. Gunakan cURL untuk memanggil JSON API dengan permintaan PUT 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 tidak mengetahui ukuran penuh objek Anda, gunakan * untuk nilai ini.
   • SESSION_URI adalah nilai yang ditampilkan dalam header Location saat Anda memulai upload yang dapat dilanjutkan.

XML API

1. Gunakan cURL untuk memanggil XML API dengan permintaan PUT 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 tidak mengetahui ukuran penuh objek Anda, gunakan * untuk nilai ini.
   • SESSION_URI adalah nilai yang ditampilkan dalam header Location saat Anda memulai upload yang dapat dilanjutkan.

Respons 200 OK atau 201 Created menunjukkan bahwa upload selesai, dan tidak perlu melakukan tindakan lebih lanjut.

Respons 308 Resume Incomplete menunjukkan bahwa Anda harus terus mengupload data.

• Jika Cloud Storage belum mempertahankan byte apa pun, respons 308 tidak memiliki header Range. Dalam kasus ini, Anda harus memulai upload dari awal.
• Jika tidak, respons 308 memiliki header Range, yang menentukan byte mana yang dipertahankan Cloud Storage sejauh ini. Gunakan nilai ini saat melanjutkan upload yang terhenti.

Melanjutkan upload yang terhenti

Penting: Cloud Storage mengabaikan setiap byte yang Anda kirim pada offset yang sudah dipertahankan oleh Cloud Storage.

Jika permintaan upload dihentikan sebelum menerima respons, atau jika Anda menerima respons 503 atau 500, maka Anda perlu melanjutkan upload yang terhenti dari posisi terakhirnya. Untuk melanjutkan upload yang terhenti:

JSON API

1. Periksa status upload yang dapat dilanjutkan.

2. Simpan nilai yang lebih tinggi dari header Range, yang ada dalam respons, ke pemeriksaan status Anda. Jika respons tidak memiliki header Range, berarti Cloud Storage belum mempertahankan byte apa pun, dan Anda harus mengupload dari awal.

3. Pastikan data objek yang akan Anda upload dimulai pada byte setelah nilai yang lebih tinggi di header Range.

4. Jika permintaan yang terhenti berisi header yang diawali dengan X-Goog-Meta-, sertakan header tersebut dalam permintaan untuk melanjutkan upload.

5. Gunakan cURL untuk memanggil JSON API dengan permintaan PUT Object yang melanjutkan dari byte setelah nilai dalam header Range:

   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 adalah UPLOAD_SIZE_REMAINING 19999957.
   • NEXT_BYTE adalah bilangan bulat berikutnya setelah nilai yang Anda simpan di langkah 2. Misalnya, jika 42 adalah nilai yang lebih besar pada langkah 2, nilai untuk NEXT_BYTE adalah 43.
   • LAST_BYTE adalah byte akhir yang terdapat dalam permintaan PUT ini. Misalnya, untuk menyelesaikan upload objek yang ukuran totalnya adalah 20000000, nilai untuk LAST_BYTE adalah 19999999.
   • TOTAL_OBJECT_SIZE adalah total ukuran objek yang Anda upload. Misalnya, 20000000.
   • SESSION_URI adalah nilai yang ditampilkan dalam header Location saat Anda memulai upload yang dapat dilanjutkan.

XML API

1. Periksa status upload yang dapat dilanjutkan.

2. Simpan nilai yang lebih tinggi dari header Range, yang ada dalam respons, ke pemeriksaan status Anda. Jika respons tidak memiliki header Range, Cloud Storage belum mempertahankan byte apa pun, dan Anda harus mengupload dari awal.

3. Pastikan data objek yang akan Anda upload dimulai pada byte setelah nilai yang lebih tinggi di header Range.

4. Gunakan cURL untuk memanggil XML API dengan permintaan PUT Object yang melanjutkan dari byte setelah nilai dalam header Range:

   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 adalah UPLOAD_SIZE_REMAINING 19999957.
   • NEXT_BYTE adalah bilangan bulat berikutnya setelah nilai yang Anda simpan di langkah 2. Misalnya, jika 42 adalah nilai yang lebih besar pada langkah 2, nilai untuk NEXT_BYTE adalah 43.
   • LAST_BYTE adalah byte akhir yang terdapat dalam permintaan PUT ini. Misalnya, untuk menyelesaikan upload objek yang ukuran totalnya adalah 20000000, nilai untuk LAST_BYTE adalah 19999999.
   • TOTAL_OBJECT_SIZE adalah total ukuran objek yang Anda upload. Misalnya, 20000000.
   • SESSION_URI adalah nilai yang ditampilkan dalam header Location saat Anda memulai upload yang dapat dilanjutkan.

Anda dapat melanjutkan upload sebanyak yang diperlukan selama URI sesi aktif; URI sesi akan berakhir setelah seminggu. Jika 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

1. Gunakan cURL untuk memanggil JSON API dengan permintaan DELETE:

   curl -i -X DELETE -H "Content-Length: 0" \
     "SESSION_URI"

   Dengan keterangan:

   • SESSION_URI adalah nilai yang ditampilkan dalam header Location saat Anda memulai upload yang dapat dilanjutkan.

Jika berhasil, respons akan berisi kode status 499. Upaya selanjutnya untuk membuat kueri atau melanjutkan upload akan menghasilkan respons 4xx.

XML API

1. Gunakan cURL untuk memanggil XML API dengan permintaan DELETE:

   curl -i -X DELETE -H "Content-Length: 0" \
     "SESSION_URI"

   Dengan keterangan:

   • SESSION_URI adalah nilai yang ditampilkan dalam header Location saat Anda memulai upload yang dapat dilanjutkan.

Jika berhasil, responsnya akan berisi kode status 204. Upaya selanjutnya untuk membuat kueri atau melanjutkan upload juga akan menghasilkan respons 204.

Langkah berikutnya

• 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.