list_buckets¶
Operation¶
async
¶
list_buckets(input: ListBucketsInput, plugins: list[Plugin] | None = None) -> ListBucketsOutput
Note
This operation is not supported for directory buckets.
Returns a list of all buckets owned by the authenticated sender of the
request. To grant IAM permission to use this operation, you must add the
s3:ListAllMyBuckets policy action.
For information about Amazon S3 buckets, see Creating, configuring, and working with Amazon S3 buckets.
Warning
We strongly recommend using only paginated ListBuckets requests.
Unpaginated ListBuckets requests are only supported for Amazon Web
Services accounts set to the default general purpose bucket quota of
10,000. If you have an approved general purpose bucket quota above
10,000, you must send paginated ListBuckets requests to list your
account's buckets. All unpaginated ListBuckets requests will be
rejected for Amazon Web Services accounts with a general purpose bucket
quota greater than 10,000.
Warning:
You must URL encode any signed header values that contain spaces. For
example, if your header value is my file.txt, containing two spaces
after my, you must URL encode this value to my%20%20file.txt.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input
|
ListBucketsInput
|
An instance of |
required |
plugins
|
list[Plugin] | None
|
A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations. |
None
|
Returns:
| Type | Description |
|---|---|
ListBucketsOutput
|
An instance of |
Input¶
dataclass
¶
Bases: _SerdeShape
Dataclass for ListBucketsInput structure.
Attributes¶
class-attribute
instance-attribute
¶
bucket_region: str | None = ...
Limits the response to buckets that are located in the specified Amazon
Web Services Region. The Amazon Web Services Region must be expressed
according to the Amazon Web Services Region code, such as us-west-2
for the US West (Oregon) Region. For a list of the valid values for all
of the Amazon Web Services Regions, see Regions and
Endpoints.
Note
Requests made to a Regional endpoint that is different from the
bucket-region parameter are not supported. For example, if you want to
limit the response to your buckets in Region us-west-2, the request
must be made to an endpoint in Region us-west-2.
class-attribute
instance-attribute
¶
continuation_token: str | None = ...
ContinuationToken indicates to Amazon S3 that the list is being
continued on this bucket with a token. ContinuationToken is obfuscated
and is not a real key. You can use this ContinuationToken for
pagination of the list results.
Length Constraints: Minimum length of 0. Maximum length of 1024.
Required: No.
Note
If you specify the bucket-region, prefix, or continuation-token
query parameters without using max-buckets to set the maximum number
of buckets returned in the response, Amazon S3 applies a default page
size of 10,000 and provides a continuation token if there are more
buckets.
Output¶
dataclass
¶
Bases: _SerdeShape
Dataclass for ListBucketsOutput structure.
Attributes¶
class-attribute
instance-attribute
¶
buckets: list[Bucket] | None = ...
The list of buckets owned by the requester.
class-attribute
instance-attribute
¶
continuation_token: str | None = ...
ContinuationToken is included in the response when there are more
buckets that can be listed with pagination. The next ListBuckets
request to Amazon S3 can be continued with this ContinuationToken.
ContinuationToken is obfuscated and is not a real bucket.
class-attribute
instance-attribute
¶
The owner of the buckets listed.
class-attribute
instance-attribute
¶
prefix: str | None = ...
If Prefix was sent with the request, it is included in the response.
All bucket names in the response begin with the specified bucket name prefix.
class-attribute
instance-attribute
¶
Metadata about the response that produced this output. Use this to recover the request identifiers a service's support team needs in order to investigate a call. Members of the metadata are individually optional.