This page shows you how to list the objects stored in your Cloud Storage buckets, which are ordered in the list lexicographically by name.
Before you begin
To get the permissions that you need to list objects, ask your administrator
to grant you the Storage Object Viewer ( roles/storage.objectViewer
)
IAM role for the bucket that contains the objects you want to
list.
If you want to return object ACLs as part of your request or use the Google Cloud console to perform the tasks on this page, you'll need alternative roles:
-
If you want to return object ACLs as part of your request, ask your administrator to grant you the Storage Object Admin (
roles/storage.objectAdmin
) role instead of the Storage Object Viewer (roles/storage.objectViewer
) role. -
If you plan on using the Google Cloud console to perform the tasks on this page, ask your administrator to grant you the Storage Admin (
roles/storage.admin
) role instead of the Storage Object Viewer (roles/storage.objectViewer
) role.Alternatively, you can ask your administrator to grant you the Viewer (
roles/viewer
) basic role in addition to the Storage Object Viewer (roles/storage.objectViewer
) role.
These roles contain the permissions required to list objects. To see the exact permissions that are required, expand the Required permissionssection:
Required permissions
-
storage.objects.list
-
storage.objects.getIamPolicy
- This permission is only needed if you want to return object ACLs
-
storage.buckets.list
- This permission is only needed if you want to use the Google Cloud console to perform the tasks on this page.
You can also get these permissions with other predefined roles or custom roles .
For information about granting roles for buckets, see Use IAM with buckets .
List the objects in a bucket
Complete the following steps to list the objects in a bucket:
Console
- In the Google Cloud console, go to the Cloud Storage Buckets
page.
-
In the bucket list, click the name of the bucket whose contents you want to view.
-
Optional: Use filtering and sorting to limit and organize the results in your list.
Command line
Use the gcloud storage ls
command with the --recursive
flag:
gcloud storage ls --recursive gs:// BUCKET_NAME /**
Where:
-
BUCKET_NAME
is the name of the bucket whose objects you want to list. For example,my-bucket
.
The response looks like the following example:
gs://my-bucket/cats.jpeg gs://my-bucket/dogs.jpeg gs://my-bucket/thesis.txt ...
Client libraries
C++
For more information, see the Cloud Storage C++ API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .
The following sample lists all objects in a bucket:
The following sample lists objects with a given prefix:
C#
For more information, see the Cloud Storage C# API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .
The following sample lists all objects in a bucket:
The following sample lists objects with a given prefix:
Go
For more information, see the Cloud Storage Go API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .
The following sample lists all objects in a bucket:
The following sample lists objects with a given prefix:
Java
For more information, see the Cloud Storage Java API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .
The following sample lists all objects in a bucket:
The following sample lists objects with a given prefix:
Node.js
For more information, see the Cloud Storage Node.js API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .
The following sample lists all objects in a bucket:
The following sample lists objects with a given prefix:
PHP
For more information, see the Cloud Storage PHP API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .
The following sample lists all objects in a bucket:
The following sample lists objects with a given prefix:
Python
For more information, see the Cloud Storage Python API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .
The following sample lists all objects in a bucket:
The following sample lists objects with a given prefix:
Ruby
For more information, see the Cloud Storage Ruby API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .
The following sample lists all objects in a bucket:
The following sample lists objects with a given prefix: