Retrieves a list of objects matching the criteria. Try it now or see an example .
In conjunction with the
prefix
filter, the use of the
delimiter
parameter allows the
list
method to operate like a directory listing, despite the object namespace being flat. For example, if
delimiter
were set to "/", then listing objects from a bucket that contains the objects "a/b", "a/c", "d", "e", "e/f" would return objects "d" and "e", and prefixes "a/" and "e/".
The authenticated user must have
READER
permissions on the
bucket
.
Request
HTTP request
GET https://www.googleapis.com/storage/v1/b/bucket/o
Parameters
| Parameter name | Value | Description |
|---|---|---|
| Path parameters | ||
bucket
|
string
|
Name of the bucket in which to look for objects. |
| Optional query parameters | ||
delimiter
|
string
|
Returns results in a directory-like mode.
items
will contain only objects whose names, aside from the
prefix
, do not contain
delimiter
. Objects whose names, aside from the
prefix
, contain
delimiter
will have their name, truncated after the
delimiter
, returned in
prefixes
. Duplicate
prefixes
are omitted.
|
maxResults
|
unsigned integer
|
Maximum number of
items
plus
prefixes
to return. As duplicate
prefixes
are omitted, fewer total results may be returned than requested.
|
pageToken
|
string
|
A previously-returned page token representing part of the larger set of results to view. |
prefix
|
string
|
Filter results to objects whose names begin with this prefix. |
projection
|
string
|
Set of properties to return. Defaults to
noAcl
.
Acceptable values are:
|
versions
|
boolean
|
If true, lists all versions of a file as distinct results. |
Request body
Do not supply a request body with this method.
Response
If successful, this method returns a response body with the following structure:
{
"kind": "storage#objects",
"nextPageToken": string,
"prefixes": [
string
],
"items": [
objects Resource
]
}
| Property name | Value | Description | Notes |
|---|---|---|---|
kind
|
string
|
The kind of item this is. For lists of objects, this is always
storage#objects
.
|
|
nextPageToken
|
string
|
The continuation token, used to page through large result sets. Provide this value in a subsequent request to return the next page of results. | |
prefixes[]
|
list
|
The list of prefixes of objects matching-but-not-listed up to and including the requested delimiter. | |
items[]
|
list
|
The list of items. |
Examples
Note: The code examples available for this method do not represent all supported programming languages (see the client libraries page for a list of supported languages).
Java
Uses the Java client library .
Storage.Objects.List listObjects = storage.objects().list("mybucket");
Objects objects;
do {
objects = listObjects.execute();
for (StorageObject object : objects.getItems()) {
// Do things!
}
listObjects.setPageToken(objects.getNextPageToken());
} while (null != objects.getNextPageToken());
Python
Uses the Python client library .
fields_to_return = 'nextPageToken,items(bucket,name,metadata(my-key))'
req = client.objects().list(
bucket=bucket_name,
fields=fields_to_return, # optional
maxResults=42) # optional
# If you have too many items to list in one request, list_next() will
# automatically handle paging with the pageToken.
while req is not None:
resp = req.execute()
print json.dumps(resp, indent=2)
req = client.objects().list_next(req, resp)
Ruby
Uses the Ruby client library .
# List all objects in a bucket.
page_token = '' # An empty pageToken will be ignored. maxResults is 1000 by default.
puts "List of objects in #{BUCKET}: "
until page_token.nil? do
objects_list_result = client.execute(
api_method: storage.objects.list,
parameters: {bucket: BUCKET, pageToken: page_token}
)
objects_list_result.data.items.each { |item| puts item.name }
page_token = objects_list_result.next_page_token
end
Go
Uses the Go client library .
// List all objects in a bucket. bucketName := "BUCKET_NAME" result, err := service.Objects.List(bucketName).Do() fmt.Printf("Objects in bucket %v:\n", bucketName) for _, object := range result.Items { fmt.Println(object.Name) }
Try it!
Use the APIs Explorer below to call this method on live data and see the response. Alternatively, try the standalone Explorer .