Initiate Job (trabalhos POST) - Amazon S3 Glacier

Se você é novato no Amazon Simple Storage Service (Amazon S3), recomendamos que comece aprendendo mais sobre as classes de armazenamento S3 Glacier no Amazon S3, S3 Glacier Instant Retrieval, S3 Glacier Flexible Retrieval e S3 Glacier Deep Archive. Para obter mais informações, consulte Classes de armazenamento S3 Glacier e Classes de armazenamento para arquivamento de objetos no Guia do usuário do Amazon S3.

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 (trabalhos POST)

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

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:

  1. Inicie um trabalho de recuperação usando a operação Initiate Job (trabalhos POST).

    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ção PolicyEnforcedException, consulte Respostas de erro.

  2. 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:

  • Usar uma notificação do Amazon SNS— Você pode especificar um tópico do Amazon SNS no qual o S3 Glacier poderá publicar uma notificação depois que o trabalho for concluído. Você pode especificar um tópico do SNS por solicitação de trabalho. A notificação será enviada somente depois que o S3 Glacier concluir o trabalho. Além de especificar um tópico do SNS por solicitação de trabalho, você pode configurar notificações para um cofre, de maneira que as notificações de trabalho sejam enviadas para todas as recuperações. Para obter 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 notificação do Amazon SNS para determinar quando um trabalho está 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 tópico do SNS na solicitação do trabalho de iniciação, o S3 Glacier enviará ambas as notificações. Para obter 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 de cofre, o S3 Glacier retorna o último inventário gerado, que é um snapshot point-in-time, 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 método POST HTTP e delimita a solicitação ao sub-recurso jobs do cofre. Você especifica detalhes da solicitação de trabalho no documento JSON da solicitação. O tipo de trabalho é especificado com o campo Type. Se desejar, você pode especificar um campo SNSTopic para indicar um tópico do Amazon SNS no qual o S3 Glacier poderá publicar uma notificação depois que o trabalho for concluído.

nota

Para publicar uma notificação no Amazon SNS, você deve criar o tópico por conta própria, 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 valor de AccountId é o ID de Conta da AWS da conta proprietária do cofre. Você pode especificar um ID de Conta da AWS ou, de forma opcional, um '-' (hífen) único; nesse caso, o Amazon S3 Glacier usa o ID de Conta da AWS associado à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 no formato JSON 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 caminho de URI relativo do trabalho. Você pode usar esse caminho de URI para encontrar o status do trabalho. Para obter 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 Location.

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 Código de status HTTP 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 de aplicativos

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 definido como CSV no corpo da solicitação indica que o inventário é retornado no formato CSV.

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