Amazon Glacier
Developer Guide (API Version 2012-06-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

List Multipart Uploads (GET multipart-uploads)

Description

This multipart upload operation lists in-progress multipart uploads for the specified vault. An in-progress multipart upload is a multipart upload that has been initiated by an Initiate Multipart Upload (POST multipart-uploads) request, but has not yet been completed or aborted. The list returned in the List Multipart Upload response has no guaranteed order.

The List Multipart Uploads operation supports pagination. By default, this operation returns up to 1,000 multipart uploads in the response. You should always check the marker field in the response body for a marker at which to continue the list; if there are no more items the marker field is null.

If the marker is not null, to fetch the next set of multipart uploads you sent another List Multipart Uploads request with the marker request parameter set to the marker value Amazon Glacier returned in response to your previous List Multipart Uploads request.

Note the difference between this operation and the List Parts (GET uploadID)) operation. The List Multipart Uploads operation lists all multipart uploads for a vault. The List Parts operation returns parts of a specific multipart upload identified by an Upload ID.

For information about multipart upload, see Uploading Large Archives in Parts (Multipart Upload).

Requests

Syntax

To list multipart uploads, send a GET request to the URI of the multipart-uploads subresource of the vault. You may optionally specify marker and limit parameters.

GET /AccountId/vaults/VaultName/multipart-uploads HTTP/1.1
Host: glacier.Region.amazonaws.com
Date: Date
Authorization: SignatureValue
x-amz-glacier-version: 2012-06-01

Note

The AccountId is the AWS Account ID. This value must match the AWS Account ID associated with the credentials used to sign the request. You can either specify AWS Account ID or optionally a '-' in which case Amazon Glacier uses the AWS Account ID associated with the credentials used to sign the request. If you specify your Account ID, do not include dashes in it.

Request Parameters

Name Description Required
limit

Specifies the maximum number of uploads returned in the response body. If not specified, the List Uploads operation returns up to 1,000 uploads.

Type: String

Constraints: Minimum integer value of 1. Maximum integer value of 1000.

No
marker

An opaque string used for pagination. marker specifies the upload at which the listing of uploads should begin. Get the marker value from a previous List Uploads response. You need only include the marker if you are continuing the pagination of results started in a previous List Uploads request.

Type: String

Constraints: None

No

Request Headers

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

Request Body

This operation does not have a request body.

Responses

Syntax

HTTP/1.1 200 OK
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: application/json
Content-Length: Length

{
  "Marker": String,
  "UploadsList" : [ 
    {
      "ArchiveDescription": String,
      "CreationDate": String,
      "MultipartUploadId": String,
      "PartSizeInBytes": Number,
      "VaultARN": String
    }, 
   ...
  ]
} 

Response Headers

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

Response Body

The response body contains the following JSON fields.

ArchiveDescription

The description of the archive that was specified in the Initiate Multipart Upload request. This field is null if no archive description was specified in the Initiate Multipart Upload operation.

Type: String

CreationDate

The UTC time that the multipart upload was initiated.

Type: String. A string representation of ISO 8601 date format, for example, 2013-03-20T17:03:43.221Z.

Marker

An opaque string that represents where to continue pagination of the results. You use the marker in a new List Multipart Uploads request to obtain more uploads in the list. If there are no more uploads, this value is null.

Type: String

PartSizeInBytes

The part size specified in the Initiate Multipart Upload (POST multipart-uploads) request. This is the size of all the parts in the upload except the last part, which may be smaller than this size.

Type: Number

MultipartUploadId

The ID of the multipart upload.

Type: String

UploadsList

A list of metadata about multipart upload objects. Each item in the list contains a set of name-value pairs for the corresponding upload, including ArchiveDescription, CreationDate, MultipartUploadId, PartSizeInBytes, and VaultARN.

Type: Array

VaultARN

The Amazon Resource Name (ARN) of the vault that contains the archive.

Type: String

Errors

For information about Amazon Glacier exceptions and error messages, see Error Responses.

Examples

Example - List All Multipart Uploads

The following example lists all the multipart uploads in progress for the vault. The example shows an HTTP GET request to the URI of the multipart-uploads subresource of a specified vault. Because the marker and limit parameters are not specified in the request, up to 1,000 in-progress multipart uploads are returned.

Example Request

GET /-/vaults/examplevault/multipart-uploads HTTP/1.1
Host: glacier.us-east-1.amazonaws.com
x-amz-Date: 20120325T120000Z
x-amz-glacier-version: 2012-06-01
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120525/us-east-1/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2

Example Response

In the response Amazon Glacier returns a list of all in-progress multipart uploads for the specified vault. The marker field is null, which indicates that there are no more uploads to list.

HTTP/1.1 200 OK
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Sun, 25 Mar 2012 12:00:00 GMT
Content-Type: application/json
Content-Length: 1054
      
{
  "Marker": null, 
  "UploadsList": [ 
    {
      "ArchiveDescription": "archive 1",
      "CreationDate": "2012-03-19T23:20:59.130Z",
      "MultipartUploadId": "xsQdFIRsfJr20CW2AbZBKpRZAFTZSJIMtL2hYf8mvp8dM0m4RUzlaqoEye6g3h3ecqB_zqwB7zLDMeSWhwo65re4C4Ev",
      "PartSizeInBytes": 4194304,
      "VaultARN": "arn:aws:glacier:us-east-1:012345678901:vaults/examplevault"
    }, 
    {
      "ArchiveDescription": "archive 2",
      "CreationDate": "2012-04-01T15:00:00.000Z",
      "MultipartUploadId": "nPyGOnyFcx67qqX7E-0tSGiRi88hHMOwOxR-_jNyM6RjVMFfV29lFqZ3rNsSaWBugg6OP92pRtufeHdQH7ClIpSF6uJc",
      "PartSizeInBytes": 4194304,
      "VaultARN": "arn:aws:glacier:us-east-1:012345678901:vaults/examplevault"
    },
    {
      "ArchiveDescription": "archive 3",
      "CreationDate": "2012-03-20T17:03:43.221Z",
      "MultipartUploadId": "qt-RBst_7yO8gVIonIBsAxr2t-db0pE4s8MNeGjKjGdNpuU-cdSAcqG62guwV9r5jh5mLyFPzFEitTpNE7iQfHiu1XoV",
      "PartSizeInBytes": 4194304,
      "VaultARN": "arn:aws:glacier:us-east-1:012345678901:vaults/examplevault"
    } 
  ]
}    

Example - Partial List of Multipart Uploads

The following example demonstrates how to use pagination to get a limited number of results. The example shows an HTTP GET request to the URI of the multipart-uploads subresource for a specified vault. In this example, the limit parameter is set to 1, which means that only one upload is returned in the list, and the marker parameter indicates the multipart upload ID at which the returned list begins.

Example Request

GET /-/vaults/examplevault/multipart-uploads?limit=1&marker=xsQdFIRsfJr20CW2AbZBKpRZAFTZSJIMtL2hYf8mvp8dM0m4RUzlaqoEye6g3h3ecqB_zqwB7zLDMeSWhwo65re4C4Ev HTTP/1.1
Host: glacier.us-east-1.amazonaws.com
x-amz-Date: 20120325T120000Z
x-amz-glacier-version: 2012-06-01
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120525/us-east-1/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2

Example Response

In the response, Amazon Glacier returns a list of no more than two in-progress multipart uploads for the specified vault, starting at the specified marker and returning two results.

HTTP/1.1 200 OK
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Sun, 25 Mar 2012 12:00:00 GMT
Content-Type: application/json
Content-Length: 470

{
  "Marker": "qt-RBst_7yO8gVIonIBsAxr2t-db0pE4s8MNeGjKjGdNpuU-cdSAcqG62guwV9r5jh5mLyFPzFEitTpNE7iQfHiu1XoV",
  "UploadsList" : [ 
    {
      "ArchiveDescription": "archive 2",
      "CreationDate": "2012-04-01T15:00:00.000Z",
      "MultipartUploadId": "nPyGOnyFcx67qqX7E-0tSGiRi88hHMOwOxR-_jNyM6RjVMFfV29lFqZ3rNsSaWBugg6OP92pRtufeHdQH7ClIpSF6uJc",
      "PartSizeInBytes": 4194304,
      "VaultARN": "arn:aws:glacier:us-east-1:012345678901:vaults/examplevault"
    }
  ]
}