Caricamenti paralleli composti

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 blocchi, i blocchi vengono caricati in parallelo in 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à 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 i controlli di integrità quando scarichi l'oggetto con le applicazioni Python. Dovresti eseguire i caricamenti compositi paralleli solo se si verificano le seguenti condizioni:

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

  • Qualsiasi utente Python, inclusi gli utenti gsutil, che deve scaricare i tuoi oggetti ha 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.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per eseguire i caricamenti compositi paralleli, chiedi all'amministratore di concederti il ruolo IAM Utente oggetti Storage (roles/storage.objectUser) sul bucket.

Il ruolo Amministratore Storage (roles/storage.admin) contiene le autorizzazioni necessarie per caricare, leggere ed eliminare i blocchi di oggetti. Contiene anche l'autorizzazione richiesta per gcloud CLI per eseguire un controllo di compatibilità a livello di bucket con i caricamenti compositi paralleli. Se non riesci a ottenere il ruolo Amministratore Storage (roles/storage.admin), puoi comunque eseguire i caricamenti compositi paralleli utilizzando gcloud CLI ottenendo il ruolo Utente oggetti Storage (roles/storage.objectUser) e disattivando la proprietà storage/parallel_composite_upload_compatibility_check. Per saperne di più, consulta la scheda Riga di comando nella sezione Come gli strumenti e le API utilizzano i caricamenti compositi paralleli.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Per istruzioni su come concedere i ruoli sui bucket, consulta Impostare e gestire le policy IAM sui bucket.

Come 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 dei caricamenti compositi paralleli per diversi strumenti e fornisce informazioni su come modificare il comportamento.

Console

La Google Cloud console non esegue caricamenti compositi paralleli.

Riga di comando

Le seguenti proprietà funzionano insieme per determinare come e quando gcloud CLI esegue i caricamenti compositi paralleli:

  • storage/parallel_composite_upload_enabled: proprietà per abilitare i caricamenti compositi paralleli. Se False, disabilita i caricamenti compositi paralleli e salta i controlli di compatibilità a livello di bucket. Se True o None, abilita i caricamenti compositi paralleli per gli oggetti che soddisfano i criteri definiti nelle altre proprietà e abilita i controlli di compatibilità. L'impostazione predefinita è None.

  • storage/parallel_composite_upload_compatibility_check: proprietà per attivare/disattivare i controlli a livello di bucket per la compatibilità e la sicurezza con i caricamenti compositi paralleli. Se True, gcloud CLI invia una richiesta GET per i metadati del bucket di destinazione prima di tentare un caricamento composito parallelo, che richiede che l'entità disponga dell'autorizzazione storage.buckets.get. gcloud CLI esegue i caricamenti compositi paralleli solo quando sono soddisfatte tutte le seguenti condizioni:

    L'impostazione predefinita è True. Se False, gcloud CLI non esegue il controllo di compatibilità.

    L'impostazione di storage/parallel_composite_upload_compatibility_check su False non disabilita i caricamenti compositi paralleli. Quando storage/parallel_composite_upload_compatibility_check è impostato su False e storage/parallel_composite_upload_enabled è None o True, gcloud CLI salta il controllo del bucket e procede direttamente con un caricamento composito parallelo.

    Per saltare questo controllo, disattiva la proprietà storage/parallel_composite_upload_compatibility_check:

    gcloud config set storage/parallel_composite_upload_compatibility_check False

  • storage/parallel_composite_upload_threshold: la dimensione totale minima del file per eseguire 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 la dimensione totale del file è così grande da richiedere più di 32 blocchi a questa dimensione.

  • storage/parallel_composite_upload_component_prefix: il prefisso utilizzato per denominare gli oggetti temporanei. Questa proprietà può essere impostata come percorso assoluto o come percorso relativo all'oggetto finale. Per saperne di più, 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 per ogni comando utilizzando il --configuration flag a livello di progetto o per tutti i comandi gcloud CLI utilizzando il gcloud config set comando.

Quando utilizzi gcloud CLI per eseguire caricamenti compositi paralleli, non è necessario spazio su disco locale aggiuntivo. Se un caricamento composito parallelo non riesce prima della composizione, esegui di nuovo il comando gcloud CLI per sfruttare i 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, ma per evitare di lasciare oggetti temporanei, 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 JavaCloud 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 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 Node.js 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.

La libreria client Node.js non supporta i caricamenti compositi paralleli. Utilizza invece i caricamenti in più parti dell'API XML.

Python

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

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.

La libreria client Python non supporta i caricamenti compositi paralleli. Utilizza invece i caricamenti in più parti dell'API XML.

API REST

API JSON

L'API JSON supporta il caricamento parallelo dei blocchi di oggetti e la loro ricombinazione in un singolo oggetto utilizzando l' compose operazione.

Tieni presente quanto segue quando progetti il codice per i caricamenti compositi paralleli:

  • Quando utilizzi l'operazione compose, puoi eliminare definitivamente gli oggetti di origine nell'ambito della procedura di composizione. Utilizza questa opzione per ridurre al minimo la fatturazione degli oggetti temporanei che non devono essere protetti dall'eliminazione temporanea o dal controllo delle versioni degli oggetti.

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

API XML

L'API XML supporta il caricamento parallelo dei blocchi di oggetti e la loro ricombinazione in un singolo oggetto utilizzando l' compose operazione.

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 dalla procedura di composizione.

    Ciò significa che, se devono essere temporanei, devi esplicitamente eliminarli una volta completata 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 di composizione, devi fornire un numero di generazione previsto per ogni origine.

Risoluzione dei problemi

Questa sezione contiene informazioni su come risolvere i problemi relativi agli errori di gcloud CLI che possono verificarsi con i caricamenti compositi paralleli.

Impossibile verificare se il bucket di destinazione è compatibile con i caricamenti compositi paralleli

Problema: quando carichi un file di 150 MiB o più utilizzando gcloud storage cp o gcloud storage mv, il comando registra il seguente messaggio una volta, ma il caricamento viene completato correttamente con il codice di uscita 0:

ERROR: Cannot check if the destination bucket is compatible for running
parallel composite uploads as the user does not permission to perform GET
operation on the bucket. The operation will be performed without parallel
composite upload feature and hence might perform relatively slower.

Soluzione: gcloud CLI sta tentando di eseguire il controllo di compatibilità dei caricamenti compositi paralleli. L'entità non dispone dell'autorizzazione storage.buckets.get sul bucket di destinazione, pertanto la richiesta dei metadati del bucket viene negata. gcloud CLI gestisce l'errore internamente e non visualizza un codice di stato HTTP. Al contrario, registra il messaggio e torna a un caricamento normale.

Se vuoi eseguire caricamenti compositi paralleli, assicurati che l'entità disponga delle autorizzazioni storage.buckets.get, storage.objects.get e storage.objects.delete sul bucket di destinazione. Queste autorizzazioni possono essere concesse tramite il ruolo Amministratore Storage (roles/storage.admin). In alternativa, se l'entità dispone già delle autorizzazioni storage.objects.get e storage.objects.delete tramite un ruolo come Utente oggetti Storage (roles/storage.objectUser), può impostare la proprietà storage/parallel_composite_upload_compatibility_check su False per disattivare il controllo di compatibilità.

403: does not have storage.objects.get access

Problema: i caricamenti di file di dimensioni inferiori a 150 MiB vengono completati, ma i caricamenti di file di dimensioni pari o superiori a 150 MiB non riescono con il codice di uscita 1 e un errore simile al seguente:

HTTPError 403: PRINCIPAL does not have storage.objects.get access to
the Google Cloud Storage object.

Soluzione: storage/parallel_composite_upload_compatibility_check è impostato su False e storage/parallel_composite_upload_enabled è impostato su None o True. In questa configurazione, gcloud CLI salta il controllo di compatibilità del bucket e procede direttamente con un caricamento composito parallelo.

Il caricamento degli oggetti temporanei viene completato correttamente perché l'entità dispone dell'autorizzazione storage.objects.create. Tuttavia, la composizione degli oggetti temporanei nell'oggetto finale richiede l'autorizzazione storage.objects.get, mentre l'eliminazione degli oggetti temporanei richiede l'autorizzazione storage.objects.delete.

Per risolvere il problema, scegli una delle seguenti opzioni:

  • Se non hai bisogno di caricamenti compositi paralleli, disattivali:

    gcloud config set storage/parallel_composite_upload_enabled False

    Tutti i file vengono caricati come caricamenti normali e l'entità necessita solo delle autorizzazioni incluse nel ruolo Creatore oggetti Storage (roles/storage.objectCreator). Puoi lasciare storage/parallel_composite_upload_compatibility_check con qualsiasi valore.

  • Se hai bisogno di caricamenti compositi paralleli, concedi all'entità le autorizzazioni storage.objects.get e storage.objects.delete sul bucket di destinazione. Queste autorizzazioni possono essere concesse tramite il ruolo Utente oggetti Storage (roles/storage.objectUser).

Se il caricamento non riuscito ha lasciato oggetti temporanei nel bucket, eliminali. Per impostazione predefinita, gli oggetti temporanei utilizzano il prefisso gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details. Per eliminare gli oggetti temporanei risultanti da un caricamento non riuscito, devi disporre dell'autorizzazione storage.objects.delete.

Tieni presente che il gcloud storage rsync comando si comporta in modo diverso da gcloud storage cp e gcloud storage mv. Quando la destinazione è una radice del bucket, ad esempio gs://my-bucket, gcloud storage rsync richiede sempre l'autorizzazione storage.buckets.get per la sincronizzazione con il bucket, indipendentemente dalle impostazioni di caricamento composito parallelo. Quando la destinazione è una sottodirectory del bucket, ad esempio gs://my-bucket/dir/, gcloud storage rsync non richiede l'autorizzazione storage.buckets.get, a condizione che il controllo di compatibilità sia disattivato nelle impostazioni di caricamento composito parallelo. In questo scenario, gcloud storage rsync richiede l'autorizzazione storage.objects.get anziché storage.buckets.get.