| « PreviousNext » | |
   | Did this page help you? Yes | No | Tell us about it... |
Initiate a Job (POST jobs)
Description
This operation initiates a job of the specified type. Retrieving an archive or a vault inventory are asynchronous operations that require you to initiate a job. It is a two-step process:
Initiate a retrieval job.
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).
About 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.
About Ranged Archive Retrieval
You can initiate an 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:DateAuthorization:SignatureValuex-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:DateAuthorization:SignatureValuex-amz-glacier-version: 2012-06-01 { "Type": "inventory-retrieval", "Description":String, "Format":String, "SNSTopic":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
Typeis set toarchive-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
Typeis set toarchive-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
- 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
Formatfield, JSON is the default format.Valid Values:
CSV|JSONRequired: 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 a400response.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
- 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-retrievalRequired: 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
| Header | Description |
|---|---|
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
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 retreive 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
