Upload gabungan paralel

Upload komposit paralel dapat membantu Anda mengupload file besar secara signifikan lebih cepat jika kecepatan jaringan dan disk bukan merupakan faktor yang membatasi. Dalam upload gabungan paralel, 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.

Jika Anda berinteraksi dengan Cloud Storage menggunakan XML API, pertimbangkan untuk menggunakan upload multibagian XML API. Upload multibagian XML API mendukung jumlah bagian yang lebih besar daripada operasi compose, memiliki potensi biaya penghapusan awal yang lebih rendah, dan tidak memerlukan permintaan Delete untuk menghapus bagian sumber setelah objek akhir disusun.

Pertimbangan

Objek akhir yang disimpan oleh upload gabungan paralel 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 pengguna 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 diperlukan guna melakukan upload gabungan paralel, minta administrator 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 potongan objek. Peran ini juga berisi izin yang diperlukan gcloud CLI untuk melakukan pemeriksaan kompatibilitas tingkat bucket dengan upload gabungan paralel. Jika tidak bisa mendapatkan peran Storage Admin (roles/storage.admin), Anda masih dapat melakukan upload gabungan paralel menggunakan gcloud CLI dengan mendapatkan 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 komposit paralel.

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

Untuk mengetahui petunjuk tentang cara memberikan peran pada bucket, lihat Menetapkan dan mengelola kebijakan IAM pada 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 menjalankan 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, nonaktifkan upload gabungan paralel dan lewati pemeriksaan kompatibilitas level bucket. Jika True atau None, aktifkan upload gabungan paralel untuk objek yang memenuhi kriteria yang ditentukan di properti lain dan aktifkan pemeriksaan kompatibilitas. Setelan default-nya adalah None.

  • storage/parallel_composite_upload_compatibility_check: Properti untuk mengaktifkan pemeriksaan tingkat bucket untuk kompatibilitas dan keamanan dengan upload gabungan paralel. Jika True, gcloud CLI akan mengirim 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 jika 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 defaultnya adalah 150 MiB.

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

  • 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 flag seluruh project --configuration atau untuk semua perintah gcloud CLI dengan menggunakan perintah gcloud config set.

Tidak diperlukan kapasitas 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. Setiap 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, lihatDokumentasi referensi Cloud Storage Node.js API.

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, lihatDokumentasi referensi Cloud Storage Python API.

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 operasi compose.

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 untuk objek sementara yang tidak perlu dilindungi oleh penghapusan sementara atau Pembuatan Versi Objek.

  • Untuk melindungi dari perubahan pada objek sumber antara permintaan upload dan penyusunan, Anda harus memberikan nomor pembuatan 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 tersebut dimaksudkan untuk bersifat sementara, Anda harus secara eksplisit menghapusnya setelah berhasil menyelesaikan penyusunan, atau objek sumber akan tetap berada di bucket Anda dan akan ditagih sesuai penggunaan.

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

Pemecahan masalah

Bagian ini berisi informasi tentang cara memecahkan masalah error gcloud CLI yang dapat terjadi pada 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 sekali, 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 untuk metadata bucket ditolak. gcloud CLI menangani error secara internal dan tidak menampilkan kode status HTTP. Sebagai gantinya, library akan mencatat pesan ke dalam log dan beralih 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 utama 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 komposit paralel.

Objek sementara berhasil diupload karena akun utama memiliki izin storage.objects.create. Namun, menyusun objek sementara menjadi objek akhir memerlukan izin storage.objects.get, dan menghapus 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 menyinkronkan 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, asalkan pemeriksaan kompatibilitas dinonaktifkan di setelan upload gabungan paralel Anda. Dalam skenario ini, gcloud storage rsync memerlukan izin storage.objects.get, bukan storage.buckets.get.