Get Job Output (GET output)

Descrição

Essa operação faz download da saída do trabalho iniciado por você usando a operação Initiate Job (POSTtrabalhos). Dependendo do tipo de trabalho especificado por você quando iniciou o trabalho, a saída será o conteúdo de um arquivo ou um inventário de cofre.

Você pode fazer download de toda a saída do ou de uma parte da saída especificando um intervalo de bytes. Para trabalhos de recuperação de arquivo e inventário, você deve verificar o tamanho obtido por download em relação ao tamanho retornado nos cabeçalhos da resposta Obter saída de trabalho.

Para trabalhos de recuperação de arquivo, você também deve verificar se o tamanho é o esperado. Se você fizer download de uma parte da saída, o tamanho esperado se baseará no intervalo de bytes especificado. Por exemplo, se especificar um intervalo de bytes=0-1048575, você deverá verificar se o tamanho do download é de 1.048.576 bytes. Se você fizer download de um arquivo inteiro, o tamanho esperado será o tamanho do arquivo quando fez upload dele no S3 Glacier (S3 Glacier). O tamanho esperado também é retornado nos cabeçalhos da resposta Obter saída de trabalho.

Em caso de um trabalho de recuperação de arquivo, dependendo do intervalo de bytes especificado por você, o S3 Glacier retorna a soma de verificação da parte dos dados. Para garantir que a parte obtida por download seja de dados corretos, compute a soma de verificação no cliente, verifique se os valores são correspondentes e se o tamanho é o esperado.

Um ID do trabalho não expira por pelo menos 24 horas depois que o S3 Glacier concluir o trabalho. Ou seja, você pode fazer download do resultado do trabalho dentro do período de 24 horas depois que o S3 Glacier concluir o trabalho.

Solicitações

Sintaxe

Para recuperar uma saída de trabalho, você envia a solicitação GET HTTP para o URI do output do trabalho específico.

GET /AccountId/vaults/VaultName/jobs/JobID/output HTTP/1.1
Host: glacier.Region.amazonaws.com
Date: Date
Authorization: SignatureValue
Range: ByteRangeToRetrieve
x-amz-glacier-version: 2012-06-01

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.

Parâmetros de solicitação

Essa operação não usa parâmetros de solicitação.

Cabeçalhos de solicitação

Essa operação usa os seguintes cabeçalhos de solicitação, além dos cabeçalhos de solicitação que são comuns a todas as operações. Para mais informações sobre os cabeçalhos de solicitação comuns, consulte Cabeçalhos de solicitação comuns.

Name (Nome)	Descrição	Obrigatório
Range	O intervalo de bytes a ser recuperado da saída. Por exemplo, se você quiser fazer download dos primeiros 1.048.576 bytes, especifique o intervalo como bytes=0-1048575. Para obter mais informações, acesse Definição do campo de cabeçalho do intervalo. O intervalo se refere a qualquer intervalo especificado na solicitação Initiate Job. Por padrão, essa operação faz download de toda a saída. Se a saída do trabalho for grande, você poderá usar o cabeçalho da solicitação Range para recuperar uma parte da saída. Isso permite fazer download de toda a saída em blocos de bytes menores. Por exemplo, suponhamos que você tenha 1 GB de saída de trabalho cujo download deseja fazer e opte por fazer download de blocos de 128 MB de dados por vez, em um total de oito solicitações Get Job Output. Você usará o seguinte processo para fazer download da saída do trabalho: Faça download de uma saída de bloco de 128 MB de dados especificando o intervalo de bytes apropriado com o cabeçalho Range. Verifique se todos os 128 MB de dados foram recebidos. Com os dados, a resposta incluirá uma soma de verificação da carga útil. Você computa a soma de verificação da carga útil no cliente e a compara com a soma de verificação recebida na resposta para garantir que tenha recebido todos os dados esperados. Repita as etapas 1 e 2 para todos os oito blocos de 128 MB de dados de saída, sempre especificando o intervalo de bytes apropriado. Depois do download de todas as partes da saída do trabalho, você terá uma lista de oito valores de soma de verificação. Compute o hash de árvore desses valores para encontrar a soma de verificação de toda a saída. Usando a operação Trabalho de descrição (GET JobID), obtenha informações do trabalho que forneceu a saída. A resposta inclui a soma de verificação de todo o arquivo armazenado no S3 Glacier. Você compara esse valor com a soma de verificação computada para garantir que tenha feito download de todo o conteúdo do arquivo sem erros. Tipo: string Padrão: nenhum Restrições: nenhuma	Não

Corpo da solicitação

Essa operação não tem um corpo de solicitação.

Respostas

Sintaxe

Para uma solicitação de recuperação que retorne todos os dados do trabalho, a resposta da saída do trabalho retorna um código de resposta 200 OK. Quando o conteúdo parcial é solicitado, por exemplo, se você tiver especificado o cabeçalho Range na solicitação, o código de resposta 206 Partial Content será retornado.

HTTP/1.1 200 OK
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: ContentType
Content-Length: Length
x-amz-sha256-tree-hash: ChecksumComputedByAmazonGlacier

[Body containing job output.]

Cabeçalhos de resposta

Cabeçalho	Descrição
Content-Range	O intervalo de bytes retornado pelo S3 Glacier. Se somente o download da saída parcial tiver sido feito, a resposta fornecerá o intervalo de bytes retornado pelo S3 Glacier. Por exemplo, bytes 0-1048575/8388608 retorna o primeiro 1 MB de 8 MB. Para obter mais informações sobre o cabeçalho Content-Range, acesse Definição do campo de cabeçalho Content-Range. Tipo: string
Content-Type	O Content-Type depende da saída do trabalho ser um arquivo ou um inventário de cofre. Para dados de arquivo, o Content-Type é application/octet-stream. Para inventário de cofre, se você tiver solicitado o formato CSV quando iniciou o trabalho, o Content-Type será text/csv. Do contrário, por padrão, o inventário de cofre é retornado como JSON, e o Content-Type será application/json. Tipo: string
x-amz-sha256-tree-hash​	A soma de verificação dos dados na resposta. Esse cabeçalho é retornado somente quando se recupera a saída de um trabalho de recuperação de arquivo. Além disso, esse cabeçalho é exibido quando o intervalo de dados recuperados solicitado no pedido Initiate Job está alinhado ao hash de árvore e o intervalo para download no Get Job Output também está 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. Por exemplo, se na solicitação Initiate Job, tiver especificado um intervalo alinhado ao hash de árvore (o que inclui todo o arquivo), você receberá a soma de verificação dos dados cujo download fez nas seguintes condições: Você recebe todo o intervalo dos dados recuperados. Você solicita um intervalo de bytes dos dados recuperados que tem um tamanho de um megabyte (1.024 KB) multiplicado por uma potência de 2 e que começa e termina em um múltiplo do tamanho do intervalo solicitado. Por exemplo, se tiver 3,1 MB de dados recuperados e especificar um intervalo a ser retornado que comece em 1 MB e termine em 2 MB, o x-amz-sha256-tree-hash será retornado como um cabeçalho de resposta. Você solicita um intervalo a ser retornado dos dados recuperados que vai para o final dos dados, e o início do intervalo é um múltiplo do tamanho do intervalo a ser recuperado arredondado para a próxima potência de dois, mas não menor que um megabyte (1.024 KB). Por exemplo, se tiver 3,1 MB de dados recuperados e especificar um intervalo a ser retornado que comece em 2 MB e termine em 3,1 MB (o final dos dados), o x-amz-sha256-tree-hash será retornado como um cabeçalho de resposta. Tipo: string

Corpo da resposta

O S3 Glacier retorna a saída do trabalho no corpo da resposta. Dependendo do tipo de trabalho, a saída pode ser o conteúdo do arquivo ou o inventário de cofre. No caso de um inventário de cofre, por padrão, a lista de inventários é retornada como o corpo JSON a seguir.

{
 "VaultARN": String,
 "InventoryDate": String,
 "ArchiveList": [
      {"ArchiveId": String,
       "ArchiveDescription": String,
       "CreationDate": String,
       "Size": Number,
       "SHA256TreeHash": String
      },
      ...
    ]
}

Se você tiver solicitado o formato de saída Comma-Separated Values (CSV – Valores separados por vírgula) quando iniciou o trabalho de inventário, o inventário de cofre será retornado em formato CSV no corpo. O formato CSV tem cinco colunas "ArchiveId", "ArchiveDescription", "CreationDate", "Size" e "SHA256TreeHash" com as mesmas definições dos campos JSON correspondentes.

nota

No formato CSV retornado, os campos podem ser retornados com o campo inteiro entre aspas duplas. Os campos que contenham uma vírgula ou aspas duplas sempre são retornados entre aspas duplas. Por exemplo, my archive description,1 é retornado como "my archive description,1". Caracteres de aspas duplas que estejam entre campos entre aspas duplas têm escape com um caractere de barra invertida antes deles. Por exemplo, my archive description,1"2 é retornado como "my archive description,1\"2" e my archive description,1\"2 é retornado como "my archive description,1\\"2". O caractere de barra invertida não é de escape.

O corpo da resposta JSON contém os seguintes campos JSON:

ArchiveDescription

A descrição de um arquivo.

Tipo: string

ArchiveId

O ID de um arquivo.

Tipo: string

ArchiveList

Uma matriz de metadados de arquivo. Cada objeto na matriz representa metadados de um arquivo contido no cofre.

Tipo: matriz

CreationDate

A data e hora UTC em que o arquivo foi criado.

Tipo: uma representação de string no formato de data ISO 8601, por exemplo 2013-03-20T17:03:43.221Z.

InventoryDate

A data e hora UTC do inventário mais recente do cofre que foi concluído após alterações terem sido feitas no cofre. Embora o S3 Glacier prepare um inventário de cofre uma vez por dia, a data do inventário será atualizada somente se tiver ocorrido adições ou exclusões de arquivo no cofre desde o último inventário.

Tipo: uma representação de string no formato de data ISO 8601, por exemplo 2013-03-20T17:03:43.221Z.

SHA256TreeHash

O hash de árvore do arquivo.

Tipo: string

Tamanho

O tamanho em bytes do arquivo.

Tipo: número

VaultARN

O Amazon Resource Name (ARN – Nome de recurso da Amazon) do qual a recuperação do arquivo foi solicitada.

Tipo: string

Erros

Para obter informações sobre exceções e mensagens de erro do Amazon S3 Glacier, consulte Respostas de erro.

Exemplos

O exemplo a seguir mostra a solicitação de um trabalho que recupera um arquivo.

Exemplo 1: fazer download da saída

Este exemplo recupera dados preparados pelo S3 Glacier em resposta à solicitação do trabalho de recuperação de arquivo de iniciação.

Exemplo de solicitação

GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/output 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

Exemplo de resposta

Esta é uma resposta de exemplo de um trabalho de recuperação de arquivo. O cabeçalho Content-Type é application/octet-stream e esse cabeçalho x-amz-sha256-tree-hash está incluído na resposta, o que significa que todos os dados do trabalho são retornados.

HTTP/1.1 200 OK
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
x-amz-sha256-tree-hash: beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60
Date: Wed, 10 Feb 2017 12:00:00 GMT
Content-Type: application/octet-stream
Content-Length: 1048576

[Archive data.]

Esta é uma resposta de exemplo de um trabalho de recuperação de inventário. O cabeçalho Content-Type é application/json. A resposta também não inclui o cabeçalho x-amz-sha256-tree-hash.

HTTP/1.1 200 OK
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Wed, 10 Feb 2017 12:00:00 GMT
Content-Type: application/json
Content-Length: 906

{
 "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault",
 "InventoryDate": "2011-12-12T14:19:01Z",
 "ArchiveList": [
   {
     "ArchiveId": "DMTmICA2n5Tdqq5BV2z7og-A20xnpAPKt3UXwWxdWsn_D6auTUrW6kwy5Qyj9xd1MCE1mBYvMQ63LWaT8yTMzMaCxB_9VBWrW4Jw4zsvg5kehAPDVKcppUD1X7b24JukOr4mMAq-oA",
     "ArchiveDescription": "my archive1",
     "CreationDate": "2012-05-15T17:19:46.700Z",
     "Size": 2140123,
     "SHA256TreeHash": "6b9d4cf8697bd3af6aa1b590a0b27b337da5b18988dbcc619a3e608a554a1e62"
   },
   {
     "ArchiveId": "2lHzwhKhgF2JHyvCS-ZRuF08IQLuyB4265Hs3AXj9MoAIhz7tbXAvcFeHusgU_hViO1WeCBe0N5lsYYHRyZ7rrmRkNRuYrXUs_sjl2K8ume_7mKO_0i7C-uHE1oHqaW9d37pabXrSA",
     "ArchiveDescription": "my archive2",
     "CreationDate": "2012-05-15T17:21:39.339Z",
     "Size": 2140123,
     "SHA256TreeHash": "7f2fe580edb35154041fa3d4b41dd6d3adaef0c85d2ff6309f1d4b520eeecda3"
   }
  ]
}

Exemplo 2: fazer download somente da saída parcial

Este exemplo recupera somente uma parte do arquivo preparado pelo S3 Glacier em resposta à solicitação do trabalho de recuperação de arquivo de iniciação. A solicitação usa o cabeçalho Range opcional para recuperar somente os primeiros 1.024 bytes.

Exemplo de solicitação

GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/output HTTP/1.1
Host: glacier.us-west-2.amazonaws.com
x-amz-Date: 20170210T120000Z
Range: bytes=0-1023	
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

Exemplo de resposta

A resposta bem-sucedida a seguir mostra a resposta 206 Partial Content. Nesse caso, a resposta também inclui um cabeçalho Content-Range que especifica o intervalo de bytes retornado pelo S3 Glacier.

HTTP/1.1 206 Partial Content
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Wed, 10 Feb 2017 12:00:00 GMT
Content-Range: bytes 0-1023/8388608
Content-Type: application/octet-stream
Content-Length: 1024

[Archive data.]

Seções relacionadas

• Trabalho de descrição (GET JobID)

• Initiate Job (POSTtrabalhos)

• Gerenciamento de identidade e acesso para o Amazon S3 Glacier