Download di oggetti sezionati

Una strategia per scaricare file di grandi dimensioni è chiamata download di oggetti suddivisi. In questo tipo di download, le richieste GET con intervallo vengono effettuate in parallelo, memorizzando i dati in un file di destinazione temporaneo preallocato. Una volta completato il download di tutte le suddivisioni, il file temporaneo viene rinominato nel file di destinazione.

I download di oggetti suddivisi sono progettati per accelerare il download di un intero oggetto trasferendo le sue parti contemporaneamente. Non puoi utilizzare i download di oggetti suddivisi per scaricare solo una suddivisione o un intervallo di byte specifico di un oggetto. Per scaricare o leggere una parte specifica di un oggetto, consulta Scaricare una parte di un oggetto o Leggere oggetti.

I download di oggetti suddivisi possono essere notevolmente più veloci se la velocità di rete e del disco non sono fattori limitanti. Tuttavia, i download di oggetti suddivisi causano più scritture in varie posizioni sul disco, quindi questa strategia di download può peggiorare le prestazioni dei dischi con tempi di ricerca lenti, soprattutto quando si suddivide un download in un numero elevato di suddivisioni. Strumenti come Google Cloud CLI hanno valori predefiniti bassi per il numero di suddivisioni che creano per ridurre al minimo la possibilità di impatti sulle prestazioni.

Verificare l'integrità dei dati

I download di oggetti suddivisi devono sempre utilizzare un checksum componibile veloce (CRC32C) per verificare l'integrità dei dati delle suddivisioni. Per eseguire i download di oggetti suddivisi, strumenti come gcloud CLI richiedono una versione compilata di crcmod sulla macchina che esegue il download. Se crcmod compilato non è disponibile, gcloud CLI esegue invece download di oggetti non suddivisi.

Per ulteriori informazioni su come eseguire la convalida dei dati per le letture degli oggetti, consulta Checksum per le letture dei dati.

Come gli strumenti e le API utilizzano i download di oggetti suddivisi

A seconda di come interagisci con Cloud Storage, i download di oggetti suddivisi potrebbero essere gestiti automaticamente per tuo conto. Questa sezione descrive il comportamento di download di oggetti suddivisi per diversi strumenti e fornisce informazioni su come modificare il comportamento.

Console

La Google Cloud console non esegue download di oggetti suddivisi.

Riga di comando

Per impostazione predefinita, gcloud storage cp abilita i download di oggetti suddivisi. Puoi controllare come e quando gcloud CLI esegue i download di oggetti suddivisi modificando le seguenti proprietà:

  • storage/sliced_object_download_threshold: la dimensione totale minima del file per eseguire un download di oggetti suddivisi. Puoi disabilitare tutti i download di oggetti suddivisi impostando questo valore su 0.

  • storage/sliced_object_download_max_components: il numero massimo di suddivisioni da utilizzare nel download. Imposta 0 per nessun limite, nel qual caso il numero di suddivisioni è determinato esclusivamente da storage/sliced_object_download_component_size.

  • storage/sliced_object_download_component_size: la dimensione di destinazione per ogni suddivisione di download. Questa proprietà viene ignorata se la dimensione totale del file è così grande che il download di suddivisioni di questa dimensione richiederebbe più suddivisioni di quelle consentite, come impostato in storage/sliced_object_download_max_components.

Puoi modificare queste proprietà creando una configurazione denominata e applicandola per ogni comando utilizzando il flag --configuration a livello di progetto o per tutti i comandi gcloud CLI utilizzando il comando gcloud config set.

Quando utilizzi gcloud CLI per eseguire i download di oggetti suddivisi, non è necessario spazio su disco locale aggiuntivo. Se il download non viene completato, esegui di nuovo il comando per riprendere le suddivisioni non riuscite. Le suddivisioni scaricate correttamente prima dell'errore non vengono scaricate di nuovo quando riprovi, tranne nel caso in cui l'oggetto di origine sia cambiato tra i tentativi di download.

Gli oggetti scaricati temporaneamente vengono visualizzati nella directory di destinazione con il suffisso _.gstmp nel nome.

Librerie client

Java

Per saperne di più, consulta la documentazione di riferimento dell'API Java Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

Puoi eseguire i download di oggetti suddivisi impostando AllowDivideAndConquer su true. Ad esempio:

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

Per saperne di più, consulta la documentazione di riferimento dell'Node.js API di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

Puoi eseguire i download di oggetti suddivisi utilizzando il downloadFileInChunks metodo. Ad esempio:

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

Per saperne di più, consulta la documentazione di riferimento dell' API Python di Cloud Storage.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

Puoi eseguire i download di oggetti suddivisi utilizzando il download_chunks_concurrently metodo. Ad esempio:

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

Sia l'API JSON che l'API XML supportano le richieste con intervallo GET, il che significa che puoi utilizzare una delle due API per implementare la tua strategia di download di oggetti suddivisi.

Per proteggerti dal danneggiamento dei dati dovuto alla modifica dell'oggetto di origine durante il download, devi fornire il numero di generazione dell'oggetto di origine in ogni richiesta di download per una suddivisione dell'oggetto.