Carregamentos multipartes da API XML

Esta página aborda os carregamentos multipartes da API XML no Cloud Storage. Este método de carregamento carrega ficheiros em partes e, em seguida, junta-os num único objeto através de um pedido final. Os carregamentos multipartes da API XML são compatíveis com os carregamentos multipartes do Amazon S3.

Vista geral

Um carregamento multipartes da API XML permite-lhe carregar dados em várias partes e, em seguida, juntá-los num objeto final. Este comportamento tem várias vantagens, especialmente para ficheiros grandes:

  • Pode carregar partes em simultâneo, o que reduz o tempo necessário para carregar os dados na sua totalidade.

  • Se uma das operações de carregamento falhar, só tem de voltar a carregar uma parte do objeto geral, em vez de reiniciar desde o início.

  • Uma vez que o tamanho total do ficheiro não é especificado antecipadamente, pode usar carregamentos multipartes da API XML para carregamentos de streaming ou para comprimir dados em tempo real durante o carregamento.

Um carregamento multipartes da API XML tem três passos obrigatórios:

  1. Inicie o carregamento com um pedido POST, que inclui a especificação de quaisquer metadados que o objeto concluído deva ter. A resposta devolve um UploadId que usa em todos os pedidos subsequentes associados ao carregamento.

  2. Carregue os dados através de um ou mais pedidos PUT.

  3. Conclua o carregamento através de um pedido POST. Este pedido substitui qualquer objeto existente no contentor com o mesmo nome.

Não existe limite para a duração em que um carregamento multipartes e as respetivas partes carregadas podem permanecer inacabados ou inativos num contentor.

Considerações

Aplicam-se as seguintes limitações à utilização de carregamentos multipartes da API XML:

  • Existem limites para o tamanho mínimo de uma parte, o tamanho máximo de uma parte e o número de partes usadas para montar o carregamento concluído.
  • As condições prévias não são suportadas nos pedidos.
  • Os hashes MD5 não existem para objetos carregados através deste método.
  • Este método de carregamento não é suportado na Google Cloud consola nem na CLI do Google Cloud.

Tenha em atenção o seguinte quando trabalhar com carregamentos multipartes da API XML:

Como as bibliotecas cliente usam carregamentos multipartes da API XML

Esta secção fornece informações sobre a realização de carregamentos multipartes de API XML com bibliotecas cliente que o suportam.

Bibliotecas cliente

Java

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

A biblioteca cliente Java não suporta carregamentos multipartes da API XML. Em alternativa, use carregamentos compostos paralelos.

Node.js

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Pode fazer carregamentos multipartes da API XML através do método uploadFileInChunks. Por 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 Python do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Pode fazer carregamentos multipartes da API XML através do método upload_chunks_concurrently. Por 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}.")


if __name__ == "__main__":
    argparse = argparse.ArgumentParser(
        description="Upload a file to GCS in chunks concurrently."
    )
    argparse.add_argument(
        "--bucket_name", help="The name of the GCS bucket to upload to."
    )
    argparse.add_argument(
        "--source_filename", help="The local path to the file to upload."
    )
    argparse.add_argument(
        "--destination_blob_name", help="The name of the object in GCS."
    )
    argparse.add_argument(
        "--chunk_size",
        type=int,
        default=32 * 1024 * 1024,
        help="The size of each chunk in bytes (default: 32 MiB). The remote\
              service has a minimum of 5 MiB and a maximum of 5 GiB",
    )
    argparse.add_argument(
        "--workers",
        type=int,
        default=8,
        help="The number of worker processes to use (default: 8).",
    )
    args = argparse.parse_args()
    upload_chunks_concurrently(
        args.bucket_name,
        args.source_filename,
        args.destination_blob_name,
        args.chunk_size,
        args.workers,
    )

O que se segue?