Téléchargements d'objets en plusieurs parties

L'une des stratégies de téléchargement de fichiers volumineux est appelée téléchargement d'objets en plusieurs parties. Dans ce type de téléchargement, les requêtes GET sont effectuées par plages en parallèle, en stockant des données dans un fichier de destination temporaire préalloué. Une fois toutes les parties terminées, le fichier temporaire est renommé en tant que fichier de destination.

Le téléchargement d'objets en plusieurs parties peut être considérablement plus rapide si la vitesse du réseau et du disque ne sont pas des facteurs limitants. Toutefois, les téléchargements d'objets en plusieurs parties entraînent plusieurs écritures à différents emplacements sur le disque. Par conséquent, cette stratégie de téléchargement peut dégrader les performances des disques présentant des temps de recherche lents, en particulier lors du fractionnement d'un téléchargement en beaucoup de parties. Les outils tels que la Google Cloud CLI possèdent des valeurs par défaut faibles pour le nombre de parties qu'ils créent afin de minimiser les risques d'impact sur les performances.

Les téléchargements d'objets en parties doivent toujours utiliser une somme de contrôle (CRC32C) facilement composable pour vérifier l'intégrité des données des parties. Pour effectuer des téléchargements d'objets en plusieurs parties, des outils tels que gcloud CLI nécessitent une version compilée de crcmod sur la machine effectuant le téléchargement. Si la version compilée de crcmod n'est pas disponible, gcloud CLI effectue à la place des téléchargements d'objets non divisés en plusieurs parties.

Utilisation des téléchargements d'objets en plusieurs parties par les outils et les API

Selon votre manière d'interagir avec Cloud Storage, les téléchargements d'objets en plusieurs parties peuvent être gérés automatiquement en votre nom. Cette section décrit le comportement des téléchargements d'objets en plusieurs parties pour différents outils et fournit des informations sur la façon dont vous pouvez modifier ce comportement.

Console

La console Google Cloud n'effectue pas de téléchargements d'objets en plusieurs parties.

Ligne de commande

Par défaut, gcloud storage cp active les téléchargement d'objets en plusieurs parties. Vous pouvez contrôler quand et comment gcloud CLI effectue des téléchargements d'objets en plusieurs parties en modifiant les paramètres suivants :

storage/sliced_object_download_threshold : taille totale minimale des fichiers pour effectuer le téléchargement d'un objet en plusieurs parties. Vous pouvez désactiver tous les téléchargements d'objets en plusieurs parties en définissant cette valeur sur 0.
storage/sliced_object_download_max_components : nombre maximal de parties à utiliser dans le téléchargement. Définissez 0 pour n'avoir aucune limite. Dans ce cas, le nombre de parties est déterminé uniquement par storage/sliced_object_download_component_size.
storage/sliced_object_download_component_size : taille cible de chaque partie de téléchargement. Cette propriété est ignorée si la taille totale du fichier est si importante que le téléchargement de parties de cette taille nécessiterait plus de parties que ce qui est autorisé, tel que défini dans storage/sliced_object_download_max_components.

Vous pouvez modifier ces propriétés en créant une Configuration nommée et en appliquant la configuration soit pour chaque commande à l'aide de l'option --configuration à l'échelle du projet, soit pour toutes les commandes gcloud CLI à l'aide de la commande gcloud config set.

Aucun espace disque local supplémentaire n'est requis lorsque vous utilisez gcloud CLI pour effectuer des téléchargements d'objets en plusieurs parties. Si le téléchargement échoue avant la fin, exécutez à nouveau la commande gcloud CLI pour reprendre les parties qui ont échoué. Les parties qui ont été téléchargées avant l'échec ne sont pas téléchargées lorsque vous effectuez une nouvelle tentative, sauf dans le cas où l'objet source a changé entre les tentatives de téléchargement.

Les objets téléchargés temporairement apparaissent dans le répertoire de destination avec le suffixe _.gstmp dans leur nom.

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 Configurer l'authentification pour un environnement de développement local.

Vous pouvez effectuer des téléchargements d'objets segmentés en définissant AllowDivideAndConquer sur true. Exemple :

import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.transfermanager.DownloadResult;
import com.google.cloud.storage.transfermanager.ParallelDownloadConfig;
import com.google.cloud.storage.transfermanager.TransferManager;
import com.google.cloud.storage.transfermanager.TransferManagerConfig;
import java.nio.file.Path;
import java.util.List;

class AllowDivideAndConquerDownload {

  public static void divideAndConquerDownloadAllowed(
      List<BlobInfo> blobs, String bucketName, Path destinationDirectory) {
    TransferManager transferManager =
        TransferManagerConfig.newBuilder()
            .setAllowDivideAndConquerDownload(true)
            .build()
            .getService();
    ParallelDownloadConfig parallelDownloadConfig =
        ParallelDownloadConfig.newBuilder()
            .setBucketName(bucketName)
            .setDownloadDirectory(destinationDirectory)
            .build();
    List<DownloadResult> results =
        transferManager.downloadBlobs(blobs, parallelDownloadConfig).getDownloadResults();

    for (DownloadResult result : results) {
      System.out.println(
          "Download of "
              + result.getInput().getName()
              + " completed with status "
              + result.getStatus());
    }
  }
}

Node.js

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

Vous pouvez effectuer des téléchargements d'objets segmentés à l'aide de la méthode downloadFileInChunks. Exemple :

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The ID of the GCS file to download
// const fileName = 'your-file-name';

// The path to which the file should be downloaded
// const destFileName = '/local/path/to/file.txt';

// The size of each chunk to be downloaded
// const chunkSize = 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 downloadFileInChunksWithTransferManager() {
  // Downloads the files
  await transferManager.downloadFileInChunks(fileName, {
    destination: destFileName,
    chunkSizeBytes: chunkSize,
  });

  console.log(
    `gs://${bucketName}/${fileName} downloaded to ${destFileName}.`
  );
}

downloadFileInChunksWithTransferManager().catch(console.error);

Python

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

Vous pouvez effectuer des téléchargements d'objets segmentés à l'aide de la méthode download_chunks_concurrently. Exemple :

def download_chunks_concurrently(
    bucket_name, blob_name, filename, chunk_size=32 * 1024 * 1024, workers=8
):
    """Download a single file in chunks, concurrently in a process pool."""

    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    # The file to be downloaded
    # blob_name = "target-file"

    # The destination filename or path
    # filename = ""

    # 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, but smaller files usually
    # benefit from a higher number of processes. 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(blob_name)

    transfer_manager.download_chunks_concurrently(
        blob, filename, chunk_size=chunk_size, max_workers=workers
    )

    print("Downloaded {} to {}.".format(blob_name, filename))

API REST

L'API JSON et l'API XML sont compatibles avec les requêtes GET par plages, ce qui signifie que vous pouvez utiliser l'une ou l'autre de ces API pour mettre en œuvre votre propre stratégie de téléchargement d'objets en plusieurs parties.

Afin d'empêcher la corruption des données en raison de l'évolution de l'objet source lors du téléchargement, vous devez fournir le numéro de génération de l'objet source dans chaque requête de téléchargement d'une partie de l'objet.