Initiate Job (POSTtrabalhos) - Amazon S3 Glacier
Inicialização de um trabalho de recuperação de arquivo ou inventário de cofre SolicitaçõesRespostasExemplosSeções relacionadas

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 de armazenamento S3 Glacier no Guia do usuário do Amazon S3. Essas classes de armazenamento usam o Amazon S3API, estão disponíveis em todas as regiões e podem ser gerenciadas no console do Amazon S3. Eles oferecem recursos como análise de custos de armazenamento, lente de armazenamento, recursos avançados de criptografia opcional e muito mais.

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

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 (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çã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:

  • 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 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 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