Esegui la transizione da gsutil a gcloud storage

Google Cloud CLI è lo strumento a riga di comando consigliato per interagire con Cloud Storage. Questa pagina ti aiuta a passare da gsutil ai comandi gcloud storage di gcloud CLI descrivendo le principali differenze e mappature dei comandi tra i due strumenti. Se hai script che utilizzano gsutil, puoi utilizzare le informazioni in questa pagina per aggiornarli con i comandi gcloud storage corrispondenti.

Per scoprire come iniziare a utilizzare gcloud CLI, consulta Installa Google Cloud CLI.

Per una descrizione dettagliata dei comandi gcloud storage, consulta la documentazione di riferimento di gcloud storage.

Differenze di comportamento

Le sezioni seguenti descrivono le differenze di comportamento tra gsutil e gcloud storage.

Chiamate parallele

gcloud storage non supporta le chiamate parallele utilizzando più terminali sulla stessa macchina.

Elaborazione in parallelo

gcloud storage supporta l'elaborazione parallela.

Gestione dei caratteri jolly

gcloud storage semplifica più asterischi. Se utilizzi tre o più asterischi di seguito (***), li considera come un singolo asterisco (*).

Gestione dei bucket di spazi dei nomi gerarchici

gcloud storage può essere utilizzato per creare e gestire bucket con lo spazio dei nomi gerarchico abilitato.

Supporto per la copia di file da locale a locale

gcloud storage è progettato esclusivamente per l'interazione con Cloud Storage e non supporta la copia di file da locale a locale. Per spostare correttamente i dati utilizzando gcloud storage, almeno un argomento (origine o destinazione) deve essere un URI della risorsa Cloud Storage. Ad esempio gs://my-bucket.

Formattazione dell'output

I comandi gcloud storage e gsutil formattano l'output in modo diverso. Sebbene modifiche minori come il formato di logging potrebbero non influire su di te, differenze più significative nei messaggi di errore e negli elenchi di dati possono interrompere gli script automatici.

Se hai script che si basano sull'analisi dell'output comando gsutil, devi esaminarli e aggiornarli per il formato gcloud storage prima di eseguirne la transizione.

Comandi gcloud equivalenti

Tutti i comandi di gsutil esistenti hanno comandi equivalenti in gcloud storage, con alcune eccezioni. Per un elenco completo dei comandi di gcloud storage, visita la documentazione di riferimento o esegui gcloud storage --help. La tabella riportata di seguito illustra brevemente le modifiche apportate ai comandi di gsutil più utilizzati.

Operazione Comando gsutil Comando gcloud storage
Gestisci gli elenchi di controllo dell'accesso (ACL) 
gsutil acl get
gsutil acl set
gsutil acl ch

gcloud storage RESOURCE describe --format="multi(acl:format=json)"
gcloud storage RESOURCE update --acl-file=ACL_FILE_PATH
gcloud storage RESOURCE update --add-acl-grant=GRANT
gcloud storage RESOURCE update --remove-acl-grant=GRANT
Operazione Comando gsutil Comando gcloud storage
Concatena gli oggetti e visualizza i contenuti degli oggetti 
gsutil cat
 
gcloud storage cat
Operazione Comando gsutil Comando gcloud storage
Concatena gli oggetti combinandoli in un nuovo oggetto 
gsutil compose
 
gcloud storage objects compose
Note
Per applicare le precondizioni in gcloud storage objects compose, utilizza flag specifici, come --if-generation-match o --if-metageneration-match.
Operazione Comando gsutil Comando gcloud storage
Copia oggetti e altre risorse 
gsutil cp
 
gcloud storage cp
Note

Le cartelle simulate create utilizzando la console Google Cloud vengono riconosciute come oggetti segnaposto da 0 byte. gcloud storage cp può essere utilizzato per copiare cartelle simulate, mentre gsutil cp no.

Durante la gestione degli errori, gcloud storage cp tenta di copiare tutte le risorse, anche se una di queste non è valida o non esiste. gsutil cp potrebbe interrompere l'intera operazione non appena rileva una risorsa non valida.

Quando scarichi un oggetto, gcloud storage cp crea le directory locali mancanti specificate nel percorso di destinazione. gsutil cp non va a buon fine se la directory di destinazione non esiste.
Operazione Comando gsutil Comando gcloud storage
Visualizza lo spazio su disco totale utilizzato dagli oggetti 
gsutil du
 
gcloud storage du
Operazione Comando gsutil Comando gcloud storage
Calcola gli hash dei file 
gsutil hash
 
gcloud storage hash
Note

gsutil hash utilizza flag aggiuntivi per includere hash specifici, come -c o -m. gcloud storage hash utilizza flag sottrattivi per escludere gli hash, ad esempio --skip-md5 o --skip-crc32c.
Operazione Comando gsutil Comando gcloud storage
Gestisci le etichette dei bucket 
gsutil label get
gsutil label set
gsutil label ch

gcloud storage buckets describe
gcloud storage buckets update
gcloud storage buckets update
Note

La combinazione di aggiunta, aggiornamento e rimozione di etichette in un singolo comando gsutil label ch può comportarsi in modo diverso rispetto alle operazioni equivalenti che utilizzano gcloud storage buckets update. Gli script che si basano su un comportamento di lettura-modifica-scrittura specifico di gsutil devono essere testati attentamente dopo la transizione a gcloud storage.
Operazione Comando gsutil Comando gcloud storage
Elenca bucket, oggetti e cartelle 
gsutil ls
 
gcloud storage ls
Note

Quando viene utilizzato un carattere jolly per elencare gli oggetti in un progetto, gsutil ls restituisce un elenco semplice di oggetti, mentre gcloud storage ls restituisce gli oggetti raggruppati per nome del bucket.

Quando utilizzi gcloud storage ls -L per restituire elenchi dettagliati come output, si applicano i seguenti comportamenti:

  • Le etichette di ogni metadato (noto anche come "chiave") hanno la prima lettera di ogni parola in maiuscolo.
  • Se un elemento dei metadati di un oggetto non ha un valore, gcloud storage omette la riga dall'output.

gcloud storage restituisce sempre date e ore in formato UTC.

gcloud storage restituisce eventuali messaggi di errore alla fine dell'output del comando.
Operazione Comando gsutil Comando gcloud storage
Sposta e rinomina oggetti o directory 
gsutil mv
 
gcloud storage mv
Operazione Comando gsutil Comando gcloud storage
Riscrivi gli oggetti in loco 
gsutil rewrite
 
gcloud storage objects update
Note

Se nel file di configurazione boto è impostato un encryption_key, gsutil rewrite -k applica la chiave agli oggetti. Se encryption_key non è impostato, l'equivalente di gsutil rewrite -k è gcloud storage objects update --clear-encryption-key. In questo modo, vengono rimosse dall'oggetto eventuali chiavi di crittografia fornite dal cliente (CSEK) o chiavi di crittografia gestite dal cliente (CMEK). L'oggetto viene quindi criptato con la chiave KMS predefinita del bucket o con la crittografia gestita da Google.

gsutil rewrite include la logica per saltare la riscrittura di un oggetto se la trasformazione richiesta non ne modifica lo stato (ad esempio, se l'oggetto si trova già in una classe di archiviazione di destinazione). gcloud storage objects update potrebbe non eseguire gli stessi controlli, il che potrebbe portare a operazioni non necessarie.
Operazione Comando gsutil Comando gcloud storage
Rimuovi oggetti o bucket 
gsutil rm
 
gcloud storage rm
Note

Gli alias gsutil del, delete e remove non sono supportati.

Esiste un problema noto per cui gsutil e gcloud storage si comportano in modo diverso quando i flag -l e -r vengono utilizzati insieme. Gli script che inviano un elenco di directory da eliminare in modo ricorsivo devono essere testati accuratamente prima di passare dall'utilizzo di gsutil a gcloud storage.
Operazione Comando gsutil Comando gcloud storage
Sincronizza i contenuti di due bucket o directory 
gsutil rsync
 
gcloud storage rsync
Note

Per impostazione predefinita, gsutil rsync considera un oggetto invariato se le sue dimensioni e l'ora dell'ultima modifica corrispondono tra l'origine e la destinazione. Esegue un confronto più approfondito del checksum solo se un oggetto non ha l'ora di modifica o se lo forzi manualmente con il flag -c. gcloud storage rsync inizia anche controllando le dimensioni e l'ora dell'ultima modifica di un file. Tuttavia, se le dimensioni dell'oggetto corrispondono, ma gli orari di modifica sono diversi o mancanti, esegue automaticamente un confronto del checksum.

gcloud storage rsync esegue le operazioni in parallelo per impostazione predefinita per migliorare le prestazioni. gsutil rsync viene eseguito in sequenza, a meno che non venga utilizzato il flag -m di primo livello.

gsutil rsync segue i link simbolici per impostazione predefinita. gcloud storage rsync li ignora per impostazione predefinita, a meno che non venga utilizzato il flag --no-ignore-symlinks.
Operazione Comando gsutil Comando gcloud storage
Imposta i metadati sugli oggetti caricati 
gsutil setmeta
 
gcloud storage objects update
Note

gsutil setmeta utilizza un singolo flag -h ripetibile per specificare i metadati da impostare o rimuovere. gcloud storage objects update utilizza flag distinti per ogni campo dei metadati (ad esempio: --content-type, --clear-cache-control o --update-custom-metadata).

In gsutil setmeta, il flag -h viene utilizzato per impostare il nome completo dell'intestazione (ad esempio: -h "x-goog-meta-icecreamflavor:vanilla"). In gcloud storage objects update, viene utilizzato invece il flag --update-custom-metadata e accetta coppie chiave-valore (ad esempio: --update-custom-metadata=icecreamflavor=vanilla). Per rimuovere un campo dei metadati personalizzati, gsutil setmeta utilizza -h "x-goog-meta-icecreamflavor", mentre gcloud storage objects update utilizza --remove-custom-metadata=icecreamflavor.
Operazione Comando gsutil Comando gcloud storage
Visualizza lo stato dell'oggetto 
gsutil stat
 
gcloud storage objects list --stat --fetch-encrypted-object-hashes
Note

Il formato di output di gcloud storage objects list --stat è diverso da quello di gsutil stat, con problemi noti relativi alla spaziatura incoerente. Gli script scritti per analizzare l'output di gsutil stat potrebbero richiedere modifiche per gestire il formato di output di gcloud storage objects list --stat.

Passaggi successivi

Per ulteriori dettagli sulle mappature di comandi e flag, consulta il Riferimento per la migrazione nel repository GitHub gsutil.