Trabalho de descrição (GET JobID) - Amazon S3 Glacier
DescriçãoSolicitaçõesRespostasExemplosSeções relacionadas

Esta página destina-se somente a clientes atuais do serviço S3 Glacier que usam cofres e a API REST original de 2012.

Se você estiver procurando soluções de armazenamento de arquivos, sugerimos usar as classes de armazenamento do 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 do Amazon S3 Glacier e Noções básicas sobre as classes de armazenamento S3 Glacier para armazenamento de dados de longo prazo no Guia do usuário do Amazon S3. Essas classes de armazenamento usam a API do Amazon S3, estão disponíveis em todas as regiões e podem ser gerenciadas no console do Amazon S3. Elas oferecem análise de custos de armazenamento, Lente de Armazenamento, recursos avançados de criptografia opcionais e muito mais.

Trabalho de descrição (GET JobID)

Descrição

Esta operação retorna informações sobre um trabalho iniciado anteriormente, incluindo a data de início do trabalho, o usuário que iniciou o trabalho, o código de status do trabalho/mensagem e o tópico do Amazon Simple Notification Service (Amazon SNS) para notificar depois que o Amazon S3 Glacier (S3 Glacier) concluir o trabalho. Para obter mais informações sobre como iniciar um trabalho, consulte Initiate Job (trabalhos POST).

nota

Essa operação permite verificar o status do trabalho. No entanto, é altamente recomendável configurar um tópico do Amazon SNS e especificá-lo na solicitação do trabalho de inicialização para que o S3 Glacier possa notificar o tópico após a conclusão do trabalho.

Um ID do trabalho não vai expirar por pelo menos 24 horas depois que o S3 Glacier concluir o trabalho.

Solicitações

Sintaxe

Para obter informações sobre um trabalho, você usa o método GET HTTP e delimita a solicitação ao trabalho específico. O caminho do URI relativo é o mesmo retornado pelo S3 Glacier quando você iniciou o trabalho. 

GET /AccountID/vaults/VaultName/jobs/JobID HTTP/1.1
Host: glacier.Region.amazonaws.com
Date: date
Authorization: signatureValue
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.

nota

Na solicitação, se você omitir o JobID, a resposta retornará uma lista de todos os trabalhos ativos no cofre especificado. Para obter mais informações sobre como listar trabalhos, consulte List Jobs (GET jobs).

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 somente os cabeçalhos de solicitação que são comuns a todas as operações. Para informações sobre os cabeçalhos de solicitação comuns, consulte Cabeçalhos de solicitação comuns.

Corpo da Solicitação

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

Respostas

Sintaxe

HTTP/1.1 201 Created
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: application/json
Content-Length: Length

{
    "Action": "string",
    "ArchiveId": "string",
    "ArchiveSHA256TreeHash": "string",
    "ArchiveSizeInBytes": number,
    "Completed": boolean,
    "CompletionDate": "string",
    "CreationDate": "string",
    "InventoryRetrievalParameters": {
        "EndDate": "string",
        "Format": "string",
        "Limit": "string",
        "Marker": "string",
        "StartDate": "string"
    },
    "InventorySizeInBytes": number,
    "JobDescription": "string",
    "JobId": "string",
    "JobOutputPath": "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"
            }
        }
    },
    "SHA256TreeHash": "string",
    "SNSTopic": "string",
    "StatusCode": "string",
    "StatusMessage": "string",
    "Tier": "string",
    "VaultARN": "string"
}

Cabeçalhos de resposta

Essa operação usa somente os cabeçalhos de resposta que são comuns a maioria das respostas. Para informações sobre os cabeçalhos de resposta comuns, consulte Cabeçalhos de resposta comuns.

Corpo da resposta

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

Ação

O tipo de trabalho. É ArchiveRetrieval, InventoryRetrieval ou Select.

Tipo: string

ArchiveId

O ID de arquivo solicitado para um trabalho de seleção ou de recuperação de arquivo. Do contrário, esse campo será null.

Tipo: string

ArchiveSHA256TreeHash

O hash de árvore SHA256 de todo o arquivo de um trabalho de recuperação do arquivo. Para trabalhos de recuperação do inventário, esse campo é null.

Tipo: string

ArchiveSizeInBytes

Para um trabalho ArchiveRetrieval, trata-se do tamanho em bytes do arquivo solicitado para download. Para o trabalho InventoryRetrieval, o valor é null.

Tipo: número

Completed

O status do trabalho. Quando um trabalho de recuperação de arquivo ou inventário for concluído, você obterá a saída do trabalho usando o Get Job Output (GET output).

Tipo: booliano

CompletionDate

A hora UTC (Horário Coordenado Universal) em que a solicitação de trabalho foi concluída. Enquanto o trabalho estiver em andamento, o valor será nulo.

Tipo: string

CreationDate

A hora UTC em que o trabalho foi criado.

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

InventoryRetrievalParameters

Os parâmetros de entrada usados em uma recuperação de inventário de intervalo.

Tipo: InventoryRetrievalJobInput objeto

InventorySizeInBytes

Para um trabalho InventoryRetrieval, trata-se do tamanho em bytes do inventário solicitado para download. No trabalho ArchiveRetrieval ou Select, o valor é null.

Tipo: número

JobDescription

A descrição do trabalho fornecida por você quando iniciou o trabalho.

Tipo: string

JobId

O ID que identifica o trabalho no S3 Glacier.

Tipo: string

JobOutputPath

Contém o local de saída do trabalho.

Tipo: string

OutputLocation

Um objeto com informações sobre o local onde os resultados e os erros do trabalho de seleção são armazenados.

Tipo: OutputLocation objeto

RetrievalByteRange

O intervalo de bytes recuperado para trabalhos de recuperação de arquivo no formato "StartByteValue-EndByteValue". Se nenhum intervalo for especificado na recuperação do arquivo, então, todo o arquivo será recuperado; além disso, StartByteValue será igual a 0 e EndByteValue será igual ao tamanho do arquivo menos 1. Em trabalhos de seleção ou de recuperação de inventário, este campo é null.

Tipo: string

SelectParameters

Um objeto com informações sobre os parâmetros usados em uma seleção.

Tipo: SelectParameters objeto

SHA256TreeHash

O valor do hash de árvore SHA256 para o intervalo solicitado de um arquivo. Se a solicitação Initiate Job (trabalhos POST) para um arquivo tiver especificado um intervalo alinhado ao hash de árvore, esse campo retornará um valor. Para obter mais informações sobre o alinhamento ao hash de árvore para recuperações do intervalo de arquivos, consulte Receber somas de verificação durante o download de dados.

Para o caso específico quando todo o arquivo for recuperado, esse valor será igual ao valor ArchiveSHA256TreeHash.

Esse campo é null nas seguintes situações:

  • Os trabalhos de recuperação de arquivo que especificam um intervalo não alinhado ao hash de árvore.

  • Trabalhos de arquivamento que especificam um intervalo igual a todo o arquivamento e cujo status do trabalho seja InProgress.

  • Trabalhos de inventário.

  • Trabalhos de seleção.

Tipo: string

SNSTopic

Um tópico do Amazon SNS que recebe notificação.

Tipo: string

StatusCode

O código que indica o status do trabalho.

Valores válidos: InProgress | Succeeded | Failed

Tipo: string

StatusMessage

Uma mensagem amigável que descreve o status do trabalho.

Tipo: string

Nível

O nível de acesso a dados a ser usado na seleção ou na recuperação de arquivo.

Valores válidos: Bulk | Expedited | Standard

Tipo: string

VaultARN

O nome de recurso da Amazon (ARN) do cofre do qual o trabalho é um sub-recurso.

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.

Solicitação de exemplo: obter descrição do trabalho 

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

