Upload gabungan paralel

Salah satu strategi untuk mengupload file besar dikenal sebagai upload gabungan paralel. Dalam upload jenis ini, file dibagi menjadi 32 bagian dan bagian tersebut diupload secara paralel dengan objek sementara, di mana objek akhir dibuat ulang menggunakan objek sementara, dan objek sementara juga akan dihapus.

Upload gabungan paralel bisa jauh lebih cepat jika kecepatan jaringan dan disk bukan merupakan faktor yang membatasi. Namun, objek akhir yang disimpan di bucket Anda adalah objek gabungan yang hanya memiliki hash crc32c, bukan hash MD5. Akibatnya, Anda harus menggunakan crcmod untuk melakukan pemeriksaan integritas saat mendownload objek dengan aplikasi Python. Anda hanya boleh melakukan upload gabungan paralel jika hal berikut berlaku:

  • Anda tidak perlu memiliki hash MD5 pada objek yang diupload.

  • Setiap pengguna Python, termasuk gsutil, yang perlu mendownload objek Anda telah menginstal google-crc32c atau crcmod.

    Misalnya, jika Anda menggunakan Python untuk mengupload aset video yang hanya ditayangkan oleh aplikasi Java, upload gabungan paralel merupakan pilihan yang baik karena memiliki implementasi CRC32C yang efisien yang tersedia di Java.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk melakukan upload gabungan paralel, minta administrator Anda untuk memberi Anda peran IAM Storage Object User (roles/storage.objectUser) di bucket.

Peran Storage Admin (roles/storage.admin) berisi izin yang diperlukan untuk mengupload, membaca, dan menghapus bagian objek. Peran ini juga berisi izin yang diperlukan agar gcloud CLI dapat melakukan pemeriksaan kompatibilitas tingkat bucket dengan upload gabungan paralel. Jika Anda tidak dapat memperoleh peran Storage Admin (roles/storage.admin), Anda tetap dapat melakukan upload gabungan paralel menggunakan gcloud CLI dengan memperoleh peran Storage Object User (roles/storage.objectUser) dan menonaktifkan properti storage/parallel_composite_upload_compatibility_check. Untuk mengetahui informasi selengkapnya, lihat tab Command line di bagian Cara alat dan API menggunakan upload gabungan paralel.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran kustom atau peran bawaan lainnya.

Untuk mengetahui petunjuk cara memberikan peran di bucket, lihat Menetapkan dan mengelola kebijakan IAM di bucket.

Cara alat dan API menggunakan upload gabungan paralel

Bergantung pada cara Anda berinteraksi dengan Cloud Storage, upload gabungan paralel mungkin dikelola secara otomatis untuk Anda. Bagian ini menjelaskan perilaku upload gabungan paralel untuk berbagai alat dan memberikan informasi tentang cara mengubah perilaku tersebut.

Konsol

Konsol Google Cloud tidak melakukan upload gabungan paralel.

Command line

Properti berikut bekerja sama untuk menentukan cara dan waktu gcloud CLI melakukan upload gabungan paralel:

  • storage/parallel_composite_upload_enabled: Properti untuk mengaktifkan upload gabungan paralel. Jika False, upload gabungan paralel akan dinonaktifkan dan pemeriksaan kompatibilitas tingkat bucket akan dilewati. Jika True atau None, upload gabungan paralel akan diaktifkan untuk objek yang memenuhi kriteria yang ditentukan di properti lain dan pemeriksaan kompatibilitas akan diaktifkan. Setelan default-nya adalah None.

  • storage/parallel_composite_upload_compatibility_check: Properti untuk mengaktifkan/menonaktifkan pemeriksaan tingkat bucket untuk kompatibilitas dan keamanan dengan upload gabungan paralel. Jika True, gcloud CLI akan mengirimkan permintaan GET untuk metadata bucket tujuan sebelum mencoba upload gabungan paralel, yang mengharuskan akun utama memiliki izin storage.buckets.get. gcloud CLI hanya melakukan upload gabungan paralel saat semua kondisi berikut terpenuhi:

    Setelan default-nya adalah True. Jika False, gcloud CLI tidak akan melakukan pemeriksaan kompatibilitas.

    Menetapkan storage/parallel_composite_upload_compatibility_check ke False tidak akan menonaktifkan upload gabungan paralel. Jika storage/parallel_composite_upload_compatibility_check ditetapkan ke False dan storage/parallel_composite_upload_enabled adalah None atau True, gcloud CLI akan melewati pemeriksaan bucket dan langsung melanjutkan dengan upload gabungan paralel.

    Untuk melewati pemeriksaan ini, nonaktifkan properti storage/parallel_composite_upload_compatibility_check:

    gcloud config set storage/parallel_composite_upload_compatibility_check False

  • storage/parallel_composite_upload_threshold: Total ukuran file minimum untuk melakukan upload gabungan paralel. Setelan default-nya adalah 150 MiB.

  • storage/parallel_composite_upload_component_size: Ukuran maksimum untuk setiap objek sementara. Properti ini akan diabaikan jika total ukuran file sangat besar sehingga memerlukan lebih dari 32 bagian pada ukuran ini.

  • storage/parallel_composite_upload_component_prefix: Awalan yang digunakan saat memberi nama objek sementara. Properti ini dapat ditetapkan sebagai jalur absolut atau jalur yang terkait dengan objek akhir. Lihat deskripsi properti untuk mengetahui informasi selengkapnya. Awalan default-nya adalah jalur absolut /gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details.

Anda dapat memodifikasi properti ini dengan membuat konfigurasi bernama dan menerapkan konfigurasi per perintah menggunakan --configuration flag seluruh project atau untuk semua perintah gcloud CLI dengan menggunakan perintah gcloud config set.

Tidak diperlukan ruang disk lokal tambahan saat menggunakan gcloud CLI untuk melakukan upload gabungan paralel. Jika upload gabungan paralel gagal sebelum penyusunan, jalankan kembali perintah gcloud CLI untuk memanfaatkan upload yang dapat dilanjutkan untuk objek sementara yang gagal. Objek sementara yang berhasil diupload sebelum kegagalan tidak akan diupload ulang saat Anda melanjutkan upload.

Objek sementara diberi nama dengan cara berikut:

TEMPORARY_PREFIX/RANDOM_VALUE_HEX_DIGEST_COMPONENT_ID

Dengan keterangan:

  • TEMPORARY_PREFIX dikontrol oleh properti storage/parallel_composite_upload_component_prefix.
  • RANDOM_VALUE adalah nilai numerik acak.
  • HEX_DIGEST adalah hash yang berasal dari nama resource sumber.
  • COMPONENT_ID adalah nomor urut komponen.

Biasanya, objek sementara akan dihapus pada akhir upload gabungan paralel. Namun, agar tidak meninggalkan objek sementara, Anda harus memeriksa status keluar dari perintah gcloud CLI, dan Anda harus menghapus secara manual setiap objek sementara yang diupload sebagai bagian dari upload yang dibatalkan.

Library klien

Java

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Java API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Anda dapat melakukan upload gabungan paralel dengan menetapkan AllowParallelCompositeUpload ke true. Contoh:

import com.google.cloud.storage.transfermanager.ParallelUploadConfig;
import com.google.cloud.storage.transfermanager.TransferManager;
import com.google.cloud.storage.transfermanager.TransferManagerConfig;
import com.google.cloud.storage.transfermanager.UploadResult;
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;

class AllowParallelCompositeUpload {

  public static void parallelCompositeUploadAllowed(String bucketName, List<Path> files)
      throws IOException {
    TransferManager transferManager =
        TransferManagerConfig.newBuilder()
            .setAllowParallelCompositeUpload(true)
            .build()
            .getService();
    ParallelUploadConfig parallelUploadConfig =
        ParallelUploadConfig.newBuilder().setBucketName(bucketName).build();
    List<UploadResult> results =
        transferManager.uploadFiles(files, parallelUploadConfig).getUploadResults();
    for (UploadResult result : results) {
      System.out.println(
          "Upload for "
              + result.getInput().getName()
              + " completed with status "
              + result.getStatus());
    }
  }
}

Node.js

Untuk mengetahui informasi selengkapnya, lihat Cloud Storage Node.js API dokumentasi referensi.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Library klien Node.js tidak mendukung upload gabungan paralel. Sebagai gantinya, gunakan upload multibagian XML API.

Python

Untuk mengetahui informasi selengkapnya, lihat Cloud Storage Python API dokumentasi referensi.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

Library klien Python tidak mendukung upload gabungan paralel. Sebagai gantinya, gunakan upload multibagian XML API.

REST API

JSON API

JSON API mendukung upload bagian objek secara paralel dan menggabungkan ulang menjadi satu objek menggunakan compose operasi.

Perhatikan hal-hal berikut saat merancang kode untuk upload gabungan paralel:

  • Saat menggunakan operasi compose, Anda dapat menghapus permanen objek sumber sebagai bagian dari proses penyusunan. Gunakan opsi ini untuk meminimalkan penagihan objek sementara yang tidak perlu dilindungi oleh penghapusan sementara atau Object Versioning.

  • Untuk melindungi objek sumber dari perubahan antara permintaan upload dan penyusunan, Anda harus memberikan nomor generasi yang diharapkan untuk setiap sumber.

XML API

XML API mendukung upload bagian objek secara paralel dan menggabungkan ulang menjadi satu objek menggunakan operasi compose.

Perhatikan hal-hal berikut saat merancang kode untuk upload gabungan paralel:

  • Saat menggunakan operasi compose, objek sumber tidak terpengaruh oleh proses penyusunan.

    Artinya, jika objek sumber dimaksudkan untuk menjadi sementara, Anda harus secara eksplisit menghapusnya setelah berhasil menyelesaikan penyusunan, atau objek sumber akan tetap berada di bucket Anda dan ditagih sesuai dengan itu.

  • Untuk melindungi objek sumber dari perubahan antara permintaan upload dan penyusunan, Anda harus memberikan nomor generasi yang diharapkan untuk setiap sumber.

Pemecahan masalah

Bagian ini berisi informasi tentang cara memecahkan masalah error gcloud CLI yang dapat terjadi dengan upload gabungan paralel.

Tidak dapat memeriksa apakah bucket tujuan kompatibel dengan upload gabungan paralel

Masalah: Saat Anda mengupload file berukuran 150 MiB atau lebih besar menggunakan gcloud storage cp atau gcloud storage mv, perintah akan mencatat pesan berikut satu kali, tetapi upload berhasil diselesaikan dengan kode keluar 0:

ERROR: Cannot check if the destination bucket is compatible for running
parallel composite uploads as the user does not permission to perform GET
operation on the bucket. The operation will be performed without parallel
composite upload feature and hence might perform relatively slower.

Solusi: gcloud CLI mencoba menjalankan pemeriksaan kompatibilitas upload gabungan paralel. Akun utama tidak memiliki izin storage.buckets.get di bucket tujuan, sehingga permintaan metadata bucket ditolak. gcloud CLI menangani error secara internal dan tidak menampilkan kode status HTTP. Sebagai gantinya, gcloud CLI mencatat pesan dan kembali ke upload reguler.

Jika Anda menginginkan upload gabungan paralel, pastikan akun utama memiliki izin storage.buckets.get, storage.objects.get, dan storage.objects.delete di bucket tujuan. Izin ini dapat diberikan melalui peran Storage Admin (roles/storage.admin). Atau, jika akun utama sudah memiliki izin storage.objects.get dan storage.objects.delete melalui peran seperti Storage Object User (roles/storage.objectUser), akun tersebut dapat menetapkan properti storage/parallel_composite_upload_compatibility_check ke False untuk menonaktifkan pemeriksaan kompatibilitas.

403: does not have storage.objects.get access

Masalah: Upload file yang lebih kecil dari 150 MiB berhasil, tetapi upload file yang berukuran 150 MiB atau lebih besar gagal dengan kode keluar 1 dan error yang mirip dengan berikut ini:

HTTPError 403: PRINCIPAL does not have storage.objects.get access to
the Google Cloud Storage object.

Solusi: storage/parallel_composite_upload_compatibility_check ditetapkan ke False dan storage/parallel_composite_upload_enabled ditetapkan ke None atau True. Dalam konfigurasi ini, gcloud CLI akan melewati pemeriksaan kompatibilitas bucket dan langsung melanjutkan dengan upload gabungan paralel.

Upload objek sementara berhasil karena akun utama memiliki izin storage.objects.create. Namun, penyusunan objek sementara menjadi objek akhir memerlukan izin storage.objects.get, dan penghapusan objek sementara setelahnya memerlukan izin storage.objects.delete.

Untuk mengatasi masalah ini, pilih salah satu opsi berikut:

  • Jika Anda tidak memerlukan upload gabungan paralel, nonaktifkan:

    gcloud config set storage/parallel_composite_upload_enabled False

    Semua file diupload sebagai upload reguler, dan akun utama hanya memerlukan izin yang disertakan dalam peran Storage Object Creator (roles/storage.objectCreator). Anda dapat membiarkan storage/parallel_composite_upload_compatibility_check pada nilai apa pun.

  • Jika Anda memerlukan upload gabungan paralel, berikan izin storage.objects.get dan storage.objects.delete kepada akun utama di bucket tujuan. Izin ini dapat diberikan melalui peran Storage Object User (roles/storage.objectUser).

Jika upload yang gagal meninggalkan objek sementara di bucket Anda, hapus objek tersebut. Secara default, objek sementara menggunakan awalan gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details. Untuk menghapus objek sementara yang dihasilkan dari upload yang gagal, Anda memerlukan izin storage.objects.delete.

Perhatikan bahwa perintah gcloud storage rsync berperilaku berbeda dengan gcloud storage cp dan gcloud storage mv. Jika tujuannya adalah root bucket, seperti gs://my-bucket, gcloud storage rsync selalu memerlukan izin storage.buckets.get untuk melakukan sinkronisasi ke bucket, terlepas dari setelan upload gabungan paralel Anda. Jika tujuannya adalah subdirektori bucket, seperti gs://my-bucket/dir/, gcloud storage rsync tidak memerlukan izin storage.buckets.get, selama pemeriksaan kompatibilitas dinonaktifkan dalam setelan upload gabungan paralel Anda. Dalam skenario ini, gcloud storage rsync memerlukan izin storage.objects.get, bukan storage.buckets.get.