Amazon S3 Glacier Data Model - Amazon S3 Glacier
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

This page is only for existing customers of the S3 Glacier service using Vaults and the original REST API from 2012.

If you're looking for archival storage solutions we suggest using the S3 Glacier storage classes in Amazon S3, S3 Glacier Instant Retrieval, S3 Glacier Flexible Retrieval, and S3 Glacier Deep Archive. To learn more about these storage options, see S3 Glacier storage classes and Long-term data storage using S3 Glacier storage classes in the Amazon S3 User Guide. These storage classes use the Amazon S3 API, are available in all regions, and can be managed within the Amazon S3 console. They offer features like Storage Cost Analysis, Storage Lens, advanced optional encryption features, and more.

Amazon S3 Glacier Data Model

The Amazon S3 Glacier data model core components include vaults and archives. S3 Glacier is a REST-based web service. In terms of REST, vaults and archives are the resources. In addition, the S3 Glacier data model includes job and notification-configuration resources. These resources complement the core resources.

Vault

In S3 Glacier, a vault is a container for storing archives. A vault is similar to an Amazon S3 bucket. When you create a vault, you specify a name and choose an Amazon Web Services Region where you want to create the vault.

Each vault resource has a unique address. The general form is:

https://region-specific-endpoint/account-id/vaults/vault-name

For example, suppose that you create a vault (examplevault) in the US West (Oregon) Region in your account with the ID 111122223333. You can address this vault by using the following URI:

https://glacier.us-west-2.amazonaws.com.cn/111122223333/vaults/examplevault

Here is what the various components of the URI mean:

  • glacier.us-west-2.amazonaws.com.cn identifies the US West (Oregon) Region.

  • 111122223333 is the Amazon Web Services account ID that owns the vault.

  • vaults refers to the collection of vaults that are owned by the Amazon Web Services account.

  • examplevault identifies a specific vault in the vaults collection.

An Amazon Web Services account can create vaults in any supported Amazon Web Services Region. For list of supported Amazon Web Services Regions, see Accessing Amazon S3 Glacier. Within a Region, an account must use unique vault names. An Amazon Web Services account can create same-named vaults in different Regions.

You can store an unlimited number of archives in a vault. Depending on your business or application needs, you can store these archives in one vault or multiple vaults.

S3 Glacier supports various vault operations. Vault operations are Region-specific. For example, when you create a vault, you create it in a specific Region. When you request a vault list, you request it from a specific Amazon Web Services Region, and the resulting list includes only vaults created in that specific Region.

Archive

An archive can be any data, such as a photo, video, or document. An archive is similar to an Amazon S3 object, and is the base unit of storage in S3 Glacier. Each archive has a unique ID and an optional description. You can specify this optional description only during the upload of an archive. S3 Glacier assigns the archive an ID, which is unique in the Amazon Web Services Region in which the archive is stored.

Each archive has a unique address. The general form is as follows:

https://region-specific-endpoint/account-id/vaults/vault-name/archives/archive-id

The following is an example URI of an archive stored in the examplevault vault in the US West (Oregon) Region in account 111122223333:

https://glacier.us-west-2.amazonaws.com.cn/111122223333/vaults/examplevault/archives/NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId

You can store an unlimited number of archives in a vault.

Job

An S3 Glacier job can retrieve an archive, or get an inventory of a vault.

Retrieving archives and vault inventories (lists of archives) are asynchronous operations in S3 Glacier, in which you first initiate a job, and then download the job output after S3 Glacier completes the job.

Note

S3 Glacier offers a cold-storage data-archival solution. If your application needs a storage solution that requires real-time data retrieval, you might consider using Amazon S3. For more information, see Amazon Simple Storage Service (Amazon S3).

To initiate a vault inventory job, you provide a vault name. Archive retrieval jobs require both the vault name and the archive ID. You can also provide an optional job description to help identify the jobs.

Archive retrieval and vault inventory jobs are associated with a vault. A vault can have multiple jobs in progress at any point in time. When you send a job request (initiate a job), S3 Glacier returns to you a job ID to track the job. Each job is uniquely identified by a URI of the form:

https://region-specific-endpoint/account-id/vaults/vault-name/jobs/job-id

The following is an example of a job associated with an examplevault vault in the US West (Oregon) Region in account 111122223333.

https://glacier.us-west-2.amazonaws.com.cn/111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID

For each job, S3 Glacier maintains information, such as the job type, description, creation date, completion date, and job status. You can obtain information about a specific job or obtain a list of all your jobs associated with a vault. The list of jobs that S3 Glacier returns includes all the in-progress and recently finished jobs.

Notification Configuration

Because jobs take time to run, S3 Glacier supports a notification mechanism to notify you when a job is completed. You can configure a vault to send a notification to an Amazon Simple Notification Service (Amazon SNS) topic when a job is completed. You can specify one Amazon SNS topic per vault in the notification configuration.

S3 Glacier stores the notification configuration as a JSON document. The following is an example vault notification configuration:

{ "Topic": "arn:aws-cn:sns:us-west-2:111122223333:mytopic", "Events": ["ArchiveRetrievalCompleted", "InventoryRetrievalCompleted"] }

Notification configurations are associated with vaults; you can have one for each vault. Each notification configuration resource is uniquely identified by a URI of the form:

https://region-specific-endpoint/account-id/vaults/vault-name/notification-configuration

S3 Glacier supports operations to set, get, and delete a notification configuration. When you delete a notification configuration, no notifications are sent when any data retrieval operation on the vault is completed.