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.

• Les pièces importées avec succès sont comptabilisées dans votre utilisation de l'espace de stockage mensuel.
• Vous pouvez éviter la compilation d'importations en plusieurs parties abandonnées en utilisant la gestion du cycle de vie des objets pour supprimer automatiquement les importations en plusieurs parties lorsqu'elles atteignent un âge spécifié.

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 :

• Les importations en plusieurs parties avec l'API XML disposent d'autorisations IAM spécifiques. Si vous utilisez des rôles IAM personnalisés, vous devez vous assurer que ces rôles disposent des autorisations nécessaires.

• Bien que vous puissiez lancer une importation et importer plusieurs parties, la requête de finalisation de l'importation échoue si elle conduirait à écraser un objet soumis à une obligation de conservation ou une durée de conservation non remplie.

• Vous pouvez répertorier les importations en cours dans un bucket, mais seule une importation terminée apparaît dans la liste normale des objets du bucket.

• Une partie importée peut être soumise à des frais de suppression anticipée si elle n'est jamais utilisée.

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.

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

Étape suivante

• Découvrez d'autres méthodes d'importation pour Cloud Storage.
• Découvrez comment fonctionne l'intervalle exponentiel entre les tentatives tronqué et quand relancer les requêtes.