Amazon Glacier
Developer Guide (API Version 2012-06-01)
AWS Documentation » Amazon Glacier » Developer Guide » API Reference for Amazon Glacier » Job Operations » Describe Job (GET JobID)
« 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...

Describe Job (GET JobID)

Description

This operation returns information about a job you previously initiated, including the job initiation date, the user who initiated the job, the job status code/message and the Amazon Simple Notification Service (Amazon SNS) topic to notify after Amazon Glacier completes the job. For more information about initiating a job, see Initiate a Job (POST jobs).

Note

This operation enables you to check the status of your job. However, it is strongly recommended that you set up an Amazon SNS topic and specify it in your initiate job request so that Amazon Glacier can notify the topic after it completes the job.

A job ID will not expire for at least 24 hours after Amazon Glacier completes the job.

Requests

Syntax

To obtain information about a job, you use the HTTP GET method and scope the request to the specific job. Note that the relative URI path is the same one that Amazon Glacier returned to you when you initiated the job. 

GET /AccountID/vaults/VaultName/jobs/JobID 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.

Note

In the request, if you omit the JobID, the response returns a list of all active jobs on the specified vault. For more information about listing jobs, see List Jobs (GET jobs).

Request Parameters

This operation does not use request parameters.

Request Headers

This operation uses only request headers that are common to all operations. For information about common request headers, see Common Request Headers.

Request Body

This operation does not have a request body.

Responses

Syntax

HTTP/1.1 201 Created
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: application/json
Content-Length: Length

{
   "Action": String,
   "ArchiveId": String,
   "ArchiveSizeInBytes": Number,
   "ArchiveSHA256TreeHash": String,
   "Completed": Boolean,
   "CompletionDate": String,
   "CreationDate": String,
   "InventorySizeInBytes": Number,
   "JobDescription": String,
   "JobId": String,
   "RetrievalByteRange": String,
   "SHA256TreeHash": String,
   "SNSTopic": String,
   "StatusCode": String,
   "StatusMessage": String,
   "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.

Action

The job type. It is either ArchiveRetrieval or InventoryRetrieval.

Type: String

ArchiveId

For an ArchiveRetrieval job, this is the archive ID requested for download. Otherwise, this field is null.

Type: String

ArchiveSizeInBytes

For an ArchiveRetrieval job, this is the size in bytes of the archive being requested for download. For the InventoryRetrieval job, the value is null.

Type: Number

ArchiveSHA256TreeHash

The SHA256 tree hash of the entire archive for an archive retrieval job. For inventory retrieval jobs, this field is null.

Type: String

Completed

The job status. When a job is completed you get the job's output using the Get Job Output (GET output).

Type: Boolean

CompletionDate

The UTC time that the job request completed. While the job is in progress, the value will be null.

Type: String

CreationDate

The UTC time that the job was created.

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

InventorySizeInBytes

For an InventoryRetrieval job, this is the size in bytes of the inventory requested for download. For the ArchiveRetrieval job, the value is null.

Type: Number

JobDescription

The job description you provided when you initiated the job.

Type: String

JobId

The ID that represents the job in Amazon Glacier.

Type: String

RetrievalByteRange

The retrieved byte range for archive retrieval jobs in the form "StartByteValue-EndByteValue" If you don't specify a range in the archive retrieval, then the whole archive is retrieved; also StartByteValue equals 0, and EndByteValue equals the size of the archive minus 1. For inventory retrieval jobs, this field is null.

Type: String

SHA256TreeHash

The SHA256 tree hash value for the requested range of an archive. If the Initiate a Job (POST jobs) request for an archive specified a tree-hash aligned range, then this field returns a value. For more information about tree-hash alignment for archive range retrievals, see Receiving Checksums When Downloading Data.

For the specific case when the whole archive is retrieved, this value is the same as the ArchiveSHA256TreeHash value.

This field is null in the following situations:

  • Archive retrieval jobs that specify a range that is not tree-hash aligned.

  • Archival jobs that specify a range that is equal to the whole archive and the job status is InProgress.

  • Inventory jobs.

Type: String

SNSTopic

An Amazon Simple Notification Service (Amazon SNS) topic that receives notification.

Type: String

StatusCode

The status code can be InProgress, Succeeded, or Failed, and indicates the status of the job.

Type: String

StatusMessage

A friendly message that describes the job status.

Type: String

VaultARN

The Amazon Resource Name (ARN) of the vault from which the archive retrieval was requested.

Type: String

Errors

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

Examples

The following example shows the request for a job that retrieves an archive.

Example Request: Get job description 

GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID 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

The response body includes JSON that describes the specified job. Note that for both the inventory retrieval and archive retrieval jobs the JSON fields are the same. However, when a field doesn't apply to the type of job, its value is null. The following is an example response for an archive retrieval job. Note the following:

  • The Action field value is ArchiveRetrieval.

  • The ArchiveSizeInBytes field shows the size of the archive requested in the archive retrieval job.

  • The ArchiveSHA256TreeHash field shows the SHA256 tree hash for the entire archive.

  • The RetrievalByteRange field shows the range requested in the Initiate Job request. In this example, the whole archive is requested.

  • The SHA256TreeHash field shows the SHA256 tree hash for the range requested in the Initiate Job request. In this example it is the same as the ArchiveSHA256TreeHash field, which means that the whole archive was requested.

  • The InventorySizeInBytes field value is null because it does not apply to an archive retrieval job.

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: 419
{
  "Action": "ArchiveRetrieval",
  "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId",
  "ArchiveSizeInBytes": 16777216,
  "ArchiveSHA256TreeHash": "beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60",
  "Completed": false,
  "CreationDate": "2012-05-15T17:21:39.339Z",
  "CompletionDate": "2012-05-15T17:21:43.561Z",
  "InventorySizeInBytes": null,
  "JobDescription": "My ArchiveRetrieval Job",
  "JobId": "HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID",
  "RetrievalByteRange": "0-16777215",
  "SHA256TreeHash": "beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60",
  "SNSTopic": "arn:aws:sns:us-east-1:012345678901:mytopic",
  "StatusCode": "InProgress",
  "StatusMessage": "Operation in progress.",
  "VaultARN": "arn:aws:glacier:us-east-1:012345678901:vaults/examplevault"
}

The following is an example response for an inventory retrieval job. Note the following:

  • The Action field value is InventoryRetrieval.

  • The ArchiveSizeInBytes, ArchiveSHA256TreeHash, and RetrievalByteRange field values are null because these fields do not apply to an inventory retrieval job.

  • The InventorySizeInBytes field value is null because the job is still in progress, has not fully prepared the inventory for download. If the job was complete prior to your describe job request, this field would give you the size of the output.

{
   "Action": "InventoryRetrieval",
   "ArchiveId": null,
   "ArchiveSizeInBytes": null,
   "ArchiveSHA256TreeHash": null,
   "Completed": false,
   "CompletionDate": null,
   "CreationDate": "2012-05-15T23:18:13.224Z",
   "InventorySizeInBytes": null,
   "JobDescription": "Inventory Description",
   "JobId": "HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID",
   "RetrievalByteRange": null,
   "SHA256TreeHash": null,
   "SNSTopic": "arn:aws:sns:us-east-1:012345678901:mytopic",
   "StatusCode": "InProgress",
   "StatusMessage": "Operation in progress.",
   "VaultARN": "arn:aws:glacier:us-east-1:012345678901:vaults/examplevault"
}

Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...