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 i mapping dei comandi tra i due strumenti. Per una descrizione dettagliata dei comandi gcloud storage, consulta la documentazione di riferimento gcloud storage.

Per scoprire come installare e iniziare a utilizzare gcloud CLI, consulta Installare Google Cloud CLI.

Differenze di comportamento

Le seguenti sezioni 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 in parallelo.

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 di 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 interagire con Cloud Storage e non supporta la copia di file da locale a locale. Per spostare i dati correttamente utilizzando gcloud storage, almeno un argomento (origine o destinazione) deve essere un URI di risorsa Cloud Storage. Ad esempio: gs://my-bucket.

Formattazione dell'output

I comandi gcloud storage e gsutil formattano l'output in modo diverso. Anche se le modifiche secondarie, come il formato dei log, potrebbero non interessarti, le 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 gsutil esistenti hanno comandi equivalenti in gcloud storage, con alcune eccezioni. Per un elenco completo dei gcloud storage comandi, visita la documentazione di riferimento o esegui gcloud storage --help. La seguente tabella riassume brevemente le modifiche apportate ai comandi gsutil più comuni.

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 Google Cloud console vengono riconosciute come oggetti segnaposto di 0 byte. gcloud storage cp può essere utilizzato per copiare le cartelle simulate, mentre gsutil cp non può.

Quando gestisce gli errori, gcloud storage cp tenta di copiare tutte le risorse, anche se una delle risorse non è valida o non esiste. gsutil cp potrebbe interrompere l'intera operazione non appena rileva una risorsa non valida.

Quando scarica un oggetto, gcloud storage cp crea le directory locali mancanti specificate nel percorso di destinazione. gsutil cp non riesce 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 additivi per includere hash specifici, come -c o -m. gcloud storage hash utilizza flag sottrattivi per escludere gli hash, come --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 specifico di lettura-modifica-scrittura 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 piatto 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 per ogni metadato (note anche come "chiave") hanno la prima lettera di ogni parola in maiuscolo.
  • Se un metadato di un oggetto non ha un valore, gcloud storage omette la riga dall'output.

gcloud storage restituisce sempre le date e le 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 encryption_key è impostato nel file di configurazione boto, 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 le chiavi di crittografia fornite dal cliente (CSEK) o le chiavi di crittografia gestite dal cliente (CMEK) dall'oggetto. L'oggetto viene quindi criptato con la chiave KMS predefinita del bucket o con Google-managed encryption.

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 è già in una classe di archiviazione di destinazione). gcloud storage objects update potrebbe non eseguire gli stessi controlli, il che potrebbe comportare 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 tramite pipe un elenco di directory da eliminare in modo ricorsivo devono essere testati a fondo 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 dimensioni e l'ora dell'ultima modifica corrispondono tra l'origine e la destinazione. Esegue un confronto più approfondito del checksum solo se a un oggetto manca 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 degli oggetti corrispondono, ma le ore di modifica differiscono o mancano, 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 di 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 di 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 dal formato di output 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 maggiori dettagli sui mapping di comandi e flag, consulta il riferimento alla migrazione nel repository GitHub gsutil.