Cette page vous explique comment répertorier les objets stockés dans vos buckets Cloud Storage, classés par ordre alphabétique dans la liste.
Avant de commencer
Pour obtenir les autorisations nécessaires pour lister des objets, demandez à votre administrateur de vous accorder le rôle IAM "Lecteur des objets Storage" (roles/storage.objectViewer
) sur le bucket contenant les objets que vous souhaitez lister.
Si vous prévoyez d'utiliser la console Google Cloud pour effectuer les tâches de cette page, demandez à votre administrateur de vous accorder le rôle de base Lecteur (roles/viewer
) en plus du rôle Lecteur des objets Storage (roles/storage.objectViewer
).
Ces rôles contiennent les autorisations requises pour regrouper des objets. Pour afficher les autorisations exactes requises, développez la section Autorisations requises :
Autorisations requises
storage.objects.list
storage.buckets.list
- Cette autorisation n'est nécessaire que si vous souhaitez utiliser la console Google Cloud pour effectuer les tâches décrites sur cette page.
Vous pouvez également obtenir ces autorisations en utilisant d'autres rôles prédéfinis ou des rôles personnalisés.
Pour en savoir plus sur l'attribution de rôles pour des buckets, consultez la page Utiliser IAM avec des buckets.
Répertorier les objets d'un bucket
Pour répertorier les objets d'un bucket, procédez comme suit :
Console
- Dans la console Google Cloud , accédez à la page Buckets de Cloud Storage.
Dans la liste des buckets, cliquez sur le nom du bucket dont vous souhaitez afficher le contenu.
(Facultatif) Utilisez le filtrage et le tri pour limiter et organiser les résultats de votre liste.
Ligne de commande
Exécutez la commande gcloud storage ls
:
gcloud storage ls gs://BUCKET_NAME
Où :
BUCKET_NAME
correspond au nom du bucket contenant les objets que vous souhaitez lister. Exemple :my-bucket
Bibliothèques clientes
C++
Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C++.
Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.
L'exemple suivant répertorie tous les objets d'un bucket :
L'exemple suivant répertorie les objets ayant un préfixe donné :
C#
Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C#.
Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.
L'exemple suivant répertorie tous les objets d'un bucket :
L'exemple suivant répertorie les objets ayant un préfixe donné :
Go
Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Go.
Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.
L'exemple suivant répertorie tous les objets d'un bucket :
L'exemple suivant répertorie les objets ayant un préfixe donné :
Java
Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Java.
Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.
L'exemple suivant répertorie tous les objets d'un bucket :
L'exemple suivant répertorie les objets ayant un préfixe donné :
Node.js
Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Node.js.
Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.
L'exemple suivant répertorie tous les objets d'un bucket :
L'exemple suivant répertorie les objets ayant un préfixe donné :
PHP
Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage PHP.
Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.
L'exemple suivant répertorie tous les objets d'un bucket :
L'exemple suivant répertorie les objets ayant un préfixe donné :
Python
Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Python.
Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.
L'exemple suivant répertorie tous les objets d'un bucket :
L'exemple suivant répertorie les objets ayant un préfixe donné :
Ruby
Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Ruby.
Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.
L'exemple suivant répertorie tous les objets d'un bucket :
L'exemple suivant répertorie les objets ayant un préfixe donné :
API REST
API JSON
Vous devez installer et initialiser gcloud CLIafin de générer un jeton d'accès pour l'en-tête
Authorization
.Utilisez
cURL
pour appeler l'API JSON avec une requête permettant de répertorier les objets :curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o"
où
BUCKET_NAME
correspond au nom du bucket dont vous souhaitez répertorier les objets. Exemple :my-bucket
Vous pouvez utiliser le paramètre de requête
includeFoldersAsPrefixes=True
pour renvoyer des dossiers gérés dans les résultats de votre liste. Lorsque vous utilisez le paramètreincludeFoldersAsPrefixes
, le paramètredelimiter
doit être défini sur/
.
API XML
Vous devez installer et initialiser gcloud CLIafin de générer un jeton d'accès pour l'en-tête
Authorization
.Utilisez
cURL
pour appeler l'API XML avec une requêteGET
Bucket :curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME?list-type=2"
où
BUCKET_NAME
correspond au nom du bucket dont vous souhaitez répertorier les objets. Exemple :my-bucket
Vous pouvez utiliser un paramètre de chaîne de requête
prefix=PREFIX
pour limiter les résultats aux objets comportant le préfixe spécifié.
Filtrer des objets
Lorsque vous listez des objets, vous pouvez utiliser des préfixes ou des suffixes dans votre demande de liste pour filtrer les objets par nom.
Console
Pour filtrer des objets par préfixe de nom à l'aide de la console Google Cloud , utilisez le champ Filtrer les objets et les dossiers de la page Informations sur le bucket.
Pour connaître les autres options de filtrage disponibles dans la console Google Cloud , consultez la section Filtrage et tri.
Ligne de commande
Vous pouvez utiliser des caractères génériques dans votre commande gcloud storage ls
pour filtrer les objets par préfixe ou suffixe. Par exemple, la commande suivante ne liste que les objets du bucket my-bucket
dont le nom commence par image
et se termine par .png
:
gcloud storage ls gs://my-bucket/image*.png
Si la requête aboutit, la réponse se présente comme suit :
gs://my-bucket/image.png gs://my-bucket/image-dog.png gs://my-bucket/image-cat.png ...
Vous pouvez utiliser des caractères génériques à double astérisque pour établir une correspondance avec zéro ou plusieurs niveaux de répertoire dans un chemin d'accès. Par exemple, la commande suivante ne liste que les objets dont le nom se termine par .jpeg
dans n'importe quel répertoire du bucket my-bucket
:
gcloud storage ls gs://my-bucket/**/*.jpeg
Si la requête aboutit, la réponse se présente comme suit :
gs://my-bucket/puppy.jpeg gs://my-bucket/pug.jpeg gs://my-bucket/pets/dog.jpeg ...
API REST
API JSON
Lorsque vous répertoriez des objets à l'aide de l'API JSON Cloud Storage, vous pouvez utiliser les paramètres de chaîne de requête prefix
ou matchGlob
pour filtrer vos résultats. Pour en savoir plus sur l'utilisation de ces paramètres de chaîne de requête, consultez la documentation de référence sur l'API JSON pour la liste des objets.
Filtrer par préfixe
Vous pouvez utiliser le paramètre prefix=PREFIX
ou le paramètre de chaîne de requête pour limiter les résultats aux objets ou aux dossiers gérés portant le préfixe spécifié. Par exemple, pour répertorier tous les objets du bucket my-bucket
avec le préfixe folder/subfolder/
, exécutez une requête de liste d'objets en utilisant l'URL "https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"
.
Utilisez la commande prefix
pour répertorier le contenu d'un dossier géré lorsque vous êtes uniquement autorisé à répertorier les objets dans un dossier géré, mais pas dans l'ensemble du bucket. Par exemple, supposons que vous disposiez du rôle IAM de lecteur des objets de l'espace de stockage (roles/storage.objectViewer
) pour le dossier géré my-bucket/my-managed-folder-a/
, mais pas pour le dossier géré my-bucket/my-managed-folder-b/
. Pour ne renvoyer que les objets de my-managed-folder-a
, vous pouvez spécifier prefix=my-managed-folder-a/
.
Lorsque vous limitez les résultats à un dossier géré et aux objets qu'il contient, vous devez terminer PREFIX
par /
(par exemple, prefix=my-managed-folder/
). Sinon, les résultats peuvent également inclure des objets adjacents au dossier géré. Dans cet exemple, vous disposez d'un bucket contenant les objets suivants :
my-bucket/abc.txt
my-bucket/abc/object.txt
Si vous spécifiez prefix=abc/
, vous pouvez renvoyer les objets my-bucket/abc/object.txt
, tandis que la spécification prefix=abc
peut renvoyer à la fois my-bucket/abc.txt
et my-bucket/abc/object.txt
.
Filtrer par expression glob
Le paramètre de chaîne de requête matchGlob=GLOB_PATTERN
permet de filtrer les résultats en fonction des objets correspondant à une expression glob spécifique. Par exemple, matchGlob=**.jpeg
peut être utilisé pour correspondre à tous les objets qui se terminent par .jpeg
.
Les requêtes qui utilisent le paramètre matchGlob
échouent si elles incluent également un paramètre delimiter
défini sur une valeur autre que /
.
Considérations relatives aux performances lors de la création d'une liste d'objets
La structure sous-jacente des buckets avec l'espace de noms hiérarchique activé influe sur les performances de l'opération de listage des objets, par rapport aux buckets avec l'espace de noms plat. Pour en savoir plus, consultez Optimiser les performances dans les buckets avec l'espace de noms hiérarchique activé.
Étapes suivantes
- Téléchargez un objet se trouvant dans votre bucket.
- Consultez et modifiez les métadonnées d'objet.
- Supprimez des objets du bucket.
- Découvrez comment paginer les résultats.