Importations en plusieurs parties avec l'API XML

Cette page traite des importations en plusieurs parties dans Cloud Storage avec l'API XML. Cette méthode d'importation transfère les fichiers en plusieurs parties, puis les assemble en un seul objet à l'aide d'une requête finale. Les importations en plusieurs parties avec l'API XML sont compatibles avec les importations Amazon S3 en plusieurs parties.

Présentation

Une importation en plusieurs parties avec l'API XML vous permet d'importer des données en plusieurs parties, puis de les assembler en un objet final. Ce comportement présente plusieurs avantages, en particulier pour les fichiers volumineux :

  • Vous pouvez importer simultanément différentes parties, ce qui réduit le temps nécessaire à l'importation de l'ensemble des données.

  • Si l'une des opérations d'importation échoue, il vous suffit d'importer à nouveau cette partie de l'objet global, au lieu de redémarrer depuis le début.

  • Comme la taille totale du fichier n'est pas spécifiée à l'avance, vous pouvez effectuer des importations en plusieurs parties avec l'API XML pour transférer des données en flux continu ou pour compresser des données à la volée pendant l'importation.

L'importation en plusieurs parties avec l'API XML s'effectue en trois étapes :

  1. Le lancement de l'importation à l'aide d'une requête POST, qui inclut la spécification de toutes les métadonnées que doit posséder l'objet une fois terminé. La réponse renvoie un objet UploadId que vous utilisez dans toutes les requêtes suivantes associées à l'importation.

  2. L'importation des données à l'aide d'une ou plusieurs requêtes PUT.

  3. La finalisation de l'importation à l'aide d'une requête POST. Cette requête écrase tout objet existant dans le bucket et portant le même nom.

Il n'existe aucune limite à la durée d'une importation en plusieurs parties, et les parties importées peuvent être inachevées ou inactives dans un bucket.

Remarques

Les limites suivantes s'appliquent à l'utilisation des importations en plusieurs parties avec l'API XML :

  • Des limites s'appliquent à la taille minimale d'une partie, à sa taille maximale et au nombre de parties utilisées pour assembler l'importation terminée.
  • Les conditions préalables ne sont pas autorisées dans les requêtes.
  • Les hachages MD5 n'existent pas pour les objets importés à l'aide de cette méthode.
  • Cette méthode d'importation n'est pas compatible avec la console Google Cloud ni avec la Google Cloud CLI.

Tenez compte des points suivants lorsque vous utilisez les importations en plusieurs parties avec l'API XML :

Comment les bibliothèques clientes utilisent les importations en plusieurs parties avec l'API XML

Cette section fournit des informations sur l'exécution d'importations en plusieurs parties avec l'API XML avec des bibliothèques clientes compatibles.

Bibliothèques clientes

Java

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Java.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

La bibliothèque cliente Java n'est pas compatible avec les importations en plusieurs parties de l'API XML. Utilisez plutôt les importations composites parallèles.

Node.js

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Node.js.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

Vous pouvez effectuer des importations en plusieurs parties avec l'API XML à l'aide de la méthode uploadFileInChunks. Exemple :

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

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Python.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

Vous pouvez effectuer des importations en plusieurs parties avec l'API XML à l'aide de la méthode upload_chunks_concurrently. Exemple :

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

Étapes suivantes