Esta página é somente para clientes existentes do serviço S3 Glacier que usam o Vaults e o original de 2012. REST API
Se você estiver procurando por soluções de armazenamento de arquivamento, sugerimos usar as classes de armazenamento S3 Glacier no Amazon S3, S3 Glacier Instant Retrieval, S3 Glacier Flexible Retrieval e S3 Glacier Deep Archive. Para saber mais sobre essas opções de armazenamento, consulte Classes de armazenamento S3 Glacier e Armazenamento de dados de longo prazo usando classes
As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Initiate Job (POSTtrabalhos)
Essa operação inicia os seguintes tipos de trabalhos no Amazon S3 Glacier (S3 Glacier):
-
archive-retrieval
: recupera um arquivo -
inventory-retrieval
: cria um inventário de um cofre
Tópicos
Inicialização de um trabalho de recuperação de arquivo ou inventário de cofre
Recuperar um arquivo ou um inventário de cofre são operações assíncronas que exigem que você inicie um trabalho. Após ser iniciado, o trabalho não pode ser cancelado. A recuperação é um processo de duas etapas:
-
Inicie um trabalho de recuperação usando a operação Initiate Job (POSTtrabalhos).
Importante
Uma política de recuperação de dados pode fazer com que a solicitação do trabalho de recuperação de inicialização apresente falha com
PolicyEnforcedException
. Para obter mais informações sobre políticas de recuperação de dados, consulte Políticas de recuperação de dados do S3 Glacier. Para obter mais informações sobre a exceçãoPolicyEnforcedException
, consulte Respostas de erro. -
Após a conclusão do trabalho, faça download dos bytes usando a operação Get Job Output (GET output).
A solicitação de recuperação é executada de maneira assíncrona. Quando você inicia um trabalho de recuperação, o S3 Glacier cria um trabalho e retorna um ID de trabalho na resposta. Quando o S3 Glacier conclui o trabalho, você pode receber a saída do trabalho (dados do arquivo ou do inventário). Para saber informações sobre como obter a saída do trabalho, consulte a operação Get Job Output (GET output).
O trabalho deverá ser concluído para você obter a saída. Para determinar quando um trabalho está concluído, você tem as seguintes opções:
-
Use uma SNS notificação da Amazon — Você pode especificar um SNS tópico da Amazon para o qual o S3 Glacier pode publicar uma notificação após a conclusão do trabalho. Você pode especificar um SNS tópico por solicitação de trabalho. A notificação será enviada somente depois que o S3 Glacier concluir o trabalho. Além de especificar um SNS tópico por solicitação de trabalho, você pode configurar as notificações do cofre para um cofre para que as notificações de trabalho sejam enviadas para todas as recuperações. Para ter mais informações, consulte Definir configuração de notificação de cofre (PUT notification-configuration).
-
Obter detalhes do trabalho:você pode fazer uma solicitação Trabalho de descrição (GET JobID) para obter informações de status do trabalho enquanto um trabalho está em andamento. No entanto, é mais eficiente usar uma SNS notificação da Amazon para determinar quando um trabalho foi concluído.
nota
As informações obtidas por você por meio da notificação são as mesmas recebidas quando se chama Trabalho de descrição (GET JobID).
Se, para um evento específico, você adicionar a configuração de notificação no cofre e também especificar um SNS tópico em sua solicitação de início de trabalho, o S3 Glacier enviará as duas notificações. Para ter mais informações, consulte Definir configuração de notificação de cofre (PUT notification-configuration).
O inventário de cofre
O S3 Glacier atualiza um inventário de cofre aproximadamente uma vez por dia, começando no dia em que você faz o primeiro upload para o cofre. Se não houver adições ou exclusões de arquivo no cofre desde o último inventário, a data do inventário não será atualizada. Quando você inicia um trabalho para um inventário do cofre, o S3 Glacier retorna o último inventário gerado, que é um point-in-time instantâneo e não dados em tempo real.
Depois que o S3 Glacier criar o primeiro inventário para o cofre, normalmente levará de meio dia a um dia para que esse inventário esteja disponível para recuperação.
Talvez você não ache útil recuperar um inventário de cofre para cada upload de arquivo. No entanto, suponhamos que você mantenha um banco de dados no lado do cliente associando metadados sobre os arquivos cujo upload fez para o S3 Glacier. Nesse caso, talvez você ache o inventário de cofre útil para reconciliar informações, conforme necessário, no seu banco de dados com o inventário de cofre real. Para obter mais informações sobre os campos de dados retornados em uma saída do trabalho de inventário, consulte Corpo da resposta.
Recuperação do inventário de intervalo
Você pode limitar o número de itens do inventário recuperados filtrando a data de criação do arquivo ou definindo um limite.
Filtrar por data de criação do arquivo
Você pode recuperar itens de inventário para arquivos criados entre StartDate
e EndDate
especificando valores para esses parâmetros na solicitação Iniciar trabalho. Os arquivos criados em StartDate
ou após essa data e antes de EndDate
serão retornados. Se fornecer somente StartDate
sem EndDate
, recuperará o inventário de todos os arquivos criados em StartDate
ou após essa data. Se fornecer somente EndDate
sem StartDate
, terá de volta o inventário de todos os arquivos criados antes de EndDate
.
Limitar itens de inventário por recuperação
Você pode limitar o número de itens de inventário retornados definindo o parâmetro Limit
na solicitação Iniciar trabalho. A saída do trabalho de inventário contém itens de inventário até o Limit
especificado. Se houver mais itens de inventário disponíveis, o resultado será paginado. Depois que um trabalho for concluído, você poderá usar a operação Trabalho de descrição (GET JobID) para obter um marcador a ser usado em uma solicitação subsequente Iniciar trabalho. O marcador indicará o ponto de partida para recuperar o próximo conjunto de itens de inventário. Você pode percorrer todo o inventário fazendo várias solicitações de Iniciar trabalho com o marcador da saída anterior de Descrever trabalho. Para fazer isso, obtenha um marcador em Descrever trabalho que retorne um valor nulo, indicando que não há mais itens de inventário disponíveis.
Você pode usar o parâmetro Limit
com os parâmetros do intervalo de datas.
Recuperação do arquivo no intervalo
Você pode iniciar a recuperação de todo o arquivo ou de um intervalo do arquivo. No caso da recuperação de um intervalo do arquivo, você especifica um intervalo de bytes a ser retornado ou todo o arquivo. O intervalo especificado deve ser alinhado a megabyte (MB). Em outras palavras, o valor de início do intervalo deve ser divisível por 1 MB e o valor final do intervalo mais 1 deve ser divisível por 1 MB ou igual ao final do arquivo. Se a recuperação do arquivo no intervalo não estiver alinhada a megabyte, essa operação retornará uma resposta 400
. Além disso, para garantir que você obtenha valores da soma de verificação dos dados cujo download você faz usando Obter saída de trabalho (Get Job Output (GET output)), o intervalo deve estar alinhado ao hash de árvore. Para obter mais informações sobre intervalos alinhados ao hash de árvore, consulte Receber somas de verificação durante o download de dados.
Níveis expressos, padrão e em massa
Ao iniciar um trabalho de recuperação de arquivo, você pode especificar uma das seguintes opções no campo Tier
do corpo da solicitação:
-
Expedited
: expresso permite que você acesse rapidamente seus dados quando são feitas solicitações de urgência ocasionais para recuperar arquivos. Exceto para os arquivos maiores (mais de 250 MB), os dados acessados por meio de níveis expressos são disponibilizados geralmente entre 1 e 5 minutos. -
Standard
: padrão permite que você acesse qualquer um dos arquivos em várias horas. Os dados acessados usando o nível Padrão normalmente são disponibilizados entre 3 e 5 horas. Essa é a opção padrão para solicitações de trabalho que não especificam a opção de nível. -
Bulk
: em massa é o nível de menor custo do S3 Glacier, permitindo recuperar grandes quantidades de dados, até mesmo petabytes, em um dia e com um custo baixo. Os dados acessados usando o nível Em massa normalmente são disponibilizados entre 5 e 12 horas.
Para obter mais informações recuperações expressas e em massa, consulte Recuperando arquivos do S3 Glacier usando o console AWS.
Solicitações
Para iniciar um trabalho, você usa o HTTP POST
método e define o escopo da solicitação para o sub-recurso do jobs
cofre. Você especifica os detalhes da solicitação de trabalho no JSON documento da sua solicitação. O tipo de trabalho é especificado com o campo Type
. Opcionalmente, você pode especificar um SNSTopic
campo para indicar um SNS tópico da Amazon para o qual o S3 Glacier pode publicar uma notificação após concluir o trabalho.
nota
Para publicar uma notificação na AmazonSNS, você mesmo deve criar o tópico, caso ele ainda não exista. O S3 Glacier não cria o tópico para você. O tópico deve ter permissões para receber publicações de um cofre do S3 Glacier. O S3 Glacier não verifica se o cofre tem permissão para publicação no tópico. Se as permissões não forem configuradas corretamente, talvez você não receba uma notificação, mesmo depois da conclusão do trabalho.
Sintaxe
Esta é a sintaxe de solicitação para iniciar um trabalho.
POST /
AccountId
/vaults/VaultName
/jobs HTTP/1.1 Host: glacier.Region
.amazonaws.com Date:Date
Authorization:SignatureValue
x-amz-glacier-version: 2012-06-01 { "jobParameters": { "ArchiveId": "string
", "Description": "string
", "Format": "string
", "InventoryRetrievalParameters": { "EndDate": "string
", "Limit": "string
", "Marker": "string
", "StartDate": "string
" }, "OutputLocation": { "S3": { "AccessControlList": [ { "Grantee": { "DisplayName": "string
", "EmailAddress": "string
", "ID": "string
", "Type": "string
", "URI": "string
" }, "Permission": "string
" } ], "BucketName": "string
", "CannedACL": "string
", "Encryption": { "EncryptionType": "string
", "KMSContext": "string
", "KMSKeyId": "string
" }, "Prefix": "string
", "StorageClass": "string
", "Tagging": { "string
" : "string
" }, "UserMetadata": { "string
" : "string
" } } }, "RetrievalByteRange": "string
", "SelectParameters": { "Expression": "string
", "ExpressionType": "string
", "InputSerialization": { "csv": { "Comments": "string
", "FieldDelimiter": "string
", "FileHeaderInfo": "string
", "QuoteCharacter": "string
", "QuoteEscapeCharacter": "string
", "RecordDelimiter": "string
" } }, "OutputSerialization": { "csv": { "FieldDelimiter": "string
", "QuoteCharacter": "string
", "QuoteEscapeCharacter": "string
", "QuoteFields": "string
", "RecordDelimiter": "string
" } } }, "SNSTopic": "string
", "Tier": "string
", "Type": "string
" } }
nota
O AccountId
valor é o Conta da AWS ID da conta proprietária do cofre. Você pode especificar uma Conta da AWS ID ou, opcionalmente, um único '-
' (hífen). Nesse caso, o Amazon S3 Glacier usa Conta da AWS a ID associada às credenciais usadas para assinar a solicitação. Se você usar um ID de conta, não inclua nenhum hífen ('-') no ID.
Corpo da Solicitação
A solicitação aceita os seguintes dados em JSON formato no corpo da solicitação.
- jobParameters
-
Fornece opções para especificar as informações do trabalho.
Tipo: jobParameters objeto
Obrigatório: Sim
Respostas
O S3 Glacier cria o trabalho. Na resposta, ele retorna o URI do trabalho.
Sintaxe
HTTP/1.1 202 Accepted x-amzn-RequestId: x-amzn-RequestId Date: Date Location:
location
x-amz-job-id:jobId
x-amz-job-output-path:jobOutputPath
Cabeçalhos de resposta
Cabeçalho | Descrição |
---|---|
Location |
O URI caminho relativo do trabalho. Você pode usar esse URI caminho para encontrar o status do trabalho. Para ter mais informações, consulte Trabalho de descrição (GET JobID). Tipo: string Padrão: nenhum |
x-amz-job-id |
O ID do trabalho. Esse valor também está incluído como parte do cabeçalho Tipo: string Padrão: nenhum |
x-amz-job-output-path |
O caminho para o local onde os resultados de seleção são armazenados. Tipo: string Padrão: nenhum |
Corpo da resposta
Essa operação não retorna um corpo de resposta.
Erros
Essa operação inclui os seguintes erros, além dos possíveis erros comuns a todas as operações do Amazon S3 Glacier. Para obter informações sobre erros do Amazon S3 Glacier e uma lista de códigos de erro, consulte Respostas de erro.
Código | Descrição | HTTPCódigo de status | Tipo |
---|---|---|---|
InsufficientCapacityException |
Retornado se houver capacidade insuficiente para processar essa solicitação expressa. Esse erro se aplica somente a recuperações expressas, e não a recuperações padrão ou em massa. | 503 Service Unavailable |
Servidor |
Exemplos
Solicitação de exemplo: iniciar um trabalho de recuperação do arquivo
POST /-/vaults/examplevault/jobs HTTP/1.1 Host: glacier.us-west-2.amazonaws.com x-amz-Date: 20170210T120000Z x-amz-glacier-version: 2012-06-01 Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/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-west-2:111111111111:Glacier-ArchiveRetrieval-topic-Example", "Tier" : "Bulk" }
Este é um exemplo do corpo de uma solicitação que especifica um intervalo do arquivo a ser recuperado usando-se o campo RetrievalByteRange
.
{ "Type": "archive-retrieval", "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId", "Description": "My archive description", "RetrievalByteRange": "2097152-4194303", "SNSTopic": "arn:aws:sns:us-west-2:111111111111:Glacier-ArchiveRetrieval-topic-Example", "Tier" : "Bulk" }
Exemplo de resposta
HTTP/1.1 202 Accepted x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q Date: Wed, 10 Feb 2017 12:00:00 GMT Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID
Solicitação de exemplo: iniciar um trabalho de recuperação do inventário
A solicitação a seguir inicia um trabalho de recuperação do inventário para obter uma lista de arquivos do cofre examplevault
. O Format
valor definido como CSV
no corpo da solicitação indica que o inventário é devolvido no CSV formato.
POST /-/vaults/examplevault/jobs HTTP/1.1 Host: glacier.us-west-2.amazonaws.com x-amz-Date: 20170210T120000Z Content-Type: application/x-www-form-urlencoded x-amz-glacier-version: 2012-06-01 Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/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-west-2:111111111111:Glacier-InventoryRetrieval-topic-Example" }
Exemplo de resposta
HTTP/1.1 202 Accepted x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q Date: Wed, 10 Feb 2017 12:00:00 GMT Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID
Exemplos de solicitações: Iniciar um trabalho de recuperação de inventário usando a filtragem de dados com um limite definido e uma solicitação posterior para recuperar a próxima página dos itens de inventário.
A solicitação a seguir inicia um trabalho de recuperação de inventário de cofre usando a filtragem de data e definindo um limite.
{ "ArchiveId": null, "Description": null, "Format": "CSV", "RetrievalByteRange": null, "SNSTopic": null, "Type": "inventory-retrieval", "InventoryRetrievalParameters": { "StartDate": "2013-12-04T21:25:42Z", "EndDate": "2013-12-05T21:25:42Z", "Limit" : "10000" }, }
A solicitação a seguir é um exemplo de uma solicitação subsequente para recuperar a próxima página de itens de inventário usando um marcador obtido de Trabalho de descrição (GET JobID).
{ "ArchiveId": null, "Description": null, "Format": "CSV", "RetrievalByteRange": null, "SNSTopic": null, "Type": "inventory-retrieval", "InventoryRetrievalParameters": { "StartDate": "2013-12-04T21:25:42Z", "EndDate": "2013-12-05T21:25:42Z", "Limit": "10000", "Marker": "vyS0t2jHQe5qbcDggIeD50chS1SXwYMrkVKo0KHiTUjEYxBGCqRLKaiySzdN7QXGVVV5XZpNVG67pCZ_uykQXFMLaxOSu2hO_-5C0AtWMDrfo7LgVOyfnveDRuOSecUo3Ueq7K0" }, }
Exemplo de resposta
HTTP/1.1 202 Accepted x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q Date: Wed, 10 Feb 2017 12:00:00 GMT Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID x-amz-job-output-path: test/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/
Seções relacionadas