Halaman ini diterjemahkan oleh Cloud Translation API.

Melakukan upload yang dapat dilanjutkan

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 ke image/png:
```
{
    "contentType": "image/png"
}
```
Gunakan cURL untuk memanggil JSON API dengan permintaan POST 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 @ dan Content-Type.
- INITIAL_REQUEST_LENGTH adalah jumlah byte dalam isi permintaan awal ini, misalnya 79.
- 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. Hal ini tidak diperlukan jika Anda menyertakan name 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 dan X-Upload-Content-Length.

Jika berhasil, respons akan menyertakan kode status 200.
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 tersebut dapat digunakan oleh siapa saja untuk mengupload data ke bucket target tanpa autentikasi lebih lanjut.

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 Objek POST 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 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.
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 tersebut 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 bagian:

JSON API

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 di 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

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 di header Location 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 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 bagian 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 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 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.
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 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 bagian 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 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 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.
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 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 Anda tidak mengetahui ukuran penuh objek, gunakan * untuk nilai ini.
- SESSION_URI adalah nilai yang ditampilkan di header Location saat Anda memulai upload yang dapat dilanjutkan.

XML API

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 Anda tidak mengetahui ukuran penuh objek, gunakan * untuk nilai ini.
- SESSION_URI adalah nilai yang ditampilkan di header Location 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 header Range. Dalam kasus ini, Anda harus memulai upload dari awal.
Jika tidak, respons 308 memiliki header Range, 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 header Range, Cloud Storage belum mempertahankan byte apa pun, dan Anda harus mengupload dari awal.
Pastikan bahwa 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 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 dengan total ukuran 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 di header Location 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 header Range, 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 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 dengan total ukuran 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 di 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. 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 permintaan DELETE:
```
curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"
```
Dengan keterangan:
- SESSION_URI adalah nilai yang ditampilkan di header Location 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 permintaan DELETE:
```
curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"
```
Dengan keterangan:
- SESSION_URI adalah nilai yang ditampilkan di header Location 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 situasi 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.