2017/11/29 - Amazon Glacier - 3 updated api methods
Changes This release includes support for Glacier Select, a new feature that allows you to filter and analyze your Glacier archives and store the results in a user-specified S3 location.
{'Action': ['Select'],
'JobOutputPath': 'string',
'OutputLocation': {'S3': {'AccessControlList': [{'Grantee': {'DisplayName': 'string',
'EmailAddress': 'string',
'ID': 'string',
'Type': 'AmazonCustomerByEmail '
'| '
'CanonicalUser '
'| Group',
'URI': 'string'},
'Permission': 'FULL_CONTROL '
'| WRITE | '
'WRITE_ACP | '
'READ | '
'READ_ACP'}],
'BucketName': 'string',
'CannedACL': 'private | public-read | '
'public-read-write | aws-exec-read | '
'authenticated-read | '
'bucket-owner-read | '
'bucket-owner-full-control',
'Encryption': {'EncryptionType': 'aws:kms | AES256',
'KMSContext': 'string',
'KMSKeyId': 'string'},
'Prefix': 'string',
'StorageClass': 'STANDARD | REDUCED_REDUNDANCY | '
'STANDARD_IA',
'Tagging': {'string': 'string'},
'UserMetadata': {'string': 'string'}}},
'SelectParameters': {'Expression': 'string',
'ExpressionType': 'SQL',
'InputSerialization': {'csv': {'Comments': 'string',
'FieldDelimiter': 'string',
'FileHeaderInfo': 'USE | '
'IGNORE '
'| NONE',
'QuoteCharacter': 'string',
'QuoteEscapeCharacter': 'string',
'RecordDelimiter': 'string'}},
'OutputSerialization': {'csv': {'FieldDelimiter': 'string',
'QuoteCharacter': 'string',
'QuoteEscapeCharacter': 'string',
'QuoteFields': 'ALWAYS | '
'ASNEEDED',
'RecordDelimiter': 'string'}}}}
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 SNS topic to notify after Amazon Glacier completes the job. For more information about initiating a job, see InitiateJob .
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.
An AWS account has full permission to perform all operations (actions). However, AWS Identity and Access Management (IAM) users don't have any permissions by default. You must grant them explicit permission to perform specific actions. For more information, see Access Control Using AWS Identity and Access Management (IAM) .
For more information about using this operation, see the documentation for the underlying REST API Describe Job in the Amazon Glacier Developer Guide .
See also: AWS API Documentation
Request Syntax
client.describe_job(
accountId='string',
vaultName='string',
jobId='string'
)
string
[REQUIRED]
The AccountId value is the AWS account ID of the account that owns the vault. You can either specify an AWS account ID or optionally a single '- ' (hyphen), in which case Amazon Glacier uses the AWS account ID associated with the credentials used to sign the request. If you use an account ID, do not include any hyphens ('-') in the ID.
string
[REQUIRED]
The name of the vault.
string
[REQUIRED]
The ID of the job to describe.
dict
Response Syntax
{
'JobId': 'string',
'JobDescription': 'string',
'Action': 'ArchiveRetrieval'|'InventoryRetrieval'|'Select',
'ArchiveId': 'string',
'VaultARN': 'string',
'CreationDate': 'string',
'Completed': True|False,
'StatusCode': 'InProgress'|'Succeeded'|'Failed',
'StatusMessage': 'string',
'ArchiveSizeInBytes': 123,
'InventorySizeInBytes': 123,
'SNSTopic': 'string',
'CompletionDate': 'string',
'SHA256TreeHash': 'string',
'ArchiveSHA256TreeHash': 'string',
'RetrievalByteRange': 'string',
'Tier': 'string',
'InventoryRetrievalParameters': {
'Format': 'string',
'StartDate': 'string',
'EndDate': 'string',
'Limit': 'string',
'Marker': 'string'
},
'JobOutputPath': 'string',
'SelectParameters': {
'InputSerialization': {
'csv': {
'FileHeaderInfo': 'USE'|'IGNORE'|'NONE',
'Comments': 'string',
'QuoteEscapeCharacter': 'string',
'RecordDelimiter': 'string',
'FieldDelimiter': 'string',
'QuoteCharacter': 'string'
}
},
'ExpressionType': 'SQL',
'Expression': 'string',
'OutputSerialization': {
'csv': {
'QuoteFields': 'ALWAYS'|'ASNEEDED',
'QuoteEscapeCharacter': 'string',
'RecordDelimiter': 'string',
'FieldDelimiter': 'string',
'QuoteCharacter': 'string'
}
}
},
'OutputLocation': {
'S3': {
'BucketName': 'string',
'Prefix': 'string',
'Encryption': {
'EncryptionType': 'aws:kms'|'AES256',
'KMSKeyId': 'string',
'KMSContext': 'string'
},
'CannedACL': 'private'|'public-read'|'public-read-write'|'aws-exec-read'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
'AccessControlList': [
{
'Grantee': {
'Type': 'AmazonCustomerByEmail'|'CanonicalUser'|'Group',
'DisplayName': 'string',
'URI': 'string',
'ID': 'string',
'EmailAddress': 'string'
},
'Permission': 'FULL_CONTROL'|'WRITE'|'WRITE_ACP'|'READ'|'READ_ACP'
},
],
'Tagging': {
'string': 'string'
},
'UserMetadata': {
'string': 'string'
},
'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'STANDARD_IA'
}
}
}
Response Structure
(dict) --
Contains the description of an Amazon Glacier job.
JobId (string) --
An opaque string that identifies an Amazon Glacier job.
JobDescription (string) --
The job description provided when initiating the job.
Action (string) --
The job type. This value is either ArchiveRetrieval , InventoryRetrieval , or Select .
ArchiveId (string) --
The archive ID requested for a select job or archive retrieval. Otherwise, this field is null.
VaultARN (string) --
The Amazon Resource Name (ARN) of the vault from which an archive retrieval was requested.
CreationDate (string) --
The UTC date when the job was created. This value is a string representation of ISO 8601 date format, for example "2012-03-20T17:03:43.221Z" .
Completed (boolean) --
The job status. When a job is completed, you get the job's output using Get Job Output (GET output).
StatusCode (string) --
The status code can be InProgress , Succeeded , or Failed , and indicates the status of the job.
StatusMessage (string) --
A friendly message that describes the job status.
ArchiveSizeInBytes (integer) --
For an archive retrieval job, this value is the size in bytes of the archive being requested for download. For an inventory retrieval or select job, this value is null.
InventorySizeInBytes (integer) --
For an inventory retrieval job, this value is the size in bytes of the inventory requested for download. For an archive retrieval or select job, this value is null.
SNSTopic (string) --
An Amazon SNS topic that receives notification.
CompletionDate (string) --
The UTC time that the job request completed. While the job is in progress, the value is null.
SHA256TreeHash (string) --
For an archive retrieval job, this value is the checksum of the archive. Otherwise, this value is null.
The SHA256 tree hash value for the requested range of an archive. If the InitiateJob request for an archive specified a tree-hash aligned range, then this field returns a value.
If the whole archive is retrieved, this value is the same as the ArchiveSHA256TreeHash value.
This field is null for the following:
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, when the job status is InProgress
Inventory jobs
Select jobs
ArchiveSHA256TreeHash (string) --
The SHA256 tree hash of the entire archive for an archive retrieval. For inventory retrieval or select jobs, this field is null.
RetrievalByteRange (string) --
The retrieved byte range for archive retrieval jobs in the form StartByteValue -EndByteValue . If no range was specified in the archive retrieval, then the whole archive is retrieved. In this case, StartByteValue equals 0 and EndByteValue equals the size of the archive minus 1. For inventory retrieval or select jobs, this field is null.
Tier (string) --
The retrieval option to use for the archive retrieval. Valid values are Expedited , Standard , or Bulk . Standard is the default.
InventoryRetrievalParameters (dict) --
Parameters used for range inventory retrieval.
Format (string) --
The output format for the vault inventory list, which is set by the InitiateJob request when initiating a job to retrieve a vault inventory. Valid values are CSV and JSON .
StartDate (string) --
The start of the date range in Universal Coordinated Time (UTC) for vault inventory retrieval that includes archives created on or after this date. This value should be a string in the ISO 8601 date format, for example 2013-03-20T17:03:43Z .
EndDate (string) --
The end of the date range in UTC for vault inventory retrieval that includes archives created before this date. This value should be a string in the ISO 8601 date format, for example 2013-03-20T17:03:43Z .
Limit (string) --
The maximum number of inventory items returned per vault inventory retrieval request. This limit is set when initiating the job with the a InitiateJob request.
Marker (string) --
An opaque string that represents where to continue pagination of the vault inventory retrieval results. You use the marker in a new InitiateJob request to obtain additional inventory items. If there are no more inventory items, this value is null . For more information, see Range Inventory Retrieval .
JobOutputPath (string) --
Contains the job output location.
SelectParameters (dict) --
Contains the parameters that define a select job.
InputSerialization (dict) --
Describes the serialization format of the object.
csv (dict) --
Describes the serialization of a CSV-encoded object.
FileHeaderInfo (string) --
Describes the first line of input. Valid values are None , Ignore , and Use .
Comments (string) --
A single character used to indicate that a row should be ignored when the character is present at the start of that row.
QuoteEscapeCharacter (string) --
A single character used for escaping the quotation-mark character inside an already escaped value.
RecordDelimiter (string) --
A value used to separate individual records from each other.
FieldDelimiter (string) --
A value used to separate individual fields from each other within a record.
QuoteCharacter (string) --
A value used as an escape character where the field delimiter is part of the value.
ExpressionType (string) --
The type of the provided expression, for example SQL .
Expression (string) --
The expression that is used to select the object.
OutputSerialization (dict) --
Describes how the results of the select job are serialized.
csv (dict) --
Describes the serialization of CSV-encoded query results.
QuoteFields (string) --
A value that indicates whether all output fields should be contained within quotation marks.
QuoteEscapeCharacter (string) --
A single character used for escaping the quotation-mark character inside an already escaped value.
RecordDelimiter (string) --
A value used to separate individual records from each other.
FieldDelimiter (string) --
A value used to separate individual fields from each other within a record.
QuoteCharacter (string) --
A value used as an escape character where the field delimiter is part of the value.
OutputLocation (dict) --
Contains the location where the data from the select job is stored.
S3 (dict) --
Describes an S3 location that will receive the results of the restore request.
BucketName (string) --
The name of the bucket where the restore results are stored.
Prefix (string) --
The prefix that is prepended to the restore results for this request.
Encryption (dict) --
Contains information about the encryption used to store the job results in Amazon S3.
EncryptionType (string) --
The server-side encryption algorithm used when storing job results in Amazon S3, for example AES256 or aws:kms .
KMSKeyId (string) --
The AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS fail if not made by using Secure Sockets Layer (SSL) or Signature Version 4.
KMSContext (string) --
Optional. If the encryption type is aws:kms , you can use this value to specify the encryption context for the restore results.
CannedACL (string) --
The canned ACL to apply to the restore results.
AccessControlList (list) --
A list of grants that control access to the staged results.
(dict) --
Contains information about a grant.
Grantee (dict) --
The grantee.
Type (string) --
Type of grantee
DisplayName (string) --
Screen name of the grantee.
URI (string) --
URI of the grantee group.
ID (string) --
The canonical user ID of the grantee.
EmailAddress (string) --
Email address of the grantee.
Permission (string) --
Specifies the permission given to the grantee.
Tagging (dict) --
The tag-set that is applied to the restore results.
(string) --
(string) --
UserMetadata (dict) --
A map of metadata to store with the restore results in Amazon S3.
(string) --
(string) --
StorageClass (string) --
The storage class used to store the restore results.
{'jobParameters': {'OutputLocation': {'S3': {'AccessControlList': [{'Grantee': {'DisplayName': 'string',
'EmailAddress': 'string',
'ID': 'string',
'Type': 'AmazonCustomerByEmail '
'| '
'CanonicalUser '
'| '
'Group',
'URI': 'string'},
'Permission': 'FULL_CONTROL '
'| '
'WRITE '
'| '
'WRITE_ACP '
'| '
'READ '
'| '
'READ_ACP'}],
'BucketName': 'string',
'CannedACL': 'private | '
'public-read | '
'public-read-write | '
'aws-exec-read | '
'authenticated-read '
'| bucket-owner-read '
'| '
'bucket-owner-full-control',
'Encryption': {'EncryptionType': 'aws:kms '
'| '
'AES256',
'KMSContext': 'string',
'KMSKeyId': 'string'},
'Prefix': 'string',
'StorageClass': 'STANDARD | '
'REDUCED_REDUNDANCY '
'| STANDARD_IA',
'Tagging': {'string': 'string'},
'UserMetadata': {'string': 'string'}}},
'SelectParameters': {'Expression': 'string',
'ExpressionType': 'SQL',
'InputSerialization': {'csv': {'Comments': 'string',
'FieldDelimiter': 'string',
'FileHeaderInfo': 'USE '
'| '
'IGNORE '
'| '
'NONE',
'QuoteCharacter': 'string',
'QuoteEscapeCharacter': 'string',
'RecordDelimiter': 'string'}},
'OutputSerialization': {'csv': {'FieldDelimiter': 'string',
'QuoteCharacter': 'string',
'QuoteEscapeCharacter': 'string',
'QuoteFields': 'ALWAYS '
'| '
'ASNEEDED',
'RecordDelimiter': 'string'}}}}}
Response {'jobOutputPath': 'string'}
This operation initiates a job of the specified type, which can be a select, an archival retrieval, or a vault retrieval. For more information about using this operation, see the documentation for the underlying REST API Initiate a Job .
See also: AWS API Documentation
Request Syntax
client.initiate_job(
accountId='string',
vaultName='string',
jobParameters={
'Format': 'string',
'Type': 'string',
'ArchiveId': 'string',
'Description': 'string',
'SNSTopic': 'string',
'RetrievalByteRange': 'string',
'Tier': 'string',
'InventoryRetrievalParameters': {
'StartDate': 'string',
'EndDate': 'string',
'Limit': 'string',
'Marker': 'string'
},
'SelectParameters': {
'InputSerialization': {
'csv': {
'FileHeaderInfo': 'USE'|'IGNORE'|'NONE',
'Comments': 'string',
'QuoteEscapeCharacter': 'string',
'RecordDelimiter': 'string',
'FieldDelimiter': 'string',
'QuoteCharacter': 'string'
}
},
'ExpressionType': 'SQL',
'Expression': 'string',
'OutputSerialization': {
'csv': {
'QuoteFields': 'ALWAYS'|'ASNEEDED',
'QuoteEscapeCharacter': 'string',
'RecordDelimiter': 'string',
'FieldDelimiter': 'string',
'QuoteCharacter': 'string'
}
}
},
'OutputLocation': {
'S3': {
'BucketName': 'string',
'Prefix': 'string',
'Encryption': {
'EncryptionType': 'aws:kms'|'AES256',
'KMSKeyId': 'string',
'KMSContext': 'string'
},
'CannedACL': 'private'|'public-read'|'public-read-write'|'aws-exec-read'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
'AccessControlList': [
{
'Grantee': {
'Type': 'AmazonCustomerByEmail'|'CanonicalUser'|'Group',
'DisplayName': 'string',
'URI': 'string',
'ID': 'string',
'EmailAddress': 'string'
},
'Permission': 'FULL_CONTROL'|'WRITE'|'WRITE_ACP'|'READ'|'READ_ACP'
},
],
'Tagging': {
'string': 'string'
},
'UserMetadata': {
'string': 'string'
},
'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'STANDARD_IA'
}
}
}
)
string
[REQUIRED]
The AccountId value is the AWS account ID of the account that owns the vault. You can either specify an AWS account ID or optionally a single '- ' (hyphen), in which case Amazon Glacier uses the AWS account ID associated with the credentials used to sign the request. If you use an account ID, do not include any hyphens ('-') in the ID.
string
[REQUIRED]
The name of the vault.
dict
Provides options for specifying job information.
Format (string) --
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 are "CSV" and "JSON".
Type (string) --
The job type. You can initiate a job to perform a select query on an archive, retrieve an archive, or get an inventory of a vault. Valid values are "select", "archive-retrieval" and "inventory-retrieval".
ArchiveId (string) --
The ID of the archive that you want to retrieve. This field is required only if Type is set to select or archive-retrieval code>. An error occurs if you specify this request parameter for an inventory retrieval job request.
Description (string) --
The optional description for the job. 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.
SNSTopic (string) --
The Amazon SNS topic ARN to which 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.
RetrievalByteRange (string) --
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 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.
Tier (string) --
The retrieval option to use for a select or archive retrieval job. Valid values are Expedited , Standard , or Bulk . Standard is the default.
InventoryRetrievalParameters (dict) --
Input parameters used for range inventory retrieval.
StartDate (string) --
The start of the date range in UTC for vault inventory retrieval that includes archives created on or after this date. This value should be a string in the ISO 8601 date format, for example 2013-03-20T17:03:43Z .
EndDate (string) --
The end of the date range in UTC for vault inventory retrieval that includes archives created before this date. This value should be a string in the ISO 8601 date format, for example 2013-03-20T17:03:43Z .
Limit (string) --
Specifies the maximum number of inventory items returned per vault inventory retrieval request. Valid values are greater than or equal to 1.
Marker (string) --
An opaque string that represents where to continue pagination of the vault inventory retrieval results. You use the marker in a new InitiateJob request to obtain additional inventory items. If there are no more inventory items, this value is null .
SelectParameters (dict) --
Contains the parameters that define a job.
InputSerialization (dict) --
Describes the serialization format of the object.
csv (dict) --
Describes the serialization of a CSV-encoded object.
FileHeaderInfo (string) --
Describes the first line of input. Valid values are None , Ignore , and Use .
Comments (string) --
A single character used to indicate that a row should be ignored when the character is present at the start of that row.
QuoteEscapeCharacter (string) --
A single character used for escaping the quotation-mark character inside an already escaped value.
RecordDelimiter (string) --
A value used to separate individual records from each other.
FieldDelimiter (string) --
A value used to separate individual fields from each other within a record.
QuoteCharacter (string) --
A value used as an escape character where the field delimiter is part of the value.
ExpressionType (string) --
The type of the provided expression, for example SQL .
Expression (string) --
The expression that is used to select the object.
OutputSerialization (dict) --
Describes how the results of the select job are serialized.
csv (dict) --
Describes the serialization of CSV-encoded query results.
QuoteFields (string) --
A value that indicates whether all output fields should be contained within quotation marks.
QuoteEscapeCharacter (string) --
A single character used for escaping the quotation-mark character inside an already escaped value.
RecordDelimiter (string) --
A value used to separate individual records from each other.
FieldDelimiter (string) --
A value used to separate individual fields from each other within a record.
QuoteCharacter (string) --
A value used as an escape character where the field delimiter is part of the value.
OutputLocation (dict) --
Contains information about the location where the select job results are stored.
S3 (dict) --
Describes an S3 location that will receive the results of the restore request.
BucketName (string) --
The name of the bucket where the restore results are stored.
Prefix (string) --
The prefix that is prepended to the restore results for this request.
Encryption (dict) --
Contains information about the encryption used to store the job results in Amazon S3.
EncryptionType (string) --
The server-side encryption algorithm used when storing job results in Amazon S3, for example AES256 or aws:kms .
KMSKeyId (string) --
The AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS fail if not made by using Secure Sockets Layer (SSL) or Signature Version 4.
KMSContext (string) --
Optional. If the encryption type is aws:kms , you can use this value to specify the encryption context for the restore results.
CannedACL (string) --
The canned ACL to apply to the restore results.
AccessControlList (list) --
A list of grants that control access to the staged results.
(dict) --
Contains information about a grant.
Grantee (dict) --
The grantee.
Type (string) -- [REQUIRED]
Type of grantee
DisplayName (string) --
Screen name of the grantee.
URI (string) --
URI of the grantee group.
ID (string) --
The canonical user ID of the grantee.
EmailAddress (string) --
Email address of the grantee.
Permission (string) --
Specifies the permission given to the grantee.
Tagging (dict) --
The tag-set that is applied to the restore results.
(string) --
(string) --
UserMetadata (dict) --
A map of metadata to store with the restore results in Amazon S3.
(string) --
(string) --
StorageClass (string) --
The storage class used to store the restore results.
dict
Response Syntax
{
'location': 'string',
'jobId': 'string',
'jobOutputPath': 'string'
}
Response Structure
(dict) --
Contains the Amazon Glacier response to your request.
location (string) --
The relative URI path of the job.
jobId (string) --
The ID of the job.
jobOutputPath (string) --
The path to the location of where the select results are stored.
{'JobList': {'Action': ['Select'],
'JobOutputPath': 'string',
'OutputLocation': {'S3': {'AccessControlList': [{'Grantee': {'DisplayName': 'string',
'EmailAddress': 'string',
'ID': 'string',
'Type': 'AmazonCustomerByEmail '
'| '
'CanonicalUser '
'| '
'Group',
'URI': 'string'},
'Permission': 'FULL_CONTROL '
'| '
'WRITE '
'| '
'WRITE_ACP '
'| '
'READ '
'| '
'READ_ACP'}],
'BucketName': 'string',
'CannedACL': 'private | public-read | '
'public-read-write | '
'aws-exec-read | '
'authenticated-read | '
'bucket-owner-read | '
'bucket-owner-full-control',
'Encryption': {'EncryptionType': 'aws:kms '
'| '
'AES256',
'KMSContext': 'string',
'KMSKeyId': 'string'},
'Prefix': 'string',
'StorageClass': 'STANDARD | '
'REDUCED_REDUNDANCY | '
'STANDARD_IA',
'Tagging': {'string': 'string'},
'UserMetadata': {'string': 'string'}}},
'SelectParameters': {'Expression': 'string',
'ExpressionType': 'SQL',
'InputSerialization': {'csv': {'Comments': 'string',
'FieldDelimiter': 'string',
'FileHeaderInfo': 'USE '
'| '
'IGNORE '
'| '
'NONE',
'QuoteCharacter': 'string',
'QuoteEscapeCharacter': 'string',
'RecordDelimiter': 'string'}},
'OutputSerialization': {'csv': {'FieldDelimiter': 'string',
'QuoteCharacter': 'string',
'QuoteEscapeCharacter': 'string',
'QuoteFields': 'ALWAYS '
'| '
'ASNEEDED',
'RecordDelimiter': 'string'}}}}}
This operation lists jobs for a vault, including jobs that are in-progress and jobs that have recently finished. The List Job operation returns a list of these jobs sorted by job initiation time.
Note
Amazon Glacier retains recently completed jobs for a period before deleting them; however, it eventually removes completed jobs. The output of completed jobs can be retrieved. Retaining completed jobs for a period of time after they have completed enables you to get a job output in the event you miss the job completion notification or your first attempt to download it fails. For example, suppose you start an archive retrieval job to download an archive. After the job completes, you start to download the archive but encounter a network error. In this scenario, you can retry and download the archive while the job exists.
The List Jobs operation supports pagination. You should always check the response Marker field. If there are no more jobs to list, the Marker field is set to null . If there are more jobs to list, the Marker field is set to a non-null value, which you can use to continue the pagination of the list. To return a list of jobs that begins at a specific job, set the marker request parameter to the Marker value for that job that you obtained from a previous List Jobs request.
You can set a maximum limit for the number of jobs returned in the response by specifying the limit parameter in the request. The default limit is 1000. The number of jobs returned might be fewer than the limit, but the number of returned jobs never exceeds the limit.
Additionally, you can filter the jobs list returned by specifying the optional statuscode parameter or completed parameter, or both. Using the statuscode parameter, you can specify to return only jobs that match either the InProgress , Succeeded , or Failed status. Using the completed parameter, you can specify to return only jobs that were completed (true ) or jobs that were not completed (false ).
For more information about using this operation, see the documentation for the underlying REST API List Jobs .
See also: AWS API Documentation
Request Syntax
client.list_jobs(
accountId='string',
vaultName='string',
limit='string',
marker='string',
statuscode='string',
completed='string'
)
string
[REQUIRED]
The AccountId value is the AWS account ID of the account that owns the vault. You can either specify an AWS account ID or optionally a single '- ' (hyphen), in which case Amazon Glacier uses the AWS account ID associated with the credentials used to sign the request. If you use an account ID, do not include any hyphens ('-') in the ID.
string
[REQUIRED]
The name of the vault.
string
The maximum number of jobs to be returned. The default limit is 1000. The number of jobs returned might be fewer than the specified limit, but the number of returned jobs never exceeds the limit.
string
An opaque string used for pagination. This value specifies the job at which the listing of jobs should begin. Get the marker value from a previous List Jobs response. You only need to include the marker if you are continuing the pagination of results started in a previous List Jobs request.
string
The type of job status to return. You can specify the following values: InProgress , Succeeded , or Failed .
string
The state of the jobs to return. You can specify true or false .
dict
Response Syntax
{
'JobList': [
{
'JobId': 'string',
'JobDescription': 'string',
'Action': 'ArchiveRetrieval'|'InventoryRetrieval'|'Select',
'ArchiveId': 'string',
'VaultARN': 'string',
'CreationDate': 'string',
'Completed': True|False,
'StatusCode': 'InProgress'|'Succeeded'|'Failed',
'StatusMessage': 'string',
'ArchiveSizeInBytes': 123,
'InventorySizeInBytes': 123,
'SNSTopic': 'string',
'CompletionDate': 'string',
'SHA256TreeHash': 'string',
'ArchiveSHA256TreeHash': 'string',
'RetrievalByteRange': 'string',
'Tier': 'string',
'InventoryRetrievalParameters': {
'Format': 'string',
'StartDate': 'string',
'EndDate': 'string',
'Limit': 'string',
'Marker': 'string'
},
'JobOutputPath': 'string',
'SelectParameters': {
'InputSerialization': {
'csv': {
'FileHeaderInfo': 'USE'|'IGNORE'|'NONE',
'Comments': 'string',
'QuoteEscapeCharacter': 'string',
'RecordDelimiter': 'string',
'FieldDelimiter': 'string',
'QuoteCharacter': 'string'
}
},
'ExpressionType': 'SQL',
'Expression': 'string',
'OutputSerialization': {
'csv': {
'QuoteFields': 'ALWAYS'|'ASNEEDED',
'QuoteEscapeCharacter': 'string',
'RecordDelimiter': 'string',
'FieldDelimiter': 'string',
'QuoteCharacter': 'string'
}
}
},
'OutputLocation': {
'S3': {
'BucketName': 'string',
'Prefix': 'string',
'Encryption': {
'EncryptionType': 'aws:kms'|'AES256',
'KMSKeyId': 'string',
'KMSContext': 'string'
},
'CannedACL': 'private'|'public-read'|'public-read-write'|'aws-exec-read'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
'AccessControlList': [
{
'Grantee': {
'Type': 'AmazonCustomerByEmail'|'CanonicalUser'|'Group',
'DisplayName': 'string',
'URI': 'string',
'ID': 'string',
'EmailAddress': 'string'
},
'Permission': 'FULL_CONTROL'|'WRITE'|'WRITE_ACP'|'READ'|'READ_ACP'
},
],
'Tagging': {
'string': 'string'
},
'UserMetadata': {
'string': 'string'
},
'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'STANDARD_IA'
}
}
},
],
'Marker': 'string'
}
Response Structure
(dict) --
Contains the Amazon Glacier response to your request.
JobList (list) --
A list of job objects. Each job object contains metadata describing the job.
(dict) --
Contains the description of an Amazon Glacier job.
JobId (string) --
An opaque string that identifies an Amazon Glacier job.
JobDescription (string) --
The job description provided when initiating the job.
Action (string) --
The job type. This value is either ArchiveRetrieval , InventoryRetrieval , or Select .
ArchiveId (string) --
The archive ID requested for a select job or archive retrieval. Otherwise, this field is null.
VaultARN (string) --
The Amazon Resource Name (ARN) of the vault from which an archive retrieval was requested.
CreationDate (string) --
The UTC date when the job was created. This value is a string representation of ISO 8601 date format, for example "2012-03-20T17:03:43.221Z" .
Completed (boolean) --
The job status. When a job is completed, you get the job's output using Get Job Output (GET output).
StatusCode (string) --
The status code can be InProgress , Succeeded , or Failed , and indicates the status of the job.
StatusMessage (string) --
A friendly message that describes the job status.
ArchiveSizeInBytes (integer) --
For an archive retrieval job, this value is the size in bytes of the archive being requested for download. For an inventory retrieval or select job, this value is null.
InventorySizeInBytes (integer) --
For an inventory retrieval job, this value is the size in bytes of the inventory requested for download. For an archive retrieval or select job, this value is null.
SNSTopic (string) --
An Amazon SNS topic that receives notification.
CompletionDate (string) --
The UTC time that the job request completed. While the job is in progress, the value is null.
SHA256TreeHash (string) --
For an archive retrieval job, this value is the checksum of the archive. Otherwise, this value is null.
The SHA256 tree hash value for the requested range of an archive. If the InitiateJob request for an archive specified a tree-hash aligned range, then this field returns a value.
If the whole archive is retrieved, this value is the same as the ArchiveSHA256TreeHash value.
This field is null for the following:
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, when the job status is InProgress
Inventory jobs
Select jobs
ArchiveSHA256TreeHash (string) --
The SHA256 tree hash of the entire archive for an archive retrieval. For inventory retrieval or select jobs, this field is null.
RetrievalByteRange (string) --
The retrieved byte range for archive retrieval jobs in the form StartByteValue -EndByteValue . If no range was specified in the archive retrieval, then the whole archive is retrieved. In this case, StartByteValue equals 0 and EndByteValue equals the size of the archive minus 1. For inventory retrieval or select jobs, this field is null.
Tier (string) --
The retrieval option to use for the archive retrieval. Valid values are Expedited , Standard , or Bulk . Standard is the default.
InventoryRetrievalParameters (dict) --
Parameters used for range inventory retrieval.
Format (string) --
The output format for the vault inventory list, which is set by the InitiateJob request when initiating a job to retrieve a vault inventory. Valid values are CSV and JSON .
StartDate (string) --
The start of the date range in Universal Coordinated Time (UTC) for vault inventory retrieval that includes archives created on or after this date. This value should be a string in the ISO 8601 date format, for example 2013-03-20T17:03:43Z .
EndDate (string) --
The end of the date range in UTC for vault inventory retrieval that includes archives created before this date. This value should be a string in the ISO 8601 date format, for example 2013-03-20T17:03:43Z .
Limit (string) --
The maximum number of inventory items returned per vault inventory retrieval request. This limit is set when initiating the job with the a InitiateJob request.
Marker (string) --
An opaque string that represents where to continue pagination of the vault inventory retrieval results. You use the marker in a new InitiateJob request to obtain additional inventory items. If there are no more inventory items, this value is null . For more information, see Range Inventory Retrieval .
JobOutputPath (string) --
Contains the job output location.
SelectParameters (dict) --
Contains the parameters that define a select job.
InputSerialization (dict) --
Describes the serialization format of the object.
csv (dict) --
Describes the serialization of a CSV-encoded object.
FileHeaderInfo (string) --
Describes the first line of input. Valid values are None , Ignore , and Use .
Comments (string) --
A single character used to indicate that a row should be ignored when the character is present at the start of that row.
QuoteEscapeCharacter (string) --
A single character used for escaping the quotation-mark character inside an already escaped value.
RecordDelimiter (string) --
A value used to separate individual records from each other.
FieldDelimiter (string) --
A value used to separate individual fields from each other within a record.
QuoteCharacter (string) --
A value used as an escape character where the field delimiter is part of the value.
ExpressionType (string) --
The type of the provided expression, for example SQL .
Expression (string) --
The expression that is used to select the object.
OutputSerialization (dict) --
Describes how the results of the select job are serialized.
csv (dict) --
Describes the serialization of CSV-encoded query results.
QuoteFields (string) --
A value that indicates whether all output fields should be contained within quotation marks.
QuoteEscapeCharacter (string) --
A single character used for escaping the quotation-mark character inside an already escaped value.
RecordDelimiter (string) --
A value used to separate individual records from each other.
FieldDelimiter (string) --
A value used to separate individual fields from each other within a record.
QuoteCharacter (string) --
A value used as an escape character where the field delimiter is part of the value.
OutputLocation (dict) --
Contains the location where the data from the select job is stored.
S3 (dict) --
Describes an S3 location that will receive the results of the restore request.
BucketName (string) --
The name of the bucket where the restore results are stored.
Prefix (string) --
The prefix that is prepended to the restore results for this request.
Encryption (dict) --
Contains information about the encryption used to store the job results in Amazon S3.
EncryptionType (string) --
The server-side encryption algorithm used when storing job results in Amazon S3, for example AES256 or aws:kms .
KMSKeyId (string) --
The AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS fail if not made by using Secure Sockets Layer (SSL) or Signature Version 4.
KMSContext (string) --
Optional. If the encryption type is aws:kms , you can use this value to specify the encryption context for the restore results.
CannedACL (string) --
The canned ACL to apply to the restore results.
AccessControlList (list) --
A list of grants that control access to the staged results.
(dict) --
Contains information about a grant.
Grantee (dict) --
The grantee.
Type (string) --
Type of grantee
DisplayName (string) --
Screen name of the grantee.
URI (string) --
URI of the grantee group.
ID (string) --
The canonical user ID of the grantee.
EmailAddress (string) --
Email address of the grantee.
Permission (string) --
Specifies the permission given to the grantee.
Tagging (dict) --
The tag-set that is applied to the restore results.
(string) --
(string) --
UserMetadata (dict) --
A map of metadata to store with the restore results in Amazon S3.
(string) --
(string) --
StorageClass (string) --
The storage class used to store the restore results.
Marker (string) --
An opaque string used for pagination that specifies the job at which the listing of jobs should begin. You get the marker value from a previous List Jobs response. You only need to include the marker if you are continuing the pagination of the results started in a previous List Jobs request.