2016/11/22 - Amazon Glacier - 2 new 3 updated api methods
Changes Allow customers to retrieve their data with different tiers.
This operation purchases a provisioned capacity unit for an AWS account.
Request Syntax
client.purchase_provisioned_capacity(
accountId='string'
)
string
[REQUIRED]
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, don't include any hyphens ('-') in the ID.
dict
Response Syntax
{
'capacityId': 'string'
}
Response Structure
(dict) --
capacityId (string) --
The ID that identifies the provisioned capacity unit.
This operation lists the provisioned capacity for the specified AWS account.
Request Syntax
client.list_provisioned_capacity(
accountId='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, don't include any hyphens ('-') in the ID.
dict
Response Syntax
{
'ProvisionedCapacityList': [
{
'CapacityId': 'string',
'StartDate': 'string',
'ExpirationDate': 'string'
},
]
}
Response Structure
(dict) --
ProvisionedCapacityList (list) --
The response body contains the following JSON fields.
(dict) --
The definition for a provisioned capacity unit.
CapacityId (string) --
The ID that identifies the provisioned capacity unit.
StartDate (string) --
The date that the provisioned capacity unit was purchased, in Universal Coordinated Time (UTC).
ExpirationDate (string) --
The date that the provisioned capacity unit expires, in Universal Coordinated Time (UTC).
{'Tier': '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 information about the underlying REST API, see Working with Archives in Amazon Glacier in the Amazon Glacier Developer Guide .
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',
'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'
}
}
Response Structure
(dict) --
Describes an Amazon Glacier job.
JobId (string) --
An opaque string that identifies an Amazon Glacier job.
JobDescription (string) --
The job description you provided when you initiated the job.
Action (string) --
The job type. It is either ArchiveRetrieval or InventoryRetrieval.
ArchiveId (string) --
For an ArchiveRetrieval job, this is the archive ID requested for download. Otherwise, this field is null.
VaultARN (string) --
The Amazon Resource Name (ARN) of the vault from which the archive retrieval was requested.
CreationDate (string) --
The UTC date when the job was created. 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.
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 ArchiveRetrieval job, this is the size in bytes of the archive being requested for download. For the InventoryRetrieval job, the value is null.
InventorySizeInBytes (integer) --
For an InventoryRetrieval job, this is the size in bytes of the inventory requested for download. For the ArchiveRetrieval job, the value is null.
SNSTopic (string) --
An Amazon Simple Notification Service (Amazon SNS) topic that receives notification.
CompletionDate (string) --
The UTC time that the archive retrieval request completed. While the job is in progress, the value will be null.
SHA256TreeHash (string) --
For an ArchiveRetrieval job, it is the checksum of the archive. Otherwise, the value is null.
The SHA256 tree hash value for the requested range of an archive. If the Initiate a Job request for an archive specified a tree-hash aligned range, then this field returns a value.
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.
ArchiveSHA256TreeHash (string) --
The SHA256 tree hash of the entire archive for an archive retrieval. For inventory retrieval 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 and StartByteValue equals 0 and EndByteValue equals the size of the archive minus 1. For inventory retrieval 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.
{'jobParameters': {'Tier': 'string'}}
This operation initiates a job of the specified type. In this release, you can initiate a job to retrieve either an archive or a vault inventory (a list of archives in a vault).
Retrieving data from Amazon Glacier is a two-step process:
Initiate a retrieval job.
Note
A data retrieval policy can cause your initiate retrieval job request to fail with a PolicyEnforcedException exception. For more information about data retrieval policies, see Amazon Glacier Data Retrieval Policies. For more information about the PolicyEnforcedException exception, see Error Responses.
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 GetJobOutput operation.
The job must complete before you can get its output. To determine when a job is complete, you have the following options:
Use 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 always sent. For more information, see SetVaultNotifications.
Get job details You can make a DescribeJob 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 DescribeJob.
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 SetVaultNotifications.
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).
About the Vault Inventory
Amazon Glacier prepares an inventory for each vault periodically, every 24 hours. When you initiate a job for a vault inventory, Amazon Glacier returns the last inventory for the vault. The inventory data you get might be up to a day or two days old. Also, the initiate inventory job might take some time to complete before you can download the vault inventory. So you do not want to retrieve a vault inventory for each vault operation. However, in some scenarios, you might find the vault inventory useful. For example, when you upload an archive, you can provide an archive description but not an archive name. Amazon Glacier provides you a unique archive ID, an opaque string of characters. So, you might maintain your own database that maps archive names to their corresponding Amazon Glacier assigned archive IDs. You might find the vault inventory useful in the event you need to reconcile information in your database with the actual vault inventory.
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 InitiateJob 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 InitiateJob 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 DescribeJob operation to get a marker that you use in a subsequent InitiateJob 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 InitiateJob requests with the marker from the previous DescribeJob output, until you get a marker from DescribeJob that returns null, indicating that there are no more inventory items available.
You can use the Limit parameter together with the date range parameters.
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 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 API, the range must be tree hash aligned.
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 conceptual information and the underlying REST API, see Initiate a Job and Downloading a Vault Inventory
Expedited and Bulk Archive Retrievals
When retrieving an archive, you can specify one of the following options in the Tier field of the request body:
Standard The default type of retrieval, which allows access to any of your archives within several hours. Standard retrievals typically complete within 3–5 hours.
Bulk Amazon Glacier’s lowest-cost retrieval option, which enables you to retrieve large amounts of data inexpensively in a day. Bulk retrieval requests typically complete within 5–12 hours.
Expedited Amazon Glacier’s option for the fastest retrievals. Archives requested using the expedited retrievals typically become accessible within 1–5 minutes.
For more information about expedited and bulk retrievals, see Retrieving Amazon Glacier Archives.
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'
}
}
)
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 retrieve an archive or get an inventory of a vault. Valid values are "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 archive-retrieval. 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 the archive retrieval. 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 .
dict
Response Syntax
{
'location': 'string',
'jobId': '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.
{'JobList': {'Tier': 'string'}}
This operation lists jobs for a vault, including jobs that are in-progress and jobs that have recently finished.
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.
To retrieve an archive or retrieve a vault inventory from Amazon Glacier, you first initiate a job, and after the job completes, you download the data. For an archive retrieval, the output is the archive data. For an inventory retrieval, it is the inventory list. The List Job operation returns a list of these jobs sorted by job initiation time.
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 the underlying REST API, see List Jobs.
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',
'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'
}
},
],
'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) --
Describes an Amazon Glacier job.
JobId (string) --
An opaque string that identifies an Amazon Glacier job.
JobDescription (string) --
The job description you provided when you initiated the job.
Action (string) --
The job type. It is either ArchiveRetrieval or InventoryRetrieval.
ArchiveId (string) --
For an ArchiveRetrieval job, this is the archive ID requested for download. Otherwise, this field is null.
VaultARN (string) --
The Amazon Resource Name (ARN) of the vault from which the archive retrieval was requested.
CreationDate (string) --
The UTC date when the job was created. 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.
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 ArchiveRetrieval job, this is the size in bytes of the archive being requested for download. For the InventoryRetrieval job, the value is null.
InventorySizeInBytes (integer) --
For an InventoryRetrieval job, this is the size in bytes of the inventory requested for download. For the ArchiveRetrieval job, the value is null.
SNSTopic (string) --
An Amazon Simple Notification Service (Amazon SNS) topic that receives notification.
CompletionDate (string) --
The UTC time that the archive retrieval request completed. While the job is in progress, the value will be null.
SHA256TreeHash (string) --
For an ArchiveRetrieval job, it is the checksum of the archive. Otherwise, the value is null.
The SHA256 tree hash value for the requested range of an archive. If the Initiate a Job request for an archive specified a tree-hash aligned range, then this field returns a value.
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.
ArchiveSHA256TreeHash (string) --
The SHA256 tree hash of the entire archive for an archive retrieval. For inventory retrieval 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 and StartByteValue equals 0 and EndByteValue equals the size of the archive minus 1. For inventory retrieval 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.
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.