Uploads de várias partes da API XML

Nesta página, você aprenderá sobre os uploads de várias partes da API XML no Cloud Storage. Esse método de upload faz upload de arquivos em partes e os agrupa em um único objeto usando uma solicitação final. Os uploads de várias partes da API XML são compatíveis com os uploads de várias partes do Amazon S3.

Visão geral

Um upload de várias partes da API XML permite fazer upload de dados em várias partes e agrupá-los em um objeto final. Esse comportamento tem várias vantagens, especialmente para arquivos grandes:

  • É possível fazer upload de partes simultaneamente, reduzindo o tempo necessário para fazer o upload dos dados completos.

  • Se uma das operações de upload falhar, você só precisará fazer um novo upload de uma parte do objeto geral, em vez de reiniciar desde o início.

  • Como o tamanho total do arquivo não é especificado antecipadamente, você pode usar uploads de várias partes da API XML para uploads de streaming ou para compactar dados rapidamente durante o upload.

Um upload de várias partes da API XML tem três etapas necessárias:

  1. Inicie o upload usando uma solicitação POST, que inclui a especificação de todos os metadados que o objeto concluído deve ter. A resposta retornará um UploadId que você usa em todas as solicitações subsequentes associadas ao upload.

  2. Faça upload dos dados usando uma ou mais solicitações PUT.

  3. Conclua o upload usando uma solicitação POST. Essa solicitação substitui qualquer objeto existente no bucket com o mesmo nome.

Não há limite para o tempo que um upload de várias partes, e as partes enviadas podem permanecer inacabadas ou inativas em um bucket.

Considerações

As limitações a seguir se aplicam ao uso de uploads de várias partes da API XML:

  • Existem limites para o tamanho mínimo e máximo de uma peça e o número de partes usadas para montar o upload concluído.
  • Condições prévias não são compatíveis com as solicitações.
  • Hashes MD5 não existem para objetos enviados usando esse método.
  • Esse método de upload não é compatível com o console do Google Cloud ou a CLI do Google Cloud.

Ao trabalhar com uploads de várias partes da API XML, tenha em mente que:

Como as bibliotecas de cliente usam uploads de várias partes da API XML

Esta seção fornece informações sobre como fazer uploads de várias partes da API XML com bibliotecas de cliente compatíveis.

Bibliotecas de cliente

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

A biblioteca de cliente do Java não é compatível com uploads de várias partes da API XML. Em vez disso, use uploads compostos paralelos.

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage Node.js.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

É possível fazer uploads de várias partes da API XML usando o método uploadFileInChunks. Exemplo:

/**
 * 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

Para mais informações, consulte a documentação de referência da API Cloud Storage Python.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

É possível fazer uploads de várias partes da API XML usando o método upload_chunks_concurrently. Exemplo:

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

A seguir