A documentação do gateway de arquivos do Amazon S3 foi movida para O que é o Amazon S3 File Gateway?
A documentação FSx do Amazon File Gateway foi movida para O que é o Amazon FSx File Gateway?
A documentação do gateway de fitas foi movida para O que é o gateway de fitas?
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á.
APIReferência para Storage Gateway
Além de usar o console, você pode usar o AWS Storage Gateway API para configurar e gerenciar programaticamente seus gateways. Esta seção descreve as AWS Storage Gateway operações, a assinatura de solicitações para autenticação e o 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.
nota
Você também pode usar o AWS SDKs ao desenvolver aplicativos com AWS Storage Gateway o. O AWS SDKs para Java,. NETe PHP envolva o subjacente AWS Storage Gateway API, simplificando suas tarefas de programação. Para obter informações sobre como baixar as SDK bibliotecas, consulte Exemplos de bibliotecas de código
Tópicos
Cabeçalhos de solicitação requeridos no Storage Gateway
Esta seção descreve os cabeçalhos necessários que você deve enviar com cada POST solicitação ao Storage Gateway. Você inclui HTTP cabeçalhos para identificar as principais informações sobre a solicitação, incluindo 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 ActivateGatewayoperação.
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
A seguir estão os cabeçalhos que devem ser incluídos em suas POST solicitações ao Storage Gateway. Os cabeçalhos mostrados abaixo que começam com “x-amz” são AWS cabeçalhos específicos. Todos os outros cabeçalhos listados são cabeçalhos comuns usados em HTTP transações.
| Cabeçalho | Descrição |
|---|---|
Authorization |
O cabeçalho de autorização contém várias informações sobre a solicitação que permitem que o Storage Gateway determine se a solicitação é uma ação válida para o solicitante. O formato desse cabeçalho é o seguinte (as quebras de linha foram adicionadas por motivo de legibilidade):
Na sintaxe anterior, você especifica o ano YourAccessKey, mês e dia (aaaammdd), a região e o. CalculatedSignature O formato do cabeçalho de autorização é determinado pelos requisitos do processo de assinatura AWS V4. Os detalhes da assinatura são discutidos no tópico Solicitações de assinatura. |
Content-Type |
Use
|
Host |
Use o cabeçalho do host para especificar o endpoint do Storage Gateway em que você envia sua solicitação. Por exemplo,
|
x-amz-date |
Você deve fornecer o carimbo de data/hora no HTTP
|
x-amz-target |
Esse cabeçalho especifica a versão API e a operação que você está solicitando. Os valores do cabeçalho de destino são formados pela concatenação da API versão com o API nome e estão no formato a seguir.
O operationNamevalor (por exemplo, "ActivateGateway“) pode ser encontrado na API lista,APIReferência para Storage Gateway. |
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:
-
Tarefa 1: Criar uma solicitação canônica
Reorganize sua HTTP solicitação em um formato canônico. É necessário usar uma forma canônica, pois o Storage Gateway usa a mesma forma canônica quando recalcula uma assinatura para compará-la com a que você enviou.
-
Tarefa 2: Criar uma string para assinar
Crie uma string que será usada como um dos valores de entrada para sua função hash criptográfica. A string, chamada string-to-sign, é uma concatenação do nome do algoritmo hash, da data da solicitação, de uma string do escopo da credencial e da solicitação canonizada da tarefa anterior. A string do escopo credencial em si é uma concatenação da data, da região e de informações do serviço.
-
Crie uma assinatura para sua solicitação usando uma função hash criptográfica que aceita duas strings de entrada: sua string para assinar e uma chave derivada. A chave derivada é calculada começando com sua chave de acesso secreta e usando a string do escopo da credencial para criar uma série de códigos de autenticação de mensagens baseados em hash ()HMACs.
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. Outros cálculos de referência estão incluídos no Signature Version 4 Test Suite do Amazon Web Services Glossary.
O exemplo supõe o seguinte:
-
A data e hora da solicitação é “Seg, 10 de setembro de 2012 00:00:00”. GMT
-
O endpoint é a região Leste dos EUA (Ohio).
A sintaxe geral da solicitação (incluindo o JSON corpo) é:
POST / HTTP/1.1 Host: storagegateway.us-east-2.amazonaws.com x-amz-Date: 20120910T000000Z Authorization:SignatureToBeCalculatedContent-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 isso API (ou para qualquer Storage GatewayAPIs).
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çãoAKIAIOSFODNN7EXAMPLE, o cabeçalho (com quebras de linha adicionadas para facilitar a leitura) é:
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 fornece informações de referência sobre AWS Storage Gateway erros. 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 API resposta se houver um problema com a assinatura da solicitação. No entanto, o código de erro de operação ActivationKeyInvalid é retornado somente para ActivateGatewayAPIo.
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 as AWS Storage Gateway API exceções. Quando uma AWS Storage Gateway operação retorna uma resposta de erro, o corpo da resposta contém uma dessas exceções. 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.
| Exceção | Message | HTTPCódigo de status |
|---|---|---|
IncompleteSignatureException |
A assinatura especificada está incompleta. | 400 solicitação inválida |
InternalFailure |
O processamento da solicitação falhou por algum erro ou alguma exceção ou falha desconhecida. | 500 Internal Server Error |
InternalServerError |
Uma das mensagens de código de erro de operação em Códigos de erro de operação. | 500 Internal Server Error |
InvalidAction |
A ação ou operação solicitada é inválida. | 400 solicitação inválida |
InvalidClientTokenId |
O certificado X.509 ou ID da chave de AWS acesso fornecido não existe em nossos registros. | 403 proibido |
InvalidGatewayRequestException |
Uma das mensagens de código de erro de operação em Códigos de erro de operação. | 400 solicitação inválida |
InvalidSignatureException |
A assinatura da solicitação que calculamos não corresponde à assinatura que você forneceu. Verifique sua chave de AWS acesso e método de assinatura. | 400 solicitação inválida |
MissingAction |
Está faltando um parâmetro de ação ou operação na solicitação. | 400 solicitação inválida |
MissingAuthenticationToken |
A solicitação deve conter uma ID de chave de AWS acesso válida (registrada) ou um certificado X.509. | 403 proibido |
RequestExpired |
A solicitação ultrapassa data de expiração ou a data de solicitação (ambas com acréscimo de 15 minutos) ou a data de solicitação ultrapassa 15 minutes no futuro. | 400 solicitação inválida |
SerializationException |
Ocorreu um erro durante a serialização. Verifique se sua JSON carga está bem formada. | 400 solicitação inválida |
ServiceUnavailable |
Falha na solicitação devido a um erro temporário do servidor. | 503 Service Unavailable (503 Serviço não disponível) |
SubscriptionRequiredException |
O ID da chave de AWS acesso precisa de uma assinatura para o serviço. | 400 solicitação inválida |
ThrottlingException |
Taxa excedida. | 400 solicitação inválida |
TooManyRequests |
Muitas solicitações. | 429 Solicitações demais |
UnknownOperationException |
Foi especificada uma operação desconhecida. As operações válidas estão relacionadas em Operações no Storage Gateway. | 400 solicitação inválida |
UnrecognizedClientException |
O token de segurança incluído na solicitação é inválido. | 400 solicitação inválida |
ValidationException |
O valor de um parâmetro de entrada é inválido ou está fora do intervalo. | 400 solicitação inválida |
Códigos de erro de operação
A tabela a seguir mostra o mapeamento entre os códigos de erro de AWS Storage Gateway operação e APIs que pode 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.
| Código de erro de operação | Message | Operações que retornam esse código de erro |
|---|---|---|
ActivationKeyExpired |
A chave de ativação especificada expirou. | ActivateGateway |
ActivationKeyInvalid |
A chave de ativação especificada é inválida. | ActivateGateway |
ActivationKeyNotFound |
Não foi possível encontrar a chave de ativação especificada. | ActivateGateway |
BandwidthThrottleScheduleNotFound |
Não foi possível encontrar a limitação de largura de banda. | DeleteBandwidthRateLimit |
CannotExportSnapshot |
Não é possível exportar o snapshot especificado. | |
InitiatorNotFound |
Não foi possível encontrar o iniciador especificado. | DeleteChapCredentials |
DiskAlreadyAllocated |
O disco especificado já está alocado. | |
DiskDoesNotExist |
O disco especificado não existe. | |
DiskSizeNotGigAligned |
O disco especificado não está alinhado em gigabyte. | |
DiskSizeGreaterThanVolumeMaxSize |
O tamanho do disco é superior ao tamanho máximo de volume. | CreateStorediSCSIVolume |
DiskSizeLessThanVolumeSize |
O tamanho do disco especificado é superior ao tamanho do volume. | CreateStorediSCSIVolume |
DuplicateCertificateInfo |
As informações de certificado especificadas estão duplicadas. | ActivateGateway |
GatewayInternalError |
Ocorreu um erro interno no gateway. | |
GatewayNotConnected |
O gateway especificado não está conectado. | |
GatewayNotFound |
O gateway especificado não foi encontrado. | |
GatewayProxyNetworkConnectionBusy |
A conexão de rede proxy do gateway especificado está ocupada. | |
InternalError |
Ocorreu um erro interno. | |
InvalidParameters |
A solicitação especificada contém parâmetros incorretos. | |
LocalStorageLimitExceeded |
O limite de armazenamento local foi excedido. | |
LunInvalid |
O especificado LUN está incorreto. | CreateStorediSCSIVolume |
MaximumVolumeCountExceeded |
A contagem máxima de volume foi excedida. | |
NetworkConfigurationChanged |
A configuração de rede do gateway mudou. | |
NotSupported |
A operação especificada não é comportada. | |
OutdatedGateway |
O gateway especificado está desatualizado. | ActivateGateway |
SnapshotInProgressException |
O snapshot especificado está em andamento. | DeleteVolume |
SnapshotIdInvalid |
O snapshot especificado é inválido. | |
StagingAreaFull |
A área de preparação está cheia. | |
TargetAlreadyExists |
O destino especificado já existe. | |
TargetInvalid |
O destino especificado é inválido. | |
TargetNotFound |
O destino especificado não foi encontrado. | |
UnsupportedOperationForGatewayType |
A operação especificada não é válida para o tipo de gateway. | |
VolumeAlreadyExists |
O volume especificado já existe. | |
VolumeIdInvalid |
O volume especificado é inválido. | DeleteVolume |
VolumeInUse |
O volume especificado já está em uso. | DeleteVolume |
VolumeNotFound |
O volume especificado não foi encontrado. | |
VolumeNotReady |
O volume especificado não está pronto. |
Respostas de erro
Quando existe um erro, as informações no cabeçalho da resposta contêm:
-
Tipo de conteúdo: aplicativo/ -1,1 x-amz-json
-
Um código apropriado
4xxou5xxHTTP de status
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 JSON de resposta a erros mostrados na sintaxe anterior.
- __type
-
Uma das exceções de Exceções.
Type: string
- error
-
Contém detalhes API de erros específicos. Em erros gerais (ou seja, não específicos de nenhumAPI), essas informações de erro não são mostradas.
Tipo: Coleção
- errorCode
-
Um dos códigos de erro de operação .
Type: string
- errorDetails
-
Esse campo não é usado na versão atual doAPI.
Type: string
- mensagem
-
Uma das mensagens de código de erro de operação em .
Type: string
Exemplos de resposta de erro
O JSON corpo a seguir será retornado se você usar DescribeStoredi SCSIVolumes API e especificar uma entrada de ARN solicitação de gateway que não existe.
{ "__type": "InvalidGatewayRequestException", "message": "The specified volume was not found.", "error": { "errorCode": "VolumeNotFound" } }
O JSON corpo a seguir 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." }
Operações no Storage Gateway
Para obter uma lista das operações do Storage Gateway, consulte Ações na AWS Storage Gateway APIreferência.
