Caricamenti compositi paralleli

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

I caricamenti compositi paralleli possono essere notevolmente più veloci se la velocità di rete e del disco non è un fattore limitante. 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 i controlli di integrità durante il download dell'oggetto con le applicazioni Python. Devi eseguire caricamenti compositi paralleli solo se si applica quanto segue:

  • Per tutti gli utenti Python, inclusi gli utenti gsutil, che devono scaricare i tuoi oggetti hanno 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é sono disponibili implementazioni CRC32C efficienti in Java.

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

In che modo strumenti e 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 i diversi strumenti e fornisce informazioni su come modificare il comportamento.

Console

La console Google Cloud non esegue caricamenti compositi paralleli.

Riga di comando

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

  • storage/parallel_composite_upload_enabled: proprietà per attivare i caricamenti compositi paralleli. Se False, disabilita i caricamenti compositi paralleli. Se True o None, esegui caricamenti compositi paralleli per 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 composti paralleli solo quando vengono soddisfatte tutte le seguenti condizioni:

    Tieni presente che, per verificare queste condizioni, gcloud CLI recupera i metadati per il bucket di destinazione come parte del comando di upload.

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

  • storage/parallel_composite_upload_threshold: la dimensione minima totale del file per l'esecuzione di un caricamento composito parallelo. L'impostazione predefinita è 150 MiB.

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

  • storage/parallel_composite_upload_component_prefix: il prefisso utilizzato per la denominazione degli oggetti temporanei. Questa proprietà può essere impostata come percorso assoluto o come percorso relativo all'oggetto finale. Consulta la descrizione della proprietà per maggiori informazioni. 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 con nome e applicando la configurazione per singolo comando utilizzando il flag a livello di progetto --configuration o per tutti i comandi dell'interfaccia a riga di comando di gcloud utilizzando il comando gcloud config set.

Quando si utilizza gcloud CLI per eseguire caricamenti compositi paralleli, non è richiesto spazio aggiuntivo su disco locale. Se un caricamento composito parallelo non riesce prima della composizione, esegui di nuovo il comando gcloud CLI per sfruttare caricamenti ripristinabili per gli oggetti temporanei non riusciti. Gli oggetti temporanei 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. Tuttavia, per evitare di lasciare oggetti temporanei, devi controllare lo stato di uscita dal comando gcloud CLI ed eliminare manualmente eventuali oggetti temporanei caricati nell'ambito di un caricamento interrotto.

API REST

Sia l'API JSON che l'API XML supportano il caricamento di blocchi di oggetti in parallelo e la ricombinazione in un unico oggetto mediante l'operazione compose.

Tieni presente quanto segue quando progetti il 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 pensati per essere temporanei, devi eliminarli esplicitamente una volta completata la composizione oppure altri oggetti di origine rimangono nel bucket e vengono fatturati di conseguenza.

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

Librerie client

Java

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Cloud Storage.

Per eseguire l'autenticazione su Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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 ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js di Cloud Storage.

Per eseguire l'autenticazione su Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Cloud Storage.

Per eseguire l'autenticazione su Cloud Storage, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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