list_multipart_uploads¶
Operation¶
async
¶
list_multipart_uploads(input: ListMultipartUploadsInput, plugins: list[Plugin] | None = None) -> ListMultipartUploadsOutput
This operation lists in-progress multipart uploads in a bucket. An
in-progress multipart upload is a multipart upload that has been
initiated by the CreateMultipartUpload request, but has not yet been
completed or aborted.
Note
Directory buckets - If multipart uploads in a directory bucket are
in progress, you can't delete the bucket until all the in-progress
multipart uploads are aborted or completed. To delete these in-progress
multipart uploads, use the ListMultipartUploads operation to list the
in-progress multipart uploads in the bucket and use the
AbortMultipartUpload operation to abort all the in-progress multipart
uploads.
The ListMultipartUploads operation returns a maximum of 1,000
multipart uploads in the response. The limit of 1,000 multipart uploads
is also the default value. You can further limit the number of uploads
in a response by specifying the max-uploads request parameter. If
there are more than 1,000 multipart uploads that satisfy your
ListMultipartUploads request, the response returns an IsTruncated
element with the value of true, a NextKeyMarker element, and a
NextUploadIdMarker element. To list the remaining multipart uploads,
you need to make subsequent ListMultipartUploads requests. In these
requests, include two query parameters: key-marker and
upload-id-marker. Set the value of key-marker to the NextKeyMarker
value from the previous response. Similarly, set the value of
upload-id-marker to the NextUploadIdMarker value from the previous
response.
Note
Directory buckets - The upload-id-marker element and the
NextUploadIdMarker element aren't supported by directory buckets. To
list the additional multipart uploads, you only need to set the value of
key-marker to the NextKeyMarker value from the previous response.
For more information about multipart uploads, see Uploading Objects Using Multipart Upload in the Amazon S3 User Guide.
Note
Directory buckets - For directory buckets, you must make requests
for this API operation to the Zonal endpoint. These endpoints support
virtual-hosted-style requests in the format
https://amzn-s3-demo-bucket.s3express-zone-id.region-code.amazonaws.com/key-name.
Path-style requests are not supported. For more information about
endpoints in Availability Zones, see Regional and Zonal endpoints for
directory buckets in Availability
Zones
in the Amazon S3 User Guide. For more information about endpoints in
Local Zones, see Concepts for directory buckets in Local
Zones
in the Amazon S3 User Guide.
- Permissions
-
- General purpose bucket permissions - For information about permissions required to use the multipart upload API, see Multipart Upload and Permissions in the Amazon S3 User Guide.
- Directory bucket permissions - To grant access to this API
operation on a directory bucket, we recommend that you use the
CreateSessionAPI operation for session-based authorization. Specifically, you grant thes3express:CreateSessionpermission to the directory bucket in a bucket policy or an IAM identity-based policy. Then, you make theCreateSessionAPI call on the bucket to obtain a session token. With the session token in your request header, you can make API requests to this operation. After the session token expires, you make anotherCreateSessionAPI call to generate a new session token for use. Amazon Web Services CLI or SDKs create session and refresh the session token automatically to avoid service interruptions when a session expires. For more information about authorization, seeCreateSession.
- Sorting of multipart uploads in response
-
-
General purpose bucket - In the
ListMultipartUploadsresponse, the multipart uploads are sorted based on two criteria: -
Key-based sorting - Multipart uploads are initially sorted in ascending order based on their object keys.
-
Time-based sorting - For uploads that share the same object key, they are further sorted in ascending order based on the upload initiation time. Among uploads with the same key, the one that was initiated first will appear before the ones that were initiated later.
-
- Directory bucket - In the
ListMultipartUploadsresponse, the multipart uploads aren't sorted lexicographically based on the object keys.
- HTTP Host header syntax
-
Directory buckets - The HTTP Host header syntax is
Bucket-name.s3express-zone-id.region-code.amazonaws.com.
The following operations are related to ListMultipartUploads:
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
|
ListMultipartUploadsInput
|
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 |
|---|---|
ListMultipartUploadsOutput
|
An instance of |
Input¶
dataclass
¶
Bases: _SerdeShape
Dataclass for ListMultipartUploadsInput structure.
Attributes¶
class-attribute
instance-attribute
¶
bucket: str | None = ...
The name of the bucket to which the multipart upload was initiated.
Directory buckets - When you use this operation with a directory
bucket, you must use virtual-hosted-style requests in the format
Bucket-name.s3express-zone-id.region-code.amazonaws.com.
Path-style requests are not supported. Directory bucket names must be
unique in the chosen Zone (Availability Zone or Local Zone). Bucket
names must follow the format
bucket-base-name--zone-id--x-s3 (for example,
amzn-s3-demo-bucket--usw2-az1--x-s3). For information
about bucket naming restrictions, see Directory bucket naming
rules
in the Amazon S3 User Guide.
Access points - When you use this action with an access point for general purpose buckets, you must provide the alias of the access point in place of the bucket name or specify the access point ARN. When you use this action with an access point for directory buckets, you must provide the access point name in place of the bucket name. When using the access point ARN, you must direct requests to the access point hostname. The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. When using this action with an access point through the Amazon Web Services SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, see Using access points in the Amazon S3 User Guide.
Note
Object Lambda access points are not supported by directory buckets.
S3 on Outposts - When you use this action with S3 on Outposts, you
must direct requests to the S3 on Outposts hostname. The S3 on Outposts
hostname takes the form
AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com.
When you use this action with S3 on Outposts, the destination bucket
must be the Outposts access point ARN or the access point alias. For
more information about S3 on Outposts, see What is S3 on
Outposts?
in the Amazon S3 User Guide.
class-attribute
instance-attribute
¶
delimiter: str | None = ...
Character you use to group keys.
All keys that contain the same string between the prefix, if specified,
and the first occurrence of the delimiter after the prefix are grouped
under a single result element, CommonPrefixes. If you don't specify
the prefix parameter, then the substring starts at the beginning of the
key. The keys that are grouped under CommonPrefixes result element are
not returned elsewhere in the response.
CommonPrefixes is filtered out from results if it is not
lexicographically greater than the key-marker.
Note
Directory buckets - For directory buckets, / is the only supported
delimiter.
class-attribute
instance-attribute
¶
encoding_type: str | None = ...
Encoding type used by Amazon S3 to encode the object keys in the response. Responses are encoded only in UTF-8. An object key can contain any Unicode character. However, the XML 1.0 parser can't parse certain characters, such as characters with an ASCII value from 0 to 10. For characters that aren't supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response. For more information about characters to avoid in object key names, see Object key naming guidelines.
Note
When using the URL encoding type, non-ASCII characters that are used in
an object's key name will be percent-encoded according to UTF-8 code
values. For example, the object test_file(3).png will appear as
test_file%283%29.png.
class-attribute
instance-attribute
¶
expected_bucket_owner: str | None = ...
The account ID of the expected bucket owner. If the account ID that you
provide does not match the actual owner of the bucket, the request fails
with the HTTP status code 403 Forbidden (access denied).
class-attribute
instance-attribute
¶
key_marker: str | None = ...
Specifies the multipart upload after which listing should begin.
Note
- General purpose buckets - For general purpose buckets,
key-markeris an object key. Together withupload-id-marker, this parameter specifies the multipart upload after which listing should begin.
If upload-id-marker is not specified, only the keys
lexicographically greater than the specified key-marker will be
included in the list.
If upload-id-marker is specified, any multipart uploads for a key
equal to the key-marker might also be included, provided those
multipart uploads have upload IDs lexicographically greater than the
specified upload-id-marker.
- Directory buckets - For directory buckets,
key-markeris obfuscated and isn't a real object key. Theupload-id-markerparameter isn't supported by directory buckets. To list the additional multipart uploads, you only need to set the value ofkey-markerto theNextKeyMarkervalue from the previous response.
In the ListMultipartUploads response, the multipart uploads aren't
sorted lexicographically based on the object keys.
class-attribute
instance-attribute
¶
max_uploads: int | None = ...
Sets the maximum number of multipart uploads, from 1 to 1,000, to return in the response body. 1,000 is the maximum number of uploads that can be returned in a response.
class-attribute
instance-attribute
¶
prefix: str | None = ...
Lists in-progress uploads only for those keys that begin with the
specified prefix. You can use prefixes to separate a bucket into
different grouping of keys. (You can think of using prefix to make
groups in the same way that you'd use a folder in a file system.)
Note
Directory buckets - For directory buckets, only prefixes that end in
a delimiter (/) are supported.
class-attribute
instance-attribute
¶
request_payer: str | None = ...
Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. If either the source or destination S3 bucket has Requester Pays enabled, the requester will pay for the corresponding charges. For information about downloading objects from Requester Pays buckets, see Downloading Objects in Requester Pays Buckets in the Amazon S3 User Guide.
Note
This functionality is not supported for directory buckets.
class-attribute
instance-attribute
¶
upload_id_marker: str | None = ...
Together with key-marker, specifies the multipart upload after which
listing should begin. If key-marker is not specified, the
upload-id-marker parameter is ignored. Otherwise, any multipart uploads
for a key equal to the key-marker might be included in the list only if
they have an upload ID lexicographically greater than the specified
upload-id-marker.
Note
This functionality is not supported for directory buckets.
Output¶
dataclass
¶
Bases: _SerdeShape
Dataclass for ListMultipartUploadsOutput structure.
Attributes¶
class-attribute
instance-attribute
¶
bucket: str | None = ...
The name of the bucket to which the multipart upload was initiated. Does not return the access point ARN or access point alias if used.
class-attribute
instance-attribute
¶
common_prefixes: list[CommonPrefix] | None = ...
If you specify a delimiter in the request, then the result returns each
distinct key prefix containing the delimiter in a CommonPrefixes
element. The distinct key prefixes are returned in the Prefix child
element.
Note
Directory buckets - For directory buckets, only prefixes that end in
a delimiter (/) are supported.
class-attribute
instance-attribute
¶
delimiter: str | None = ...
Contains the delimiter you specified in the request. If you don't specify a delimiter in your request, this element is absent from the response.
Note
Directory buckets - For directory buckets, / is the only supported
delimiter.
class-attribute
instance-attribute
¶
encoding_type: str | None = ...
Encoding type used by Amazon S3 to encode object keys in the response.
If you specify the encoding-type request parameter, Amazon S3 includes
this element in the response, and returns encoded key name values in the
following response elements:
Delimiter, KeyMarker, Prefix, NextKeyMarker, Key.
class-attribute
instance-attribute
¶
is_truncated: bool | None = ...
Indicates whether the returned list of multipart uploads is truncated. A value of true indicates that the list was truncated. The list can be truncated if the number of multipart uploads exceeds the limit allowed or specified by max uploads.
class-attribute
instance-attribute
¶
key_marker: str | None = ...
The key at or after which the listing began.
class-attribute
instance-attribute
¶
max_uploads: int | None = ...
Maximum number of multipart uploads that could have been included in the response.
class-attribute
instance-attribute
¶
next_key_marker: str | None = ...
When a list is truncated, this element specifies the value that should be used for the key-marker request parameter in a subsequent request.
class-attribute
instance-attribute
¶
next_upload_id_marker: str | None = ...
When a list is truncated, this element specifies the value that should
be used for the upload-id-marker request parameter in a subsequent
request.
Note
This functionality is not supported for directory buckets.
class-attribute
instance-attribute
¶
prefix: str | None = ...
When a prefix is provided in the request, this field contains the specified prefix. The result contains only keys starting with the specified prefix.
Note
Directory buckets - For directory buckets, only prefixes that end in
a delimiter (/) are supported.
class-attribute
instance-attribute
¶
request_charged: str | None = ...
If present, indicates that the requester was successfully charged for the request. For more information, see Using Requester Pays buckets for storage transfers and usage in the Amazon Simple Storage Service user guide.
Note
This functionality is not supported for directory buckets.
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.
class-attribute
instance-attribute
¶
upload_id_marker: str | None = ...
Together with key-marker, specifies the multipart upload after which
listing should begin. If key-marker is not specified, the
upload-id-marker parameter is ignored. Otherwise, any multipart uploads
for a key equal to the key-marker might be included in the list only if
they have an upload ID lexicographically greater than the specified
upload-id-marker.
Note
This functionality is not supported for directory buckets.