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:
Client::WriteObject()
selalu menjalankan upload yang dapat dilanjutkan.Client::InsertObject()
selalu melakukan upload sederhana atau multibagian.Client::UploadFile()
dapat melakukan upload yang dapat dilanjutkan, upload sederhana, atau upload multibagian.
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:
Storage#createFrom(BlobInfo, java.io.InputStream, Storage.BlobWriteOption...)
Storage#createFrom(BlobInfo, java.io.InputStream, int, Storage.BlobWriteOption...)
Storage#createFrom(BlobInfo, java.nio.file.Path, Storage.BlobWriteOption...)
Storage#createFrom(BlobInfo, java.nio.file.Path, int, Storage.BlobWriteOption...)
Storage#writer(BlobInfo, Storage.BlobWriteOption...)
Storage#writer(java.net.URL)
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
Memilih region sesi
Upload yang dapat dilanjutkan akan disematkan di region tempat Anda memulainya. Misalnya, jika Anda memulai upload yang dapat dilanjutkan di AS dan memberikan URI sesi ke klien di Asia, upload akan tetap melalui AS. Untuk mengurangi traffic lintas region dan meningkatkan performa, Anda harus mempertahankan sesi upload yang dapat dilanjutkan di region tempat sesi tersebut dibuat.
Jika Anda menggunakan instance Compute Engine untuk memulai upload yang dapat dilanjutkan, instance tersebut harus berada di lokasi yang sama dengan bucket Cloud Storage tempat Anda mengupload. Selanjutnya, Anda dapat menggunakan layanan IP geografis untuk memilih region Compute Engine tempat Anda mengarahkan permintaan pelanggan, yang membantu menjaga traffic tetap dilokalkan ke suatu region geografis.
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
- Jalankan upload yang dapat dilanjutkan.
- Pelajari cara mencoba ulang permintaan ke Cloud Storage.
- Baca tentang jenis upload lainnya di Cloud Storage.