Upload yang dapat dilanjutkan

Penyiapan

Halaman ini membahas upload yang dapat dilanjutkan di Cloud Storage. Upload yang dapat dilanjutkan adalah metode yang direkomendasikan untuk mengupload file besar, karena Anda tidak perlu memulai ulang dari awal jika terjadi kegagalan jaringan saat upload sedang berlangsung.

Pengantar

Upload yang dapat dilanjutkan memungkinkan Anda melanjutkan operasi transfer data ke Cloud Storage setelah kegagalan komunikasi mengganggu aliran data. Upload yang dapat dilanjutkan berfungsi dengan mengirimkan beberapa permintaan, yang masing-masing berisi bagian dari objek yang Anda upload. Hal ini berbeda dengan upload permintaan tunggal, yang berisi semua data objek dalam satu permintaan dan harus dimulai ulang dari awal jika gagal di sebagian.

  • Gunakan upload yang dapat dilanjutkan jika Anda mengupload file besar atau mengupload melalui koneksi lambat. Untuk mengetahui ukuran file agar dapat menggunakan upload yang dapat dilanjutkan, lihat pertimbangan ukuran upload.

  • Upload yang dapat dilanjutkan harus diselesaikan dalam waktu satu minggu setelah dimulai, tetapi dapat dibatalkan kapan saja.

  • Hanya upload yang dapat dilanjutkan dengan status selesai yang akan muncul di bucket Anda dan, jika memungkinkan, akan mengganti objek yang ada dengan nama yang sama.

    • Waktu pembuatan objek didasarkan pada saat upload selesai.

    • Metadata objek yang disetel oleh pengguna ditentukan di permintaan awal. Metadata ini diterapkan ke objek setelah upload selesai.

    • JSON API juga mendukung penyetelan metadata kustom dalam permintaan akhir jika Anda menyertakan header yang diawali dengan X-Goog-Meta- dalam permintaan tersebut.

  • Upload yang dapat dilanjutkan dan telah selesai dianggap sebagai satu operasi Class A.

Cara alat dan API menggunakan upload yang dapat dilanjutkan

Bergantung pada cara Anda berinteraksi dengan Cloud Storage, upload yang dapat dilanjutkan mungkin dikelola secara otomatis untuk Anda. Bagian ini menjelaskan perilaku upload yang dapat dilanjutkan dengan berbagai alat dan memberikan panduan tentang cara mengonfigurasi ukuran buffer yang sesuai untuk aplikasi Anda.

Konsol

Konsol Google Cloud mengelola upload yang dapat dilanjutkan secara otomatis atas nama Anda. Namun, jika Anda memuat ulang atau keluar dari konsol Google Cloud saat upload sedang berlangsung, upload akan dibatalkan.

Command line

gcloud CLI menggunakan upload yang dapat dilanjutkan dalam perintah gcloud storage cp dan gcloud storage rsync saat mengupload data ke Cloud Storage. Jika proses upload terganggu, Anda dapat melanjutkannya dengan menjalankan perintah yang sama seperti yang digunakan untuk memulai upload. Saat melanjutkan upload yang menyertakan beberapa file, gunakan flag --no-clobber untuk mencegah upload ulang file yang sudah berhasil diselesaikan.

Library klien

Saat melakukan upload yang dapat dilanjutkan, library klien berfungsi sebagai wrapper di sekitar Cloud Storage JSON API.

C++

Fungsi di storage::Client berjalan dengan perilaku yang berbeda:

Secara default, UploadFile() akan melakukan upload yang dapat dilanjutkan saat objek berukuran lebih besar dari 20 MiB. Jika tidak, Ia akan melakukan upload sederhana atau upload multibagian. Anda dapat mengonfigurasi nilai minimum ini dengan menetapkan MaximumSimpleUploadsSizeOption saat membuat storage::Client.

8 MiB adalah ukuran buffer default, yang dapat Anda ubah dengan opsi UploadBufferSizeOption.

Library klien C++ menggunakan ukuran buffer yang sama dengan ukuran potongan. Ukuran buffer harus merupakan kelipatan dari 256 KiB (256 x 1024 byte). Saat menggunakan WriteObject() dan UploadFile(), Anda mungkin ingin mempertimbangkan konsekuensi antara kecepatan upload dan penggunaan memori. Menggunakan buffer kecil untuk mengupload objek besar dapat memperlambat proses upload. Untuk mengetahui informasi selengkapnya tentang hubungan antara kecepatan upload dan ukuran buffer untuk C++, lihat analisis mendetail di GitHub.

C#

Saat mengupload, library klien C# selalu melakukan upload yang dapat dilanjutkan. Anda dapat memulai upload yang dapat dilanjutkan dengan CreateObjectUploader.

Library klien C# menggunakan ukuran buffer yang sama dengan ukuran potongan. Ukuran buffer default adalah 10 MB dan Anda dapat mengubah nilai ini dengan menetapkan ChunkSize pada UploadObjectOptions. Ukuran buffer harus merupakan kelipatan dari 256 KiB (256 x 1024 byte). Ukuran buffer yang lebih besar biasanya membuat upload lebih cepat, tetapi perlu diperhatikan bahwa ada kompromi antara kecepatan dan penggunaan memori.

Go

Secara default, upload yang dapat dilanjutkan terjadi secara otomatis saat file berukuran lebih besar dari 16 MiB. Anda mengubah batas untuk melakukan upload yang dapat dilanjutkan dengan Writer.ChunkSize. Upload yang dapat dilanjutkan selalu terpotong saat menggunakan library klien Go.

Upload multibagian terjadi saat objek lebih kecil dari Writer.ChunkSize atau saat Writer.ChunkSize ditetapkan ke 0, di mana pembagian file dinonaktifkan. Writer tidak dapat mencoba ulang permintaan jika ChunkSize ditetapkan ke 0.

Library klien Go menggunakan ukuran buffer yang sama dengan ukuran potongan. Ukuran buffer harus merupakan kelipatan dari 256 KiB (256 x 1024 byte). Ukuran buffer yang lebih besar biasanya membuat upload lebih cepat, tetapi perlu diperhatikan bahwa ada kompromi antara kecepatan dan penggunaan memori. Jika menjalankan beberapa upload yang dapat dilanjutkan secara serentak, Anda harus menyetel Writer.ChunkSize ke nilai yang lebih kecil dari 16 MiB untuk menghindari penggelembungan memori.

Perlu diperhatikan bahwa objek belum selesai di Cloud Storage sampai Anda memanggil Writer.Close() dan menerima respons berhasil. Writer.Close menampilkan error jika permintaan tidak berhasil.

Java

Library klien Java memiliki metode terpisah untuk upload multibagian dan dapat dilanjutkan. Metode berikut selalu melakukan upload yang dapat dilanjutkan:

Ukuran buffer default adalah 15 MiB. Anda dapat mengatur ukuran buffer baik dengan menggunakan metode WriteChannel#setChunkSize(int), atau dengan meneruskan parmeter bufferSize ke metode Storage#createFrom. Ukuran minimum buffer adalah 256 KiB. Saat memanggil WriteChannel#setChunkSize(int) secara internal, ukuran buffer digeser ke kelipatan 256 KiB.

Buffering untuk fungsi upload yang dapat dilanjutkan sebagai batas flush minimum, saat penulisan yang lebih kecil dari ukuran buffer akan di-buffer hingga operasi tulis mendorong jumlah byte yang di-buffer di atas ukuran buffer.

Jika mengupload data dalam jumlah yang lebih kecil, pertimbangkan untuk menggunakan Storage#create(BlobInfo, byte[], Storage.BlobTargetOption...) atau Storage#create(BlobInfo, byte[], int, int, Storage.BlobTargetOption...).

Node.js

Upload yang dapat dilanjutkan terjadi secara otomatis. Anda dapat menonaktifkan upload yang dapat dilanjutkan dengan menetapkan resumable di UploadOptions ke false. Upload yang dapat dilanjutkan secara otomatis dikelola saat menggunakan metode createWriteStream.

Tidak ada ukuran buffer default dan potongan upload harus dipanggil secara manual dengan menyetel opsi chunkSize pada CreateResumableUploadOptions. Jika chunkSize ditentukan, data akan dikirim dalam permintaan HTTP terpisah, masing-masing dengan payload ukuran chunkSize. Jika chunkSize tidak ditentukan dan library melakukan upload yang dapat dilanjutkan, semua data akan di-streaming ke satu permintaan HTTP.

