Caricamenti paralleli composti

I caricamenti compositi paralleli possono aiutarti a caricare file di grandi dimensioni in modo molto più rapido quando la velocità della rete e del disco non sono fattori limitanti. In un caricamento composito parallelo, un file viene diviso 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.

Se interagisci con Cloud Storage utilizzando l'API XML, valuta la possibilità di utilizzare i caricamenti multiparte dell'API XML. I caricamenti multiparte dell'API XML supportano un numero maggiore di parti rispetto alle operazioni di composizione, hanno un potenziale inferiore di tariffe per l'eliminazione anticipata e non richiedono richieste Delete per rimuovere le parti di origine una volta assemblato l'oggetto finale.

Considerazioni

L'oggetto finale archiviato nel bucket da un caricamento composito parallelo è 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:

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

  • Qualsiasi utente Python, inclusi gli utenti di 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é in Java sono disponibili implementazioni CRC32C efficienti.

Ruoli obbligatori

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

Il ruolo Storage Admin (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 Storage Admin (roles/storage.admin), puoi comunque eseguire caricamenti compositi paralleli utilizzando gcloud CLI ottenendo il ruolo Storage Object User (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 In che modo 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 sulla concessione di ruoli sui bucket, consulta Imposta e gestisci le policy IAM sui bucket.

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

Console

La console Google Cloud non esegue caricamenti compositi paralleli.

Riga di comando

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

  • storage/parallel_composite_upload_enabled: proprietà per l'attivazione dei caricamenti compositi paralleli. Se False, disattiva i caricamenti compositi paralleli e ignora 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, il che richiede che l'entità disponga dell'autorizzazione storage.buckets.get. gcloud CLI esegue i caricamenti compositi paralleli solo se 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 disattiva 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 le dimensioni totali del file sono così grandi da richiedere più di 32 blocchi di queste dimensioni.

  • storage/parallel_composite_upload_component_prefix: il prefisso utilizzato per assegnare i nomi agli 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 comando per comando utilizzando il flag a livello di progetto --configuration o per tutti i comandi gcloud CLI utilizzando il comando gcloud config set.

Non è richiesto spazio su disco locale aggiuntivo quando utilizzi gcloud CLI 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 sfruttare i caricamenti ripristinabili per gli oggetti temporanei che non sono riusciti. Gli oggetti temporanei caricati correttamente prima dell'errore non vengono ricaricati quando riprendi il caricamento.

Gli oggetti temporanei sono 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 in giro, devi controllare lo stato di uscita dal comando gcloud CLI ed eliminare manualmente tutti 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 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 Cloud Storage Node.js.

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 multiparte 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 multiparte dell'API XML.

API REST

API JSON

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

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 del processo di composizione. Utilizza questa opzione per ridurre al minimo la fatturazione per gli oggetti temporanei che non devono essere protetti dall'eliminazione temporanea o dal controllo delle versioni degli oggetti.

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

API XML

L'API XML supporta il caricamento di blocchi di oggetti in parallelo e la loro ricombinazione in un unico oggetto utilizzando 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 devono essere temporanei, devi eliminarli esplicitamente una volta completata la composizione, altrimenti gli oggetti di origine rimangono nel bucket e vengono fatturati di conseguenza.

  • Per proteggerti da modifiche agli oggetti di origine tra le richieste di caricamento e 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 almeno 150 MiB 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à del caricamento composito parallelo. L'entità non dispone dell'autorizzazione storage.buckets.get sul bucket di destinazione, pertanto la richiesta dei metadati del bucket viene rifiutata. gcloud CLI gestisce l'errore internamente e non visualizza un codice di stato HTTP. Invece, registra il messaggio e torna a un caricamento standard.

Se vuoi 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 Storage Admin (roles/storage.admin). In alternativa, se l'entità dispone già delle autorizzazioni storage.objects.get e storage.objects.delete tramite un ruolo come Storage Object User (roles/storage.objectUser), può impostare la proprietà storage/parallel_composite_upload_compatibility_check su False per disattivare il controllo di compatibilità.

403: non dispone dell'accesso storage.objects.get

Problema: i caricamenti di file di dimensioni inferiori a 150 MiB vanno a buon fine, ma i caricamenti di file di dimensioni pari o superiori a 150 MiB non vanno a buon fine 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 ignora il controllo di compatibilità del bucket e procede direttamente con un caricamento composito parallelo.

Il caricamento degli oggetti temporanei va a buon fine 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 dei caricamenti compositi paralleli, disattivali:

    gcloud config set storage/parallel_composite_upload_enabled False

    Tutti i file vengono caricati come caricamenti normali e l'entità deve disporre solo delle autorizzazioni incluse nel ruolo Storage Object Creator (roles/storage.objectCreator). Puoi lasciare storage/parallel_composite_upload_compatibility_check su 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 Storage Object User (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 generati da un caricamento non riuscito, devi disporre dell'autorizzazione storage.objects.delete.

Tieni presente che il comando gcloud storage rsync si comporta in modo diverso da gcloud storage cp e gcloud storage mv. Quando la destinazione è la radice di un 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.