Referência de API para o Storage Gateway

Além de usar o console, você pode usar a API do AWS Storage Gateway para configurar e gerenciar programaticamente seus gateways. Esta seção descreve as operações do AWS Storage Gateway, solicitação de assinatura para autenticação e tratamento de erros. Para obter informações sobre os endpoints disponíveis para o Storage Gateway, consulte Endpoints e cotas do AWS Storage Gateway na Referência geral da AWS.

Cabeçalhos de solicitação necessários do AWS Storage Gateway

Esta seção descreve os cabeçalhos requeridos que você precisa enviar em cada solicitação POST ao AWS Storage Gateway. Os cabeçalhos HTTP são incluídos para identificar as principais informações sobre a solicitação, como a operação que você deseja invocar, a data da solicitação e informações que indicam sua autorização como remetente da solicitação. Os cabeçalhos diferenciam minúsculas e maiúsculas e a ordem dos cabeçalhos não é importante.

O exemplo a seguir mostra os cabeçalhos que são usados na operação ActivateGateway.

POST / HTTP/1.1 
Host: storagegateway.us-east-2.amazonaws.com
Content-Type: application/x-amz-json-1.1
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120425/us-east-2/storagegateway/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=9cd5a3584d1d67d57e61f120f35102d6b3649066abdd4bf4bbcf05bd9f2f8fe2
x-amz-date: 20120912T120000Z
x-amz-target: StorageGateway_20120630.ActivateGateway

Veja a seguir os cabeçalhos que devem ser incluídos em suas solicitações POST ao AWS Storage Gateway. Os cabeçalhos mostrados a seguir que começam com "x-amz" são específicos à AWS. Todos os outros cabeçalhos listados são cabeçalhos comuns usados em transações HTTP.

Authorization: AWS4-HMAC_SHA456 
Credentials=YourAccessKey/yyymmdd/region/storagegateway/aws4_request, 
SignedHeaders=content-type;host;x-amz-date;x-amz-target, 
Signature=CalculatedSignature

Content-Type: application/x-amz-json-1.1

Host: storagegateway.region.amazonaws.com

x-amz-date: YYYYMMDD'T'HHMMSS'Z'

x-amz-target: StorageGateway_APIversion.operationName

Solicitações de assinatura

O Storage Gateway exige que toda solicitação enviada seja autenticada com uma assinatura. Para assinar uma solicitação, calcule uma assinatura digital usando a função de hash criptográfico. Hash criptográfico é uma função que retorna um valor de hash exclusivo com base na entrada. A entrada da função de hash inclui o texto da solicitação e a chave de acesso secreta. A função de hash retorna um valor de hash que você inclui na solicitação como sua assinatura. A assinatura é parte do cabeçalho Authorization de sua solicitação.

Depois de receber a solicitação, o Storage Gateway recalculará a assinatura usando a mesma função de hash e a entrada que você usou para assinar a solicitação. Quando a assinatura resultante corresponde à assinatura na solicitação, o Storage Gateway processa a solicitação. Do contrário, a solicitação é rejeitada.

O Storage Gateway é compatível com a autenticação usando o Signature versão 4 da AWS. O processo para calcular uma assinatura pode ser dividido em três tarefas:

Cálculo de assinatura de exemplo

O exemplo a seguir mostra os detalhes da criação de uma assinatura para ListGateways. Esse exemplo pode ser usado como referência para verificar o método de cálculo da assinatura.

O exemplo supõe o seguinte:

A sintaxe de solicitação geral (incluindo o corpo JSON) é:

POST / HTTP/1.1
Host: storagegateway.us-east-2.amazonaws.com
x-amz-Date: 20120910T000000Z
Authorization: SignatureToBeCalculated
Content-type: application/x-amz-json-1.1
x-amz-target: StorageGateway_20120630.ListGateways
{}

O formato canônico da solicitação calculada para é:

POST
/

content-type:application/x-amz-json-1.1
host:storagegateway.us-east-2.amazonaws.com
x-amz-date:20120910T000000Z
x-amz-target:StorageGateway_20120630.ListGateways

