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.

• As peças enviadas são contabilizadas no seu uso de armazenamento mensal.
• É possível evitar o acúmulo de uploads de várias partes abandonados usando o Gerenciamento do ciclo de vida de objetos para remover automaticamente os uploads de várias partes quando eles atingirem uma idade específica.

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 Google Cloud ou a Google Cloud CLI.

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

• Os uploads de várias partes da API XML têm permissões do IAM específicas. Se você usa papéis de IAM personalizados, eles precisam ter as permissões necessárias.

• Embora seja possível iniciar um upload e fazer upload de partes, a solicitação para concluir o upload falhará se ela substituir um objeto que tenha uma retenção nela ou um período de armazenamento não cumprido.

• É possível listar uploads em andamento em um bucket, mas apenas um upload concluído aparecerá na lista normal de objetos no bucket.

• Uma parte enviada poderá estar sujeita a cobranças de exclusão antecipada se nunca for usada.

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.

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

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

• Conheça outros métodos de upload do Cloud Storage.
• Saiba mais sobre a espera exponencial truncada e quando repetir solicitações.