O corpo da resposta inclui JSON que descreve o trabalho especificado. Observe que, nos trabalhos de recuperação de inventário e de arquivo, os campos JSON são iguais. No entanto, quando um campo não se aplica ao tipo de trabalho, o valor é null. Esta é uma resposta de exemplo para um trabalho de recuperação de arquivo. Observe o seguinte:

  • O valor do campo Action é ArchiveRetrieval.

  • O campo ArchiveSizeInBytes mostra o tamanho do arquivo solicitado no trabalho de recuperação do arquivo.

  • O campo ArchiveSHA256TreeHash mostra o hash de árvore SHA256 de todo o arquivo.

  • O campo RetrievalByteRange mostra o intervalo solicitado no pedido Initiate Job. Neste exemplo, todo o arquivo é solicitado.

  • O campo SHA256TreeHash mostra o hash de árvore SHA256 do intervalo solicitado no pedido Initiate Job. Neste exemplo, ele é igual ao campo ArchiveSHA256TreeHash, o que significa que todo o arquivo foi solicitado.

  • O valor do campo InventorySizeInBytes é null porque não se aplica a um trabalho de recuperação de arquivo.

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: 419
{
  "Action": "ArchiveRetrieval",
  "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId",
  "ArchiveSizeInBytes": 16777216,
  "ArchiveSHA256TreeHash": "beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60",
  "Completed": false,
  "CompletionDate": null,
  "CreationDate": "2012-05-15T17:21:39.339Z",
  "InventorySizeInBytes": null,
  "JobDescription": "My ArchiveRetrieval Job",
  "JobId": "HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID",
  "RetrievalByteRange": "0-16777215",
  "SHA256TreeHash": "beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60",
  "SNSTopic": "arn:aws:sns:us-west-2:012345678901:mytopic",
  "StatusCode": "InProgress",
  "StatusMessage": "Operation in progress.",
  "Tier": "Bulk",
  "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault"
}

Esta é uma resposta de exemplo para um trabalho de recuperação de inventário. Observe o seguinte:

  • O valor do campo Action é InventoryRetrieval.

  • Os valores de campo ArchiveSizeInBytes, ArchiveSHA256TreeHash e RetrievalByteRange são nulos porque não se aplicam a um trabalho de recuperação de inventário.

  • O valor de campo InventorySizeInBytes é null porque o trabalho ainda está em andamento e não preparou totalmente o inventário para download. Se o trabalho tivesse sido concluído antes da solicitação do trabalho de descrição, esse campo informaria o tamanho do resultado.

{
   "Action": "InventoryRetrieval",
   "ArchiveId": null,
   "ArchiveSizeInBytes": null,
   "ArchiveSHA256TreeHash": null,
   "Completed": false,
   "CompletionDate": null,
   "CreationDate": "2012-05-15T23:18:13.224Z",
   "InventorySizeInBytes": null,
   "JobDescription": "Inventory Description",
   "JobId": "HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID",
   "RetrievalByteRange": null,
   "SHA256TreeHash": null,
   "SNSTopic": "arn:aws:sns:us-west-2:012345678901:mytopic",
   "StatusCode": "InProgress",
   "StatusMessage": "Operation in progress.",
   "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault"
}

Esta é uma resposta de exemplo para um trabalho de recuperação de inventário completo que contém um marcador usado para continuar a paginação da recuperação do inventário de cofre. 

{ 
    "Action": "InventoryRetrieval", 
    "ArchiveId": null, 
    "ArchiveSHA256TreeHash": null, 
    "ArchiveSizeInBytes": null, 
    "Completed": true, 
    "CompletionDate": "2013-12-05T21:51:13.591Z", 
    "CreationDate": "2013-12-05T21:51:12.281Z", 
    "InventorySizeInBytes": 777062, 
    "JobDescription": null, 
    "JobId": "sCC2RZNBF2nildYD_roe0J9bHRdPQUbDRkmTdg-mXi2u3lc49uW6TcEhDF2D9pB2phx-BN30JaBru7PMyOlfXHdStzu8", 
    "NextInventoryRetrievalMarker": null, 
    "RetrievalByteRange": null, 
    "SHA256TreeHash": null, 
    "SNSTopic": null, 
    "StatusCode": "Succeeded", 
    "StatusMessage": "Succeeded", 
    "Tier": "Bulk",
    "VaultARN": "arn:aws:glacier-devo:us-west-2:836579025725:vaults/inventory-icecube-2", 
    "InventoryRetrievalParameters": {
        "StartDate": "2013-11-12T13:43:12Z",
        "EndDate": "2013-11-20T08:12:45Z", 
        "Limit": "120000",
        "Format": "JSON",
        "Marker": "vyS0t2jHQe5qbcDggIeD50chS1SXwYMrkVKo0KHiTUjEYxBGCqRLKaiySzdN7QXGVVV5XZpNVG67pCZ_uykQXFMLaxOSu2hO_-5C0AtWMDrfo7LgVOyfnveDRuOSecUo3Ueq7K0"
    },   
}