content-type;host;x-amz-date;x-amz-target
44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a

A última linha da solicitação canônica é o hash do corpo da solicitação. Além disso, observe a terceira linha vazia na solicitação canônica. Isso ocorre porque não há parâmetros de consulta para essa API (ou qualquer API do Storage Gateway).

A string-to-sign para é:

AWS4-HMAC-SHA256
20120910T000000Z
20120910/us-east-2/storagegateway/aws4_request
92c0effa6f9224ac752ca179a04cecbede3038b0959666a8160ab452c9e51b3e

A primeira linha da string-to-sign é o algoritmo, a segunda é o time stamp, a terceira é o escopo da credencial e a última é um hash da solicitação canônica da Tarefa 1.

Para , a chave derivada pode ser representada como:

derived key = HMAC(HMAC(HMAC(HMAC("AWS4" + YourSecretAccessKey,"20120910"),"us-east-2"),"storagegateway"),"aws4_request")

Se a chave de acesso secreta, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY, for usada, a assinatura calculada será:

6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81

A etapa final é construir o cabeçalho Authorization. Para a chave de acesso de demonstração AKIAIOSFODNN7EXAMPLE, o cabeçalho (com quebras de linha adicionadas por motivo de legibilidade) é:

Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120910/us-east-2/storagegateway/aws4_request, 
SignedHeaders=content-type;host;x-amz-date;x-amz-target, 
Signature=6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81

Respostas de erro

Esta seção oferece informações de referência sobre erros do AWS Storage Gateway. Esses erros são representados por uma exceção de erro e um código de erro de operação. Por exemplo, a exceção de erro InvalidSignatureException é retornada por qualquer resposta à API se houver um problema na assinatura da solicitação. No entanto, o código de erro de operação ActivationKeyInvalid é retornado somente pela API ActivateGateway.

Dependendo do tipo de erro, o Storage Gateway pode retornar somente uma exceção ou então um código de erro de exceção e de operação. Exemplos de respostas de erro são mostrados em Respostas de erro.

Exceções

A tabela a seguir lista exceções de API do AWS Storage Gateway. Quando uma operação do AWS Storage Gateway retorna uma resposta de erro, o corpo da resposta contém uma das exceções a seguir. As exceções InternalServerError e InvalidGatewayRequestException retornam um dos códigos de mensagem de Códigos de erro de operação que geram os códigos de erro de operação específicos.

Códigos de erro de operação

A tabela a seguir mostra o mapeamento entre os códigos de erro de operação do AWS Storage Gateway e as APIs que podem retornar os códigos. Todos os códigos de erro de operação são retornados com uma das duas exceções gerais – InternalServerError e InvalidGatewayRequestException – descritas em Exceções.

Respostas de erro

Quando existe um erro, as informações no cabeçalho da resposta contêm:

O corpo de uma resposta de erro contém informações sobre o erro que ocorreu. A resposta de erro de exemplo a seguir mostra a sintaxe de saída dos elementos comuns a todas as respostas de erro.

{
    "__type": "String",
    "message": "String",
    "error":
        { "errorCode": "String",
          "errorDetails": "String"
        }
}

A tabela a seguir explica os campos de resposta de erro JSON mostrados na sintaxe anterior.

Exemplos de resposta de erro

O corpo JSON a seguir será retornado se você usar a API DescribeStorediSCSIVolumes e especificar uma entrada de solicitação de ARN de gateway que não existe.

{
  "__type": "InvalidGatewayRequestException",
  "message": "The specified volume was not found.",
  "error": {
    "errorCode": "VolumeNotFound"
  }
}

O seguinte corpo JSON será retornado se o Storage Gateway calcular uma assinatura que não corresponda à assinatura enviada com uma solicitação.

{  
  "__type": "InvalidSignatureException",  
  "message": "The request signature we calculated does not match the signature you provided." 
}  

Ações de API do Storage Gateway

Para conferir uma lista completa de operações da API do Storage Gateway, consulte Ações na Referência de API do AWS Storage Gateway.