Caricamenti multiparte API XML

Questa pagina illustra i caricamenti multiparte delle API XML in Cloud Storage. Questo metodo di caricamento carica i file in parti e quindi li assembla in un singolo oggetto utilizzando una richiesta finale. I caricamenti multiparte API XML sono compatibili con i caricamenti multiparte di Amazon S3.

Panoramica

Il caricamento multiparte dell'API XML consente di caricare i dati in più parti per poi assemblarli in un oggetto finale. Questo comportamento offre diversi vantaggi, soprattutto per i file di grandi dimensioni:

  • Puoi caricare le parti contemporaneamente, riducendo il tempo necessario per caricare i dati nella loro interezza.

  • Se una delle operazioni di caricamento non va a buon fine, devi solo ricaricare una parte dell'oggetto complessivo, anziché riavviare dall'inizio.

  • Poiché le dimensioni totali del file non vengono specificate in anticipo, puoi utilizzare i caricamenti multiparte dell'API XML per i caricamenti in streaming o per comprimere i dati in tempo reale durante il caricamento.

Un caricamento multiparte in un'API XML prevede tre passaggi obbligatori:

  1. Avvia il caricamento utilizzando una richiesta POST, che include la specifica di tutti i metadati che dovrebbero essere presenti nell'oggetto completato. La risposta restituisce un elemento UploadId che utilizzi in tutte le richieste successive associate al caricamento.

  2. Carica i dati utilizzando una o più richieste PUT.

  3. Completa il caricamento utilizzando una richiesta POST. Questa richiesta sovrascrive qualsiasi oggetto esistente nel bucket con lo stesso nome.

Non esiste alcun limite al tempo per cui un caricamento multiparte e le relative parti caricate possono rimanere non completate o inattive in un bucket.

Considerazioni

All'utilizzo dei caricamenti multiparte dell'API XML si applicano le seguenti limitazioni:

  • Esistono dei limiti relativi alle dimensioni minime di un componente, alle dimensioni massime di un componente e al numero di parti utilizzate per assemblare il caricamento completato.
  • Le condizioni preliminari non sono supportate nelle richieste.
  • Gli hash MD5 non esistono per gli oggetti caricati utilizzando questo metodo.
  • Questo metodo di caricamento non è supportato nella console Google Cloud o in Google Cloud CLI.

Tieni presente quanto segue quando lavori con i caricamenti multiparte dell'API XML:

In che modo le librerie client utilizzano i caricamenti multiparte dell'API XML

Questa sezione fornisce informazioni sull'esecuzione di caricamenti multiparte dell'API XML con le librerie client che la supportano.

Librerie client

Java

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Cloud Storage.

Per eseguire l'autenticazione su Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

La libreria client Java non supporta i caricamenti multiparte API XML. Utilizza invece i caricamenti compositi paralleli.

Node.js

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js di Cloud Storage.

Per eseguire l'autenticazione su Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Puoi eseguire caricamenti multiparte dell'API XML utilizzando il metodo uploadFileInChunks. Ad esempio:

/**
 * 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 fileName = '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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Cloud Storage.

Per eseguire l'autenticazione su Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Puoi eseguire caricamenti multiparte dell'API XML utilizzando il metodo upload_chunks_concurrently. Ad esempio:

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}.")

Passaggi successivi