Upload multibagian XML API

Halaman ini membahas upload multibagian XML API di Cloud Storage. Metode upload ini mengupload file dalam beberapa bagian, lalu menyusunnya menjadi satu objek menggunakan permintaan akhir. Upload multibagian XML API kompatibel dengan upload multibagian Amazon S3.

Ringkasan

Upload multibagian XML API memungkinkan Anda mengupload data dalam beberapa bagian, lalu menyusunnya menjadi objek akhir. Perilaku ini memiliki beberapa keuntungan, terutama untuk file berukuran besar:

  • Anda dapat mengupload beberapa bagian secara bersamaan, sehingga mengurangi waktu yang diperlukan untuk mengupload data secara keseluruhan.

  • Jika salah satu operasi upload gagal, Anda hanya perlu mengupload ulang sebagian dari keseluruhan objek, tidak perlu memulai ulang dari awal.

  • Karena total ukuran file tidak ditentukan di awal, Anda dapat menggunakan upload multibagian XML API untuk upload streaming atau untuk mengompresi data dengan cepat saat mengupload.

Upload multibagian XML API memiliki tiga langkah yang diperlukan:

  1. Mulai upload menggunakan permintaan POST, yang mencakup penentuan metadata apa pun yang seharusnya dimiliki objek yang sudah selesai. Respons akan menampilkan UploadId yang Anda gunakan di semua permintaan berikutnya yang terkait dengan upload.

  2. Upload data menggunakan satu atau beberapa permintaan PUT.

  3. Selesaikan upload menggunakan permintaan POST. Permintaan ini akan menimpa objek apa pun yang ada di bucket dengan nama yang sama.

Tidak ada batasan durasi upload multibagian dan bagian yang diuploadnya tetap dalam status tidak selesai atau tidak ada aktivitas dalam bucket.

Pertimbangan

Batasan berikut berlaku untuk penggunaan upload multibagian XML API:

  • Ada batas ukuran minimum suatu bagian, ukuran maksimum suatu bagian, dan jumlah bagian yang digunakan untuk menyusun upload yang selesai.
  • Prasyarat tidak didukung dalam permintaan.
  • Hash MD5 tidak ada untuk objek yang diupload menggunakan metode ini.
  • Metode upload ini tidak didukung di konsol Google Cloud atau Google Cloud CLI.

Perhatikan hal berikut saat menggunakan upload multibagian XML API:

Cara library klien menggunakan upload multibagian XML API

Bagian ini memberikan informasi tentang cara melakukan upload multibagian XML API dengan library klien yang mendukungnya.

Library klien

Java

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

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

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

Node.js

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

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

Anda dapat melakukan upload multibagian XML API menggunakan metode uploadFileInChunks. Contoh:

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The path of file to upload
// const filePath = 'path/to/your/file';

// The size of each chunk to be uploaded
// const chunkSize = 32 * 1024 * 1024;

// Imports the Google Cloud client library
const {Storage, TransferManager} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

// Creates a transfer manager client
const transferManager = new TransferManager(storage.bucket(bucketName));

async function uploadFileInChunksWithTransferManager() {
  // Uploads the files
  await transferManager.uploadFileInChunks(filePath, {
    chunkSizeBytes: chunkSize,
  });

  console.log(`${filePath} uploaded to ${bucketName}.`);
}

uploadFileInChunksWithTransferManager().catch(console.error);

Python

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

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

Anda dapat melakukan upload multibagian XML API menggunakan metode upload_chunks_concurrently. Contoh:

def upload_chunks_concurrently(
    bucket_name,
    source_filename,
    destination_blob_name,
    chunk_size=32 * 1024 * 1024,
    workers=8,
):
    """Upload a single file, in chunks, concurrently in a process pool."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The path to your file to upload
    # source_filename = "local/path/to/file"

    # The ID of your GCS object
    # destination_blob_name = "storage-object-name"

    # The size of each chunk. The performance impact of this value depends on
    # the use case. The remote service has a minimum of 5 MiB and a maximum of
    # 5 GiB.
    # chunk_size = 32 * 1024 * 1024 (32 MiB)

    # The maximum number of processes to use for the operation. The performance
    # impact of this value depends on the use case. Each additional process
    # occupies some CPU and memory resources until finished. Threads can be used
    # instead of processes by passing `worker_type=transfer_manager.THREAD`.
    # workers=8

    from google.cloud.storage import Client, transfer_manager

    storage_client = Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(destination_blob_name)

    transfer_manager.upload_chunks_concurrently(
        source_filename, blob, chunk_size=chunk_size, max_workers=workers
    )

    print(f"File {source_filename} uploaded to {destination_blob_name}.")

Langkah selanjutnya