Library klien Node.js menggunakan ukuran buffer yang sama dengan ukuran potongan. Ukuran buffer harus merupakan kelipatan dari 256 KiB (256 x 1024 byte). Ukuran buffer yang lebih besar biasanya membuat upload lebih cepat, tetapi perlu diperhatikan bahwa ada kompromi antara kecepatan dan penggunaan memori.

PHP

Secara default, upload yang dapat dilanjutkan terjadi secara otomatis saat ukuran objek lebih besar dari 5 MB. Jika tidak, upload multibagian akan terjadi. Nilai minimum ini tidak dapat diubah. Anda dapat memaksa upload yang dapat dilanjutkan dengan menetapkan opsi resumable dalam fungsi upload.

Library klien PHP menggunakan ukuran buffer yang sama dengan ukuran potongan. 256KiB adalah ukuran buffer default untuk upload yang dapat dilanjutkan, dan Anda dapat mengubah ukuran buffer dengan menetapkan properti chunkSize. Ukuran buffer harus merupakan kelipatan dari 256 KiB (256 x 1024 byte). Ukuran buffer yang lebih besar biasanya membuat upload lebih cepat, tetapi perlu diperhatikan bahwa ada kompromi antara kecepatan dan penggunaan memori.

Python

Upload yang dapat dilanjutkan terjadi jika objek lebih besar dari 8 MiB, dan upload multibagian terjadi jika objek lebih kecil dari 8 MiB Ambang batas ini tidak dapat diubah. Library klien Python menggunakan ukuran buffer yang sama dengan ukuran potongan. 100 MiB adalah ukuran buffer default yang digunakan untuk upload yang dapat dilanjutkan, dan Anda dapat mengubah ukuran buffer dengan menetapkan properti blob.chunk_size.

Untuk selalu melakukan upload yang dapat dilanjutkan, berapa pun ukuran objeknya, gunakan class storage.BlobWriter atau metode storage.Blob.open(mode='w'). Untuk metode ini, ukuran buffer default adalah 40 MiB. Anda juga dapat menggunakan Media yang Dapat Dilanjutkan untuk mengelola upload yang dapat dilanjutkan.

Ukuran potongan harus kelipatan dari 256 KiB (256 x 1024 byte). Ukuran potongan yang lebih besar biasanya membuat upload lebih cepat, tetapi perlu diperhatikan bahwa ada kompromi antara kecepatan dan penggunaan memori.

Ruby

Library klien Ruby memperlakukan semua upload sebagai upload yang tidak dapat dipotong dan dapat dilanjutkan.

REST API

JSON API

Cloud Storage JSON API menggunakan permintaan POST Object yang menyertakan parameter kueri uploadType=resumable untuk memulai upload yang dapat dilanjutkan. Permintaan ini ditampilkan sebagai URI sesi yang kemudian Anda gunakan dalam satu atau beberapa permintaan PUT Object untuk mengupload data objek. Untuk mengetahui panduan langkah demi langkah guna membuat logika Anda sendiri untuk upload yang dapat dilanjutkan, lihat Melakukan upload yang dapat dilanjutkan.

XML API

Cloud Storage XML API menggunakan permintaan POST Object yang menyertakan header x-goog-resumable: start untuk memulai upload yang dapat dilanjutkan. Permintaan ini ditampilkan sebagai URI sesi yang kemudian Anda gunakan dalam satu atau beberapa permintaan PUT Object untuk mengupload data objek. Untuk mengetahui panduan langkah demi langkah guna membuat logika Anda sendiri untuk upload yang dapat dilanjutkan, lihat Melakukan upload yang dapat dilanjutkan.

Upload yang dapat dilanjutkan dengan ukuran yang tidak diketahui

Mekanisme upload yang dapat dilanjutkan mendukung transfer yang ukuran filenya tidak diketahui sebelumnya. Hal ini dapat berguna untuk kasus seperti mengompresi objek dengan cepat saat mengupload, karena sulit untuk memprediksi ukuran file yang tepat untuk file terkompresi di awal transfer. Mekanisme ini berguna jika Anda ingin melakukan streaming transfer yang dapat dilanjutkan setelah terganggu, atau jika encoding transfer potongan tidak berfungsi untuk aplikasi Anda.

Untuk mengetahui informasi lebih lanjut, lihat Upload streaming.

Performa upload

Mengupload potongan

Jika memungkinkan, hindari membagi transfer menjadi bagian yang lebih kecil dan upload seluruh konten dalam satu bagian. Menghindari pemotongan akan menghapus biaya latensi dan biaya operasi tambahan dari pembuatan kueri offset yang dipertahankan dari setiap potongan serta meningkatkan throughput. Namun, Anda harus mempertimbangkan untuk mengupload potongan-potongan saat:

  • Data sumber dibuat secara dinamis dan Anda ingin membatasi berapa banyak data yang diperlukan untuk melakukan buffering sisi klien jika upload gagal.

  • Klien Anda memiliki batasan ukuran permintaan, seperti yang terjadi pada banyak browser.

Jika Anda menggunakan JSON atau XML API dan klien menerima error, klien dapat mengkueri server untuk offset yang dipertahankan dan melanjutkan upload byte yang tersisa dari offset tersebut. Konsol Google Cloud, Google Cloud CLI, dan library klien menangani hal ini secara otomatis untuk Anda. Lihat Cara alat dan API menggunakan upload yang dapat dilanjutkan untuk mendapatkan panduan selengkapnya tentang pemotongan untuk library klien tertentu.

Pertimbangan

Bagian ini berguna jika Anda sedang membuat klien sendiri yang mengirimkan permintaan upload yang dapat dilanjutkan langsung ke JSON atau XML API.

URI Sesi

Saat Anda memulai upload yang dapat dilanjutkan, Cloud Storage akan menampilkan URI sesi, yang Anda gunakan dalam permintaan berikutnya untuk mengupload data sebenarnya. Contoh URI sesi di JSON API adalah:

https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=my-file.jpg&upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

Contoh URI sesi di API XML adalah:

 https://storage.googleapis.com/my-bucket/my-file.jpg?upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

URI sesi ini bertindak sebagai token autentikasi, sehingga permintaan yang menggunakannya tidak perlu ditandatangani dan dapat digunakan oleh siapa saja untuk mengupload data ke bucket target tanpa autentikasi lebih lanjut. Karena itu, berhati-hatilah saat membagikan URI sesi dan hanya bagikan melalui HTTPS.

URI sesi akan berakhir setelah satu minggu, tetapi dapat dibatalkan sebelum masa berlakunya berakhir. Jika Anda membuat permintaan menggunakan URI sesi yang tidak lagi valid, Anda akan menerima salah satu error berikut:

  • Kode status 410 Gone jika masih kurang dari seminggu sejak upload dimulai.
  • Kode status 404 Not Found jika sudah lebih dari seminggu sejak upload dimulai.

Dalam kedua kasus tersebut, Anda harus memulai upload baru yang dapat dilanjutkan, mendapatkan URI sesi baru, dan memulai upload dari awal menggunakan URI sesi baru.

Pemeriksaan integritas

Sebaiknya minta pemeriksaan integritas pada objek akhir yang diupload untuk memastikan objek tersebut cocok dengan file sumber. Anda dapat melakukannya dengan menghitung ringkasan MD5 file sumber dan menambahkannya ke header permintaan Content-MD5.

Memeriksa integritas file yang diupload sangatlah penting jika Anda mengupload file yang besar dalam jangka waktu yang lama, karena ada peningkatan kemungkinan file sumber yang dimodifikasi selama upload ini.

Mencoba lagi dan mengirim ulang data

Setelah Cloud Storage mempertahankan byte dalam upload yang dapat dilanjutkan, byte tersebut tidak dapat ditimpa, dan Cloud Storage mengabaikan upaya untuk melakukannya. Karena itu, Anda tidak boleh mengirim data yang berbeda saat memundurkan ke offset yang yang Anda kirimkan sebelumnya.

Misalnya, Anda mengupload objek 100.000 byte, dan koneksi Anda terganggu. Saat memeriksa status, Anda mendapati bahwa 50.000 byte telah berhasil diupload dan dipertahankan. Jika Anda mencoba memulai ulang upload pada byte 40.000, Cloud Storage akan mengabaikan byte yang Anda kirim dari 40.000 menjadi 50.000. Cloud Storage mulai mempertahankan data yang Anda kirim pada byte 50.001.

Langkah berikutnya