Caricamenti compositi paralleli

Una strategia per caricare file di grandi dimensioni è chiamata caricamenti compositi paralleli. In questo tipo di caricamento, un file viene suddiviso in un massimo di 32 chunk, i chunk vengono caricati in parallelo in oggetti temporanei, l'oggetto finale viene ricreato utilizzando gli oggetti temporanei e questi ultimi vengono eliminati.

I caricamenti compositi paralleli possono essere notevolmente più rapidi se la velocità della rete e del disco non sono fattori limitanti. Tuttavia, l'oggetto finale archiviato nel bucket è un oggetto composito, che ha solo un hash CRC32c e non un hash MD5. Di conseguenza, devi utilizzare crcmod per eseguire controlli di integrità durante il download dell'oggetto con le applicazioni Python. Esegui caricamenti compositi paralleli solo se si applicano le seguenti condizioni:

  • Non è necessario che gli oggetti caricati abbiano un hash MD5.

  • Qualsiasi utente Python, inclusi gli utenti di gsutil, che deve scaricare i tuoi oggetti deve avere installato google-crc32c o crcmod.

    Ad esempio, se utilizzi Python per caricare asset video pubblicati solo da un'applicazione Java, i caricamenti compositi paralleli sono una buona scelta perché in Java sono disponibili implementazioni efficienti di CRC32C.

In che modo gli strumenti e le API utilizzano i caricamenti compositi paralleli

A seconda di come interagisci con Cloud Storage, i caricamenti compositi paralleli potrebbero essere gestiti automaticamente per tuo conto. Questa sezione descrive il comportamento del caricamento composito parallelo per diversi strumenti e fornisce informazioni su come modificarlo.

Console

La console Google Cloud non esegue caricamenti compositi paralleli.

Riga di comando

Puoi configurare come e quando gcloud storage cp esegue caricamenti compositi paralleli modificando le seguenti proprietà:

  • storage/parallel_composite_upload_enabled: proprietà per attivare i caricamenti compositi paralleli. Se False, disattiva i caricamenti paralleli degli annunci compositi. Se True o None, esegui caricamenti compositi paralleli per gli oggetti che soddisfano i criteri definiti nelle altre proprietà. L'impostazione predefinita è None.

  • storage/parallel_composite_upload_compatibility_check: proprietà per attivare/disattivare i controlli di sicurezza. Se True, gcloud storage esegue caricamenti compositi paralleli solo se vengono soddisfatte tutte le seguenti condizioni:

    Tieni presente che, per verificare queste condizioni, l'gcloud CLI recupera i metadati del bucket di destinazione nell'ambito del comando di caricamento.

    Se False, gcloud storage non esegue alcun controllo. L'impostazione predefinita è True.

  • storage/parallel_composite_upload_threshold: la dimensione minima complessiva del file per eseguire un caricamento composito parallelo. L'impostazione predefinita è 150 MiB.

  • storage/parallel_composite_upload_component_size: le dimensioni massime per ogni oggetto temporaneo. La proprietà viene ignorata se le dimensioni totali del file sono così grandi da richiedere più di 32 chunk di queste dimensioni.

  • storage/parallel_composite_upload_component_prefix: il prefisso utilizzato per assegnare un nome agli oggetti temporanei. Questa proprietà può essere impostata come percorso assoluto o come percorso relativo all'oggetto finale. Per ulteriori informazioni, consulta la descrizione della proprietà. Il prefisso predefinito è il percorso assoluto /gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details.

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

Non è necessario spazio su disco locale aggiuntivo quando utilizzi l'interfaccia a riga di comando gcloud per eseguire caricamenti compositi paralleli. Se un caricamento composito parallelo non va a buon fine prima della composizione, esegui di nuovo il comando gcloud CLI per usufruire del vantaggio dei caricamenti riavviabili per gli oggetti temporanei che non sono riusciti. Gli oggetti temporary caricati correttamente prima dell'errore non vengono ricaricati quando riprendi il caricamento.

Gli oggetti temporanei vengono denominati nel seguente modo:

TEMPORARY_PREFIX/RANDOM_VALUE_HEX_DIGEST_COMPONENT_ID

Dove:

  • TEMPORARY_PREFIX è controllato dalla proprietà storage/parallel_composite_upload_component_prefix.
  • RANDOM_VALUE è un valore numerico casuale.
  • HEX_DIGEST è un hash derivato dal nome della risorsa di origine.
  • COMPONENT_ID è il numero sequenziale del componente.

In genere, gli oggetti temporanei vengono eliminati al termine di un caricamento composito parallelo, ma per evitare di lasciarli inutilizzati, devi controllare lo stato di uscita del comando gcloud CLI ed eliminare manualmente gli oggetti temporanei caricati nell'ambito di un caricamento interrotto.

Librerie client

Java

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

Per autenticarti a Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

Puoi eseguire caricamenti compositi paralleli impostando AllowParallelCompositeUpload su true. Ad esempio:

import com.google.cloud.storage.transfermanager.ParallelUploadConfig;
import com.google.cloud.storage.transfermanager.TransferManager;
import com.google.cloud.storage.transfermanager.TransferManagerConfig;
import com.google.cloud.storage.transfermanager.UploadResult;
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;

class AllowParallelCompositeUpload {

  public static void parallelCompositeUploadAllowed(String bucketName, List<Path> files)
      throws IOException {
    TransferManager transferManager =
        TransferManagerConfig.newBuilder()
            .setAllowParallelCompositeUpload(true)
            .build()
            .getService();
    ParallelUploadConfig parallelUploadConfig =
        ParallelUploadConfig.newBuilder().setBucketName(bucketName).build();
    List<UploadResult> results =
        transferManager.uploadFiles(files, parallelUploadConfig).getUploadResults();
    for (UploadResult result : results) {
      System.out.println(
          "Upload for "
              + result.getInput().getName()
              + " completed with status "
              + result.getStatus());
    }
  }
}

Node.js

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

Per autenticarti a Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

La libreria client Node.js non supporta i caricamenti compositi paralleli. Utilizza invece caricamenti multiparte dell'API XML.

Python

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

Per autenticarti a Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

La libreria client Python non supporta i caricamenti compositi paralleli. Utilizza invece caricamenti multiparte dell'API XML.

API REST

Sia l'API JSON sia l'API XML supportano il caricamento di frammenti di oggetti in parallelo e la loro ricombinazione in un unico oggetto utilizzando l'operazione compose.

Tieni presente quanto segue durante la progettazione del codice per i caricamenti compositi paralleli:

  • Quando utilizzi l'operazione compose, gli oggetti di origine non sono interessati dal processo di composizione.

    Ciò significa che, se sono temporanei, devi esplicitamente eliminarli dopo aver completato correttamente la composizione, altrimenti gli oggetti di origine rimangono nel bucket e vengono fatturati di conseguenza.

  • Per proteggerti dalle modifiche agli oggetti di origine tra le richieste di caricamento e composizione, devi fornire un numero di generazione previsto per ogni origine.