Esta página se ha traducido con Cloud Translation API.

Subidas multiparte de la API XML

En esta página se explica cómo realizar subidas multiparte de la API XML en Cloud Storage. Este método de subida sube los archivos por partes y, a continuación, los ensambla en un solo objeto mediante una solicitud final. Las subidas multiparte de la API XML son compatibles con las subidas multiparte de Amazon S3.

Información general

Una subida multiparte de la API XML te permite subir datos en varias partes y, después, combinarlos en un objeto final. Este comportamiento tiene varias ventajas, sobre todo en el caso de archivos grandes:

Puedes subir partes simultáneamente, lo que reduce el tiempo necesario para subir los datos por completo.
Si falla una de las operaciones de subida, solo tiene que volver a subir una parte del objeto en lugar de reiniciar desde el principio.
Como el tamaño total del archivo no se especifica de antemano, puede usar las subidas multiparte de la API XML para subidas de streaming o para comprimir datos sobre la marcha mientras se suben.

Una subida multiparte de la API XML tiene tres pasos obligatorios:

Inicia la subida con una solicitud POST, que incluye la especificación de los metadatos que debe tener el objeto completado. La respuesta devuelve un UploadId que se usa en todas las solicitudes posteriores asociadas a la subida.
Suba los datos mediante una o varias solicitudes PUT.
Completa la subida mediante una solicitud POST. Esta solicitud sobrescribe cualquier objeto del segmento que tenga el mismo nombre.

No hay límite en cuanto al tiempo que pueden permanecer sin finalizar o inactivos en un contenedor una subida multiparte y sus partes subidas.

Las partes que se suben correctamente se tienen en cuenta en el uso mensual de almacenamiento.
Para evitar que se acumulen subidas multiparte abandonadas, puedes usar la gestión del ciclo de vida de los objetos para eliminar automáticamente las subidas multiparte cuando alcancen una antigüedad determinada.

Cuestiones importantes

Se aplican las siguientes limitaciones al usar subidas multiparte de la API XML:

Hay límites en el tamaño mínimo y máximo de una parte, así como en el número de partes que se pueden usar para completar la subida.
No se admiten condiciones previas en las solicitudes.
Los hashes MD5 no existen para los objetos subidos con este método.
Este método de subida no se admite en la consola ni en la CLI de Google Cloud. Google Cloud

Ten en cuenta lo siguiente cuando trabajes con subidas multiparte de la API XML:

Las subidas multiparte de la API XML tienen permisos de gestión de identidades y accesos específicos. Si usas roles de gestión de identidades y accesos personalizados, debes asegurarte de que tengan los permisos que necesitas.
Aunque puedes iniciar una subida y subir partes, la solicitud para completar la subida falla si se sobrescribe un objeto que tiene una retención o un periodo de conservación sin cumplir.
Puedes listar las subidas en curso de un segmento, pero solo las subidas completadas aparecen en la lista normal de objetos del segmento.
Una parte subida puede estar sujeta a cargos por eliminación anticipada si no se utiliza nunca.

Cómo usan las bibliotecas de cliente las subidas multiparte de la API XML

En esta sección se proporciona información sobre cómo realizar subidas multiparte de la API XML con bibliotecas de cliente que admitan esta función.

Bibliotecas de cliente

Java

Para obtener más información, consulta la documentación de referencia de la API Java de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

La biblioteca cliente de Java no admite las subidas multiparte de la API XML. En su lugar, usa subidas compuestas paralelas.

Node.js

Para obtener más información, consulta la documentación de referencia de la API Node.js de Cloud Storage.

Puedes realizar subidas multiparte de la API XML con el método uploadFileInChunks. Por ejemplo:

/**
 * 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 obtener más información, consulta la documentación de referencia de la API Python de Cloud Storage.

Puedes realizar subidas multiparte de la API XML con el método upload_chunks_concurrently. Por ejemplo:

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,
    )

Siguientes pasos

Consulta otros métodos de subida para Cloud Storage.
Consulta información sobre el tiempo de espera exponencial truncado y cuándo volver a enviar las solicitudes.