list_parts¶
Operation¶
list_parts
async
¶
list_parts(request: ListPartsInput | ListPartsInputDict, /, *, plugins: list[Plugin] | None = None) -> ListPartsOutput
list_parts(*, plugins: list[Plugin] | None = None, **kwargs: Unpack[ListPartsInputDict]) -> ListPartsOutput
Lists the parts that have been uploaded for a specific multipart upload.
To use this operation, you must provide the upload ID in the request.
You obtain this uploadID by sending the initiate multipart upload
request through
CreateMultipartUpload.
The ListParts request returns a maximum of 1,000 uploaded parts. The
limit of 1,000 parts is also the default value. You can restrict the
number of parts in a response by specifying the max-parts request
parameter. If your multipart upload consists of more than 1,000 parts,
the response returns an IsTruncated field with the value of true,
and a NextPartNumberMarker element. To list remaining uploaded parts,
in subsequent ListParts requests, include the part-number-marker
query string parameter and set its value to the NextPartNumberMarker
field value from the previous response.
For more information on 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.
If the upload was created using server-side encryption with Key Management Service (KMS) keys (SSE-KMS) or dual-layer server-side encryption with Amazon Web Services KMS keys (DSSE-KMS), you must have permission to the
kms:Decryptaction for theListPartsrequest to succeed.- 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.
- 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 ListParts:
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 |
|---|---|---|---|
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 |
|---|---|
ListPartsOutput
|
An instance of |
Input¶
Pass the input fields as keyword arguments, or pass a model or dictionary as the first positional argument. Pass plugins separately as a keyword argument.
Model¶
ListPartsInput
dataclass
¶
Bases: _SerdeShape
Dataclass for ListPartsInput structure.
Attributes¶
bucket
class-attribute
instance-attribute
¶
bucket: str | None = ...
The name of the bucket to which the parts are being uploaded.
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.
expected_bucket_owner
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).
key
class-attribute
instance-attribute
¶
key: str | None = ...
Object key for which the multipart upload was initiated.
max_parts
class-attribute
instance-attribute
¶
max_parts: int | None = ...
Sets the maximum number of parts to return.
part_number_marker
class-attribute
instance-attribute
¶
part_number_marker: str | None = ...
Specifies the part after which listing should begin. Only parts with higher part numbers will be listed.
request_payer
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.
sse_customer_algorithm
class-attribute
instance-attribute
¶
sse_customer_algorithm: str | None = ...
The server-side encryption (SSE) algorithm used to encrypt the object. This parameter is needed only when the object was created using a checksum algorithm. For more information, see Protecting data using SSE-C keys in the Amazon S3 User Guide.
Note
This functionality is not supported for directory buckets.
sse_customer_key
class-attribute
instance-attribute
¶
sse_customer_key: str | None = ...
The server-side encryption (SSE) customer managed key. This parameter is needed only when the object was created using a checksum algorithm. For more information, see Protecting data using SSE-C keys in the Amazon S3 User Guide.
Note
This functionality is not supported for directory buckets.
sse_customer_key_md5
class-attribute
instance-attribute
¶
sse_customer_key_md5: str | None = ...
The MD5 server-side encryption (SSE) customer managed key. This parameter is needed only when the object was created using a checksum algorithm. For more information, see Protecting data using SSE-C keys in the Amazon S3 User Guide.
Note
This functionality is not supported for directory buckets.
Dictionaries¶
ListPartsInputDict
¶
Bases: TypedDict
Dictionary form of ListPartsInput.
Attributes¶
bucket
instance-attribute
¶
The name of the bucket to which the parts are being uploaded.
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.
expected_bucket_owner
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).
key
instance-attribute
¶
Object key for which the multipart upload was initiated.
part_number_marker
instance-attribute
¶
part_number_marker: str | None
Specifies the part after which listing should begin. Only parts with higher part numbers will be listed.
request_payer
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.
sse_customer_algorithm
instance-attribute
¶
sse_customer_algorithm: str | None
The server-side encryption (SSE) algorithm used to encrypt the object. This parameter is needed only when the object was created using a checksum algorithm. For more information, see Protecting data using SSE-C keys in the Amazon S3 User Guide.
Note
This functionality is not supported for directory buckets.
sse_customer_key
instance-attribute
¶
sse_customer_key: str | None
The server-side encryption (SSE) customer managed key. This parameter is needed only when the object was created using a checksum algorithm. For more information, see Protecting data using SSE-C keys in the Amazon S3 User Guide.
Note
This functionality is not supported for directory buckets.
sse_customer_key_md5
instance-attribute
¶
sse_customer_key_md5: str | None
The MD5 server-side encryption (SSE) customer managed key. This parameter is needed only when the object was created using a checksum algorithm. For more information, see Protecting data using SSE-C keys in the Amazon S3 User Guide.
Note
This functionality is not supported for directory buckets.
Output¶
ListPartsOutput
dataclass
¶
Bases: _SerdeShape
Dataclass for ListPartsOutput structure.
Attributes¶
abort_date
class-attribute
instance-attribute
¶
abort_date: datetime | None = ...
If the bucket has a lifecycle rule configured with an action to abort incomplete multipart uploads and the prefix in the lifecycle rule matches the object name in the request, then the response includes this header indicating when the initiated multipart upload will become eligible for abort operation. For more information, see Aborting Incomplete Multipart Uploads Using a Bucket Lifecycle Configuration.
The response will also include the x-amz-abort-rule-id header that
will provide the ID of the lifecycle configuration rule that defines
this action.
Note
This functionality is not supported for directory buckets.
abort_rule_id
class-attribute
instance-attribute
¶
abort_rule_id: str | None = ...
This header is returned along with the x-amz-abort-date header. It
identifies applicable lifecycle configuration rule that defines the
action to abort incomplete multipart uploads.
Note
This functionality is not supported for directory buckets.
bucket
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.
checksum_algorithm
class-attribute
instance-attribute
¶
checksum_algorithm: str | None = ...
The algorithm that was used to create a checksum of the object.
checksum_type
class-attribute
instance-attribute
¶
checksum_type: str | None = ...
The checksum type, which determines how part-level checksums are
combined to create an object-level checksum for multipart objects. You
can use this header response to verify that the checksum type that is
received is the same checksum type that was specified in
CreateMultipartUpload request. For more information, see Checking
object integrity in the Amazon S3 User
Guide.
initiator
class-attribute
instance-attribute
¶
initiator: Initiator | None = ...
Container element that identifies who initiated the multipart upload. If
the initiator is an Amazon Web Services account, this element provides
the same information as the Owner element. If the initiator is an IAM
User, this element provides the user ARN.
is_truncated
class-attribute
instance-attribute
¶
is_truncated: bool | None = ...
Indicates whether the returned list of parts is truncated. A true value indicates that the list was truncated. A list can be truncated if the number of parts exceeds the limit returned in the MaxParts element.
key
class-attribute
instance-attribute
¶
key: str | None = ...
Object key for which the multipart upload was initiated.
max_parts
class-attribute
instance-attribute
¶
max_parts: int | None = ...
Maximum number of parts that were allowed in the response.
next_part_number_marker
class-attribute
instance-attribute
¶
next_part_number_marker: str | None = ...
When a list is truncated, this element specifies the last part in the
list, as well as the value to use for the part-number-marker request
parameter in a subsequent request.
owner
class-attribute
instance-attribute
¶
owner: Owner | None = ...
Container element that identifies the object owner, after the object is created. If multipart upload is initiated by an IAM user, this element provides the parent account ID.
Note
Directory buckets - The bucket owner is returned as the object owner for all the parts.
part_number_marker
class-attribute
instance-attribute
¶
part_number_marker: str | None = ...
Specifies the part after which listing should begin. Only parts with higher part numbers will be listed.
parts
class-attribute
instance-attribute
¶
Container for elements related to a particular part. A response can
contain zero or more Part elements.
request_charged
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.
response_metadata
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.
storage_class
class-attribute
instance-attribute
¶
storage_class: str | None = ...
The class of storage used to store the uploaded object.
Note
Directory buckets - Directory buckets only support EXPRESS_ONEZONE
(the S3 Express One Zone storage class) in Availability Zones and
ONEZONE_IA (the S3 One Zone-Infrequent Access storage class) in
Dedicated Local Zones.