Passer de gsutil à gcloud storage

gcloud storage (disponibilité générale) est l'outil de ligne de commande recommandé pour interagir avec Cloud Storage. Cette page vous aide à passer de gsutil à gcloud storage en vous présentant les principales différences et les mappages de commandes entre les deux outils. Pour obtenir une description détaillée de l'outil gcloud storage, consultez la documentation de référence de gcloud storage.

Pour savoir comment installer et commencer à utiliser la Google Cloud CLI, consultez Installer la Google Cloud CLI.

Différences de comportement

Les sections suivantes décrivent les différences de comportement entre gsutil et gcloud storage.

Appels parallèles

gcloud storage ne prend pas en charge l'exécution simultanée de plusieurs instances de la CLI à partir de différents terminaux.

Traitement en parallèle

gcloud storage prend en charge le traitement parallèle

Gestion des caractères génériques

gcloud storage simplifie les astérisques multiples. Si vous utilisez trois astérisques ou plus à la suite (***), ils sont traités comme un seul astérisque (*).

Gestion des buckets avec espace de noms hiérarchique

gcloud storage peut être utilisé pour créer et gérer des buckets avec l'espace de noms hiérarchique activé.

Format de sortie

Les commandes gcloud storage et gsutil formatent leur résultat différemment. Si les modifications mineures, comme le format de journalisation, ne vous affecteront peut-être pas, les différences plus importantes dans les messages d'erreur et les listes de données peuvent interrompre les scripts automatisés.

Si vous avez des scripts qui s'appuient sur l'analyse du résultat de la commande gsutil, vous devez les examiner et les mettre à jour pour le format gcloud storage avant de les migrer.

Équivalents des commandes gcloud

Toutes les commandes gsutil existantes disposent de commandes équivalentes dans gcloud storage, à quelques exceptions près. Vous pouvez obtenir la liste complète des commandes gcloud storage en consultant la documentation de référence ou en exécutant gcloud storage --help. Le tableau ci-dessous décrit brièvement les modifications apportées aux commandes gsutil les plus fréquemment utilisées.

Opération Commande gsutil Commande gcloud storage
Gérer les listes de contrôle d'accès (LCA) 
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
Opération Commande gsutil Commande gcloud storage
Concaténer des objets et afficher leur contenu 
gsutil cat
 
gcloud storage cat
Opération Commande gsutil Commande gcloud storage
Concaténer des objets en les combinant dans un nouvel objet 
gsutil compose
 
gcloud storage objects compose
Notes
Pour appliquer des conditions préalables dans gcloud storage objects compose, utilisez des flags spécifiques, tels que --if-generation-match ou --if-metageneration-match.
Opération Commande gsutil Commande gcloud storage
Copier des objets et d'autres ressources 
gsutil cp
 
gcloud storage cp
Notes

Les dossiers simulés créés à l'aide de la console Google Cloud sont reconnus comme des objets d'espace réservé de 0 octet. gcloud storage cp peut servir à copier des dossiers simulés, mais pas gsutil cp.

Lors de la gestion des erreurs, gcloud storage cp tente de copier toutes les ressources, même si l'une d'elles n'est pas valide ou n'existe pas. gsutil cp peut arrêter l'opération toute entière dès qu'il rencontre une ressource non valide.

Lorsque vous téléchargez un objet, gcloud storage cp crée tous les répertoires locaux manquants spécifiés dans le chemin de destination. gsutil cp échoue si le répertoire de destination n'existe pas.
Opération Commande gsutil Commande gcloud storage
Afficher l'espace disque total utilisé par les objets 
gsutil du
 
gcloud storage du
Opération Commande gsutil Commande gcloud storage
Calculer les hachages de fichiers 
gsutil hash
 
gcloud storage hash
Notes

gsutil hash utilise des flags d'ajout pour inclure des hachages spécifiques, tels que -c ou -m. gcloud storage hash utilise des flags de soustraction pour exclure les hachages, tels que --skip-md5 ou --skip-crc32c.
Opération Commande gsutil Commande gcloud storage
Gérer les étiquettes de bucket 
gsutil label get
gsutil label set
gsutil label ch

gcloud storage buckets describe
gcloud storage buckets update
gcloud storage buckets update
Notes

Le fait d'ajouter, de modifier et de supprimer des étiquettes dans une seule commande gsutil label ch peut donner lieu à un comportement différent de celui observé avec les opérations utilisant gcloud storage buckets update. Les scripts qui s'appuient sur un comportement de lecture-modification-écriture spécifique de gsutil doivent être testés avec soin après la transition vers gcloud storage.
Opération Commande gsutil Commande gcloud storage
Lister les buckets, les objets et les dossiers 
gsutil ls
 
gcloud storage ls
Notes

Lorsqu'un caractère générique est utilisé pour lister les objets d'un projet, gsutil ls renvoie une liste plate d'objets, tandis que gcloud storage ls renvoie les objets regroupés par nom de bucket.

Lorsque vous utilisez gcloud storage ls -L pour renvoyer des listes détaillées en tant que résultat, les comportements suivants s'appliquent :

  • La première lettre de chaque mot des étiquettes de chaque métadonnée (également appelée "clé") est en majuscule.
  • Si une métadonnée d'un objet n'a pas de valeur, gcloud storage omet cette ligne dans le résultat.

gcloud storage génère toujours des valeurs datetime en temps UTC.

gcloud storage renvoie les messages d'erreur à la fin du résultat de la commande.
Opération Commande gsutil Commande gcloud storage
Déplacer et renommer des objets ou des répertoires 
gsutil mv
 
gcloud storage mv
Opération Commande gsutil Commande gcloud storage
Réécrire les objets sur place 
gsutil rewrite
 
gcloud storage objects update
Notes

Si une encryption_key est définie dans votre fichier de configuration boto, gsutil rewrite -k applique la clé aux objets. Si encryption_key n'est pas définie, l'équivalent de gsutil rewrite -k est gcloud storage objects update --clear-encryption-key. Cela supprime de l'objet toutes les clés de chiffrement fournies par le client (CSEK) ou les clés de chiffrement gérées par le client (CMEK). L'objet est ensuite chiffré avec la clé KMS par défaut du bucket ou avec le chiffrement géré par Google.

gsutil rewrite inclut une logique permettant d'éviter de réécrire un objet si la transformation demandée ne modifie pas son état (par exemple, si l'objet se trouve déjà dans une classe de stockage cible). gcloud storage objects update peut ne pas effectuer les mêmes vérifications, ce qui peut entraîner des opérations inutiles.
Opération Commande gsutil Commande gcloud storage
Supprimer des objets ou des buckets 
gsutil rm
 
gcloud storage rm
Notes

Les alias del, delete et remove de gsutil ne sont pas pris en charge.

Il existe un problème connu pour lequel gsutil et gcloud storage se comportent différemment lorsque les flags -l et -r sont utilisés ensemble. Les scripts qui transfèrent une liste de répertoires à supprimer de manière récursive doivent être testés de manière approfondie avant de passer de gsutil à gcloud storage.
Opération Commande gsutil Commande gcloud storage
Synchroniser le contenu de deux buckets ou répertoires 
gsutil rsync
 
gcloud storage rsync
Notes

Par défaut, gsutil rsync considère qu'un objet n'a pas été modifié si sa taille et sa date de dernière modification sont les mêmes sur la source et la destination. Il n'effectue de comparaison plus approfondie des sommes de contrôle que si l'heure de modification d'un objet est manquante ou si vous forcez manuellement cette comparaison avec le flag -c. gcloud storage rsync commence par vérifier la taille et la date de la dernière modification d'un fichier. Toutefois, si les tailles des objets correspondent, mais que les dates de modification diffèrent ou sont manquantes, il effectue automatiquement une comparaison des sommes de contrôle.

Pour améliorer les performances, gcloud storage rsync effectue les opérations en parallèle par défaut. gsutil rsync s'exécute de manière séquentielle, sauf si le flag -m de premier niveau est utilisé.

gsutil rsync suit les liens symboliques par défaut. gcloud storage rsync les ignore par défaut, sauf si le flag --no-ignore-symlinks est utilisé.
Opération Commande gsutil Commande gcloud storage
Définir des métadonnées sur les objets importés 
gsutil setmeta
 
gcloud storage objects update
Notes

gsutil setmeta utilise un flag -h unique et répétable pour spécifier les métadonnées à définir ou à supprimer. gcloud storage objects update utilise des flags distincts pour chaque champ de métadonnées (par exemple, --content-type, --clear-cache-control ou --update-custom-metadata).

Dans gsutil setmeta, le flag -h est utilisé pour définir le nom complet de l'en-tête (par exemple, -h "x-goog-meta-icecreamflavor:vanilla"). Dans gcloud storage objects update, le flag --update-custom-metadata est utilisé à la place et accepte des paires clé/valeur (par exemple, --update-custom-metadata=icecreamflavor=vanilla). Pour supprimer un champ de métadonnées personnalisé, gsutil setmeta utilise -h "x-goog-meta-icecreamflavor", tandis que gcloud storage objects update utilise --remove-custom-metadata=icecreamflavor.
Opération Commande gsutil Commande gcloud storage
Afficher l'état de l'objet 
gsutil stat
 
gcloud storage objects list --stat --fetch-encrypted-object-hashes
Notes

Le format de sortie de gcloud storage objects list --stat diffère de celui de gsutil stat, et des problèmes liés à un espacement incohérent sont connus. Les scripts écrits pour analyser le résultat de gsutil stat peuvent nécessiter des ajustements pour gérer le nouveau format de sortie.

Étape suivante

Pour en savoir plus sur les mappages de commandes et de flags, consultez la documentation de référence sur la migration dans le dépôt GitHub gsutil.