Amazon Simple Storage Service
API Reference (API Version 2006-03-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.

List Parts

Description

This operation lists the parts that have been uploaded for a specific multipart upload.

This operation must include the upload ID, which you obtain by sending the initiate multipart upload request (see Initiate Multipart Upload). This request returns a maximum of 1,000 uploaded parts. The default number of parts returned is 1,000 parts. You can restrict the number of parts returned 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. In subsequent List Parts requests you can 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, go to Uploading Objects Using Multipart Upload in the Amazon Simple Storage Service Developer Guide .

For information on permissions required to use the multipart upload API, go to Multipart Upload API and Permissions in the Amazon Simple Storage Service Developer Guide .

Requests

Syntax

GET /ObjectName?uploadId=UploadId HTTP/1.1
Host: BucketName.s3.amazonaws.com
Date: Date
Authorization: authorization string

Request Parameters

This implementation of GET uses the parameters in the following table to return a subset of the objects in a bucket.

ParameterDescriptionRequired
encoding-type

Requests Amazon S3 to encode the response and specifies the encoding method to use.

An object key can contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.

Type: String

Default: None

Valid value: url

No
uploadId

Upload ID identifying the multipart upload whose parts are being listed.

Type: String

Default: None

Yes
max-parts

Sets the maximum number of parts to return in the response body.

Type: String

Default: 1,000

No
part-number​-marker

Specifies the part after which listing should begin. Only parts with higher part numbers will be listed.

Type: String

Default: None

No

Request Headers

This operation uses only Request Headers common to most requests. For more information, see Common Request Headers.

Request Elements

This operation does not use request elements.

Responses

Response Headers

This operation uses only response headers that are common to most responses. For more information, see Common Response Headers.

Response Elements

Name Description
ListPartsResult

Container for the response.

Children: Bucket, Key, UploadId, Initiator, Owner, StorageClass, PartNumberMarker, NextPartNumberMarker, MaxParts, IsTruncated, Part

Type: Container

Bucket

Name of the bucket to which the multipart upload was initiated.

Type: String

Ancestor: ListPartsResult

Encoding-Type

Encoding type used by Amazon S3 to encode object key names in the XML response.

If you specify encoding-type request parameter, Amazon S3 includes this element in the response, and returns encoded key name values in the Key element.

Type: String

Ancestor: ListBucketResult

Key

Object key for which the multipart upload was initiated.

Type: String

Ancestor: ListPartsResult

UploadId

Upload ID identifying the multipart upload whose parts are being listed.

Type: String

Ancestor: ListPartsResult

Initiator

Container element that identifies who initiated the multipart upload. If the initiator is an AWS account, this element provides the same information as the Owner element. If the initiator is an IAM User, then this element provides the user ARN and display name.

Children: ID, DisplayName

Type: Container

Ancestor: ListPartsResult

ID

If the principal is an AWS account, it provides the Canonical User ID. If the principal is an IAM User, it provides a user ARN value.

Type: String

Ancestor: Initiator

DisplayName

Principal's name.

Type: String

Ancestor: Initiator

Owner

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 and display name.

Children: ID, DisplayName

Type: Container

Ancestor: ListPartsResult

StorageClass

Class of storage (STANDARD or REDUCED_REDUNDANCY) used to store the uploaded object.

Type: String

Ancestor: ListPartsResult

PartNumberMarker

Part number after which listing begins.

Type: Integer

Ancestor: ListPartsResult

NextPartNumberMarker

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.

Type: Integer

Ancestor: ListPartsResult

MaxParts

Maximum number of parts that were allowed in the response.

Type: Integer

Ancestor: ListPartsResult

IsTruncated

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.

Type: Boolean

Ancestor: ListPartsResult

Part

Container for elements related to a particular part. A response can contain zero or more Part elements.

Children: PartNumber, LastModified, ETag, Size

Type: String

Ancestor: ListPartsResult

PartNumber

Part number identifying the part.

Type: Integer

Ancestor: Part

LastModified

Date and time at which the part was uploaded.

Type: Date

Ancestor: Part

ETag

Entity tag returned when the part was uploaded.

Type: String

Ancestor: Part

Size

Size of the uploaded part data.

Type: Integer

Ancestor: Part

Examples

Sample Request

Assume you have uploaded parts with sequential part numbers starting with 1. The following List Parts request specifies max-parts and part-number-marker query parameters. The request lists the first two parts that follow part number 1, that is, you will get parts 2 and 3 in the response. If more parts exist , the result is a truncated result and therefore the response will return an IsTruncated element with the value true. The response will also return the NextPartNumberMarker element with the value 3, which should be used for the value of the part-number-marker request query string parameter in the next List Parts request.

GET /example-object?uploadId=XXBsb2FkIElEIGZvciBlbHZpbmcncyVcdS1tb3ZpZS5tMnRzEEEwbG9hZA&max-parts=2&part-number-marker=1 HTTP/1.1
Host: example-bucket.s3.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

Sample Response

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732072657175657374
Date: Mon, 1 Nov 2010 20:34:56 GMT
Content-Length: 985
Connection: keep-alive
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>
<ListPartsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Bucket>example-bucket</Bucket>
  <Key>example-object</Key>
  <UploadId>XXBsb2FkIElEIGZvciBlbHZpbmcncyVcdS1tb3ZpZS5tMnRzEEEwbG9hZA</UploadId>
  <Initiator>
      <ID>arn:aws:iam::111122223333:user/some-user-11116a31-17b5-4fb7-9df5-b288870f11xx</ID>
      <DisplayName>umat-user-11116a31-17b5-4fb7-9df5-b288870f11xx</DisplayName>
  </Initiator>
  <Owner>
    <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
    <DisplayName>someName</DisplayName>
  </Owner>
  <StorageClass>STANDARD</StorageClass>
  <PartNumberMarker>1</PartNumberMarker>
  <NextPartNumberMarker>3</NextPartNumberMarker>
  <MaxParts>2</MaxParts>
  <IsTruncated>true</IsTruncated>
  <Part>
    <PartNumber>2</PartNumber>
    <LastModified>2010-11-10T20:48:34.000Z</LastModified>
    <ETag>"7778aef83f66abc1fa1e8477f296d394"</ETag>
    <Size>10485760</Size>
  </Part>
  <Part>
    <PartNumber>3</PartNumber>
    <LastModified>2010-11-10T20:48:33.000Z</LastModified>
    <ETag>"aaaa18db4cc2f85cedef654fccc4a4x8"</ETag>
    <Size>10485760</Size>
  </Part>
</ListPartsResult>