Amazon Glacier
Developer Guide (API Version 2012-06-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.Go to the Kindle Store to download this guide in Kindle format.

Initiate a Job (POST jobs)

Description

This operation initiates a job of the specified type, which can be an archive retrieval or vault inventory retrieval. Retrieving an archive or a vault inventory are asynchronous operations that require you to initiate a job. Retrieval is a two-step process:

  1. Initiate a retrieval job.

  2. After the job completes, download the bytes.

The retrieval request is executed asynchronously. When you initiate a retrieval job, Amazon Glacier creates a job and returns a job ID in the response. When Amazon Glacier completes the job, you can get the job output (archive or inventory data). For information about getting job output, see the Get Job Output (GET output) operation.

The job must complete before you can get its output. To determine when a job is complete, you have the following options:

  • Use an Amazon SNS notification— You can specify an Amazon Simple Notification Service (Amazon SNS) topic to which Amazon Glacier can post a notification after the job is completed. You can specify an SNS topic per job request. The notification is sent only after Amazon Glacier completes the job. In addition to specifying an SNS topic per job request, you can configure vault notifications for a vault so that job notifications are sent for all retrievals. For more information, see Set Vault Notification Configuration (PUT notification-configuration).

  • Get job details— You can make a Describe Job (GET JobID) request to obtain job status information while a job is in progress. However, it is more efficient to use an Amazon SNS notification to determine when a job is complete.

Note

The information you get via notification is same that you get by calling Describe Job (GET JobID).

If for a specific event, you add both the notification configuration on the vault and also specify an SNS topic in your initiate job request, Amazon Glacier sends both notifications. For more information, see Set Vault Notification Configuration (PUT notification-configuration).

The Vault Inventory

Amazon Glacier updates a vault inventory approximately once a day, starting on the day you first upload an archive to the vault. If there have been no archive additions or deletions to the vault since the last inventory, the inventory date is not updated. When you initiate a job for a vault inventory, Amazon Glacier returns the last inventory it generated, which is a point-in-time snapshot and not real-time data. Note that after Amazon Glacier creates the first inventory for the vault, it typically takes half a day and up to a day before that inventory is available for retrieval. You might not find it useful to retrieve a vault inventory for each archive upload. However, suppose you maintain a database on the client-side associating metadata about the archives you upload to Amazon Glacier. Then, you might find the vault inventory useful to reconcile information, as needed, in your database with the actual vault inventory. For more information about the data fields returned in an inventory job output, see Response Body.

Range Inventory Retrieval

You can limit the number of inventory items retrieved by filtering on the archive creation date or by setting a limit.

Filtering by Archive Creation Date

You can retrieve inventory items for archives created between StartDate and EndDate by specifying values for these parameters in the Initiate Job request. Archives created on or after the StartDate and before the EndDate will be returned. If you only provide the StartDate without the EndDate, you will retrieve the inventory for all archives created on or after the StartDate. If you only provide the EndDate without the StartDate, you will get back the inventory for all archives created before the EndDate.

Limiting Inventory Items per Retrieval

You can limit the number of inventory items returned by setting the Limit parameter in the Initiate Job request. The inventory job output will contain inventory items up to the specified Limit. If there are more inventory items available, the result is paginated. After a job is complete you can use the Describe Job (GET JobID) operation to get a marker that you use in a subsequent Initiate Job request. The marker will indicate the starting point to retrieve the next set of inventory items. You can page through your entire inventory by repeatedly making Initiate Job requests with the marker from the previous Describe Job output, until you get a marker from Describe Job that returns null, indicating that there are no more inventory items available.

You can use the Limit parameter together with the date range parameters.

Ranged Archive Retrieval

You can initiate archive retrieval for the whole archive or a range of the archive. In the case of ranged archive retrieval, you specify a byte range to return or the whole archive. The range specified must be megabyte (MB) aligned; that is, the range start value must be divisible by 1 MB and the range end value plus 1 must be divisible by 1 MB or equal the end of the archive. If the ranged archive retrieval is not megabyte aligned, this operation returns a 400 response. Furthermore, to ensure you get checksum values for data you download using Get Job Output (Get Job Output (GET output)), the range must be tree-hash aligned. For more information about tree-hash aligned ranges, see Receiving Checksums When Downloading Data.

Requests

To initiate a job, you use the HTTP POST method and scope the request to the vault's jobs subresource. You specify details of the job request in the JSON document of your request. The job type is specified with the Type field and you can optionally specify an SNSTopic field to indicate an Amazon SNS topic to which Amazon Glacier can post notification after it completes the job.

Note

To post a notification to Amazon SNS, you must create the topic yourself if it does not already exist. Amazon Glacier does not create the topic for you. The topic must have permissions to receive publications from an Amazon Glacier vault. Amazon Glacier does not verify if the vault has permission to publish to the topic. If the permissions are not configured appropriately, you might not receive notification even after the job completes.

Syntax

The following syntax is for an archive retrieval.

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

{
  "Type": "archive-retrieval",
  "ArchiveId": String
  "Description": String,
  "RetrievalByteRange": String,
  "SNSTopic": String
}

The following syntax is for an inventory retrieval.

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

{
  "Type": "inventory-retrieval",
  "Description": String,
  "Format": String,  
  "SNSTopic": String,
  "InventoryRetrievalParameters": { 
      "StartDate": String,
      "EndDate": String,
      "Limit": String,
      "Marker": String
   }  				
}

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 Body

The JSON in the request body contains the following fields.

ArchiveId

The ID of the archive that you want to retrieve. This field is required only if Type is set to archive-retrieval. An error occurs if you specify this field for an inventory retrieval job request.

Valid Values: Must be a valid archive ID that you obtained from a previous request to Amazon Glacier.

Required: Yes when Type is set to archive-retrieval.

Type: String

Description

The optional description for the job.

Valid Values: The description must be less than or equal to 1,024 bytes. The allowable characters are 7-bit ASCII without control codes—specifically, ASCII values 32—126 decimal or 0x20—0x7E hexadecimal.

Required: no

Type: String

EndDate

The end of the date range in UTC for vault inventory retrieval that includes archives created before this date.

Valid Values: A string representation of ISO 8601 date format YYYY-MM-DDThh:mm:ssTZD in seconds, for example, 2013-03-20T17:03:43Z.

Required: no

Type: String. A string representation of ISO 8601 date format YYYY-MM-DDThh:mm:ssTZD in seconds, for example, 2013-03-20T17:03:43Z.

Format

When initiating a job to retrieve a vault inventory, you can optionally add this parameter to your request to specify the output format. If you are initiating an inventory job and do not specify a Format field, JSON is the default format.

Valid Values: CSV | JSON

Required: no

Type: String

Limit

Specifies the maximum number of inventory items returned per vault inventory retrieval request.

Valid Values: An integer value greater than or equal to 1.

Required: no

Type: String

Marker

An opaque string that represents where to continue pagination of the vault inventory retrieval results. You use the marker in a new Initiate Job request to obtain additional inventory items. If there are no more inventory items, this value is null.

Required: no

Type: String

RetrievalByteRange

The byte range to retrieve for an archive retrieval. in the form "StartByteValue-EndByteValue" If not specified, the whole archive is retrieved. If specified, the byte range must be megabyte (1024*1024) aligned, which means that StartByteValue must be divisible by 1 MB, and the EndByteValue plus 1 must be divisible by 1 MB or be the end of the archive specified as the archive byte size value minus 1. If RetrievalByteRange is not megabyte aligned, this operation returns a 400 response.

An error occurs if you specify this field for an inventory retrieval job request.

Required: no

Type: String

SNSTopic

The Amazon SNS topic ARN where Amazon Glacier sends a notification when the job is completed, and the output is ready for you to download. The specified topic publishes the notification to its subscribers. The SNS topic must exist. If it does not, Amazon Glacier does not create it for you. Additionally, the SNS topic must have a policy that allows the account that created the job to publish messages to the topic. For information about SNS topic names, see CreateTopic in the Amazon Simple Notification Service API Reference.

Required: no

Type: String

StartDate

The start of the date range in UTC for vault inventory retrieval that includes archives created on or after this date.

Valid Values: A string representation of ISO 8601 date format YYYY-MM-DDThh:mm:ssTZD in seconds, for example, 2013-03-20T17:03:43Z.

Required: no

Type: String. A string representation of ISO 8601 date format YYYY-MM-DDThh:mm:ssTZD in seconds, for example, 2013-03-20T17:03:43Z.

Type

The job type. You can initiate a job to retrieve an archive or get an inventory of a vault.

Valid Values: archive-retrieval | inventory-retrieval

Required: yes

Type: String

Responses

Amazon Glacier creates the job. In the response, it returns the URI of the job.

Syntax

HTTP/1.1 202 Accepted
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Location: Location
x-amz-job-id: JobId

Response Headers

HeaderDescription
Location

The relative URI path of the job. You can use this URI path to find the job status. For more information, see Describe Job (GET JobID).

Type: String

Default: None

x-amz-job-id

The ID of the job. This value is also included as part of the Location header.

Type: String

Default: None

Response Body

This operation does not return a response body.

Errors

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

Examples

Example Request: Initiate an archive retrieval job

POST /-/vaults/examplevault/jobs 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

{
  "Type": "archive-retrieval",
  "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId"
  "Description": "My archive description",
  "SNSTopic": "arn:aws:sns:us-east-1:111111111111:Glacier-ArchiveRetrieval-topic-Example"
}

The following is an example of the body of a request that specifies a range of the archive to retrieve using the RetrievalByteRange field.

{
  "Type": "archive-retrieval",
  "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId"
  "Description": "My archive description",
  "RetrievalByteRange": "2097152-4194303",
  "SNSTopic": "arn:aws:sns:us-east-1:111111111111:Glacier-ArchiveRetrieval-topic-Example"
}

Example Response

HTTP/1.1 202 Accepted
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Sun, 25 Mar 2012 12:00:00 GMT
Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID
x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID

Example Request: Initiate an inventory retrieval job

The following request initiates an inventory retrieval job to get a list of archives from the examplevault vault. The Format set to CSV in the body of the request indicates that the inventory is returned in CSV format.

POST /-/vaults/examplevault/jobs HTTP/1.1
Host: glacier.us-east-1.amazonaws.com
x-amz-Date: 20120325T120000Z
Content-Type: application/x-www-form-urlencoded
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

{
  "Type": "inventory-retrieval",
  "Description": "My inventory job",
  "Format": "CSV",  
  "SNSTopic": "arn:aws:sns:us-east-1:111111111111:Glacier-InventoryRetrieval-topic-Example"
}

Example Response

HTTP/1.1 202 Accepted
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Sun, 25 Mar 2012 12:00:00 GMT 
Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID
x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID

Example Requests: Initiate an inventory retrieval job by using date filtering with a set limit. And a subsequent request to retrieve the next page of inventory items.

The following request initiates a vault inventory retrieval job by using date filtering and setting a limit.

{
    "ArchiveId": null, 
    "Description": null, 
    "Format": "CSV", 
    "RetrievalByteRange": null, 
    "SNSTopic": null, 
    "Type": "inventory-retrieval", 
    "InventoryRetrievalParameters": {
        "StartDate": "2013-12-04T21:25:42Z",
        "EndDate": "2013-12-05T21:25:42Z", 
        "Limit" : "10000"
    }, 
}

The following request is an example of a subsequent request to retrieve the next page of inventory items using a marker obtained from Describe Job (GET JobID).

{
    "ArchiveId": null, 
    "Description": null, 
    "Format": "CSV", 
    "RetrievalByteRange": null, 
    "SNSTopic": null, 
    "Type": "inventory-retrieval", 
    "InventoryRetrievalParameters": {
        "StartDate": "2013-12-04T21:25:42Z",
        "EndDate": "2013-12-05T21:25:42Z", 
        "Limit": "10000"
        "Marker": "vyS0t2jHQe5qbcDggIeD50chS1SXwYMrkVKo0KHiTUjEYxBGCqRLKaiySzdN7QXGVVV5XZpNVG67pCZ_uykQXFMLaxOSu2hO_-5C0AtWMDrfo7LgVOyfnveDRuOSecUo3Ueq7K0"
    }, 
}