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 décrivant 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 sur gcloud storage.

Pour savoir comment installer et commencer à utiliser Google Cloud CLI, consultez Installer 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 n'est pas compatible avec l'exécution simultanée de plusieurs instances de l&#CLI à partir de différents terminaux.

Traitement en parallèle

gcloud storage est compatible avec 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 permet de créer et de gérer des buckets avec l'espace de noms hiérarchique activé.

Format de sortie

Les commandes gcloud storage et gsutil formatent leur sortie différemment. Si les modifications mineures, comme le format de journalisation, ne vous affectent 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 de la résultat de la commande gsutil, vous devez les examiner et les mettre à jour pour le format gcloud storage avant de les transférer.

Équivalents des commandes gcloud

Toutes les commandes gsutil existantes disposent d'un équivalent 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 le contenu d'un objet 
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
Remarques
Pour appliquer des conditions préalables dans gcloud storage objects compose, utilisez des options spécifiques, telles 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
Remarques

Les dossiers simulés créés à l'aide de la console Google Cloud sont reconnus comme des objets espaces réservés de 0 octet. gcloud storage cp peut être utilisé pour copier des dossiers simulés, contrairement à 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'ensemble de l'opération dès qu'il rencontre une ressource non valide.

Lors du téléchargement d'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
Remarques

gsutil hash utilise des options additives pour inclure des hachages spécifiques, tels que -c ou -m. gcloud storage hash utilise des indicateurs de soustraction pour exclure les hachages, tels que --skip-md5 ou --skip-crc32c.
Opération Commande gsutil Commande gcloud storage
Gérer les libellés de bucket 
gsutil label get
gsutil label set
gsutil label ch

gcloud storage buckets describe
gcloud storage buckets update
gcloud storage buckets update
Remarques

La combinaison d'ajout, de mise à jour et de suppression d'étiquettes dans une seule commande gsutil label ch peut se comporter différemment des opérations équivalentes 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
Remarques

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 fiches détaillées en tant que résultat, les comportements suivants s'appliquent :

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

gcloud storage génère toujours des valeurs datetime au format UTC.

gcloud storage renvoie les messages d'erreur à la fin de la sortie 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
Remarques

Si un encryption_key est défini dans votre fichier de configuration boto, gsutil rewrite -k applique la clé aux objets. Si encryption_key n'est pas défini, l'équivalent de gsutil rewrite -k est gcloud storage objects update --clear-encryption-key. Cela supprime toutes les clés de chiffrement fournies par le client (CSEK) ou les clés de chiffrement gérées par le client (CMEK) de l'objet. 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
Remarques

Les alias del, delete et remove de gsutil ne sont pas acceptés.

Il existe un problème connu pour lequel gsutil et gcloud storage se comportent différemment lorsque les indicateurs -l et -r sont utilisés ensemble. Les scripts qui transmettent une liste de répertoires à supprimer de manière récursive doivent être minutieusement testés 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
Remarques

Par défaut, gsutil rsync considère qu'un objet n'a pas changé si sa taille et sa date de dernière modification correspondent entre la source et la destination. Il n'effectue une comparaison plus approfondie des sommes de contrôle que si un objet ne comporte pas d'heure de modification ou si vous le forcez manuellement avec l'indicateur -c. gcloud storage rsync commence également par vérifier la taille et la date/heure de la dernière modification d'un fichier. Toutefois, si les tailles des objets correspondent, mais que les dates/heures de modification diffèrent ou sont manquantes, il effectue automatiquement une comparaison de somme de contrôle.

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

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

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

Dans gsutil setmeta, l'indicateur -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, l'indicateur --update-custom-metadata est utilisé à la place et prend 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
Remarques

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