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á.
Referência de API para 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 mais informações sobre as regiões e os endpoints disponíveis para Storage Gateway, consulteAWS Storage GatewayEndpoints e cotas donoAWSReferência geral.
nota
Você também pode usar oAWSSDKs ao desenvolver aplicativos com Storage Gateway. OAWSOs SDKs para Java, .NET e PHP encapsulam a API do Storage Gateway subjacente, simplificando as tarefas de programação. Para obter informações sobre como fazer download de bibliotecas de SDKs, consulte Bibliotecas de códigos de exemplo
Tópicos
AWS Storage GatewayCabeçalhos de solicitação requeridos
Esta seção descreve os cabeçalhos requeridos que você deve enviar em cada solicitação POST paraAWS 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
A seguir estão os cabeçalhos que devem ser incluídos em suas solicitações POST paraAWS Storage Gateway. Os cabeçalhos mostrados a seguir que começam com “x-amz” sãoAWS-cabeçalhos específicos. Todos os outros cabeçalhos listados são cabeçalhos comuns usados em transações HTTP.
| Cabeçalho | Descrição |
|---|---|
Authorization |
O cabeçalho de autorização contém várias informações sobre a solicitação que permitemAWS Storage GatewayPara determinar 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 YourAccessKey, o ano, o mês e o dia (yyyymmdd), a região e CalculatedSignature. O formato do cabeçalho de autorização é determinado pelos requisitos doAWSProcesso de assinatura V4. Os detalhes da assinatura são discutidos no tópico Solicitações de assinatura. |
Content-Type |
Usar o
|
Host |
Use o cabeçalho do host para especificar oAWS Storage Gatewayendpoint para onde você envia sua solicitação. Por exemplo,
|
x-amz-date |
Você deve fornecer o time stamp no cabeçalho HTTP
|
x-amz-target |
Esse cabeçalho especifica a versão da API e a operação que você está solicitando. Os valores do cabeçalho de destino são formados por concatenação da versão da API e do nome da API e têm o formato a seguir.
O valor operationName (por exemplo, "ActivateGateway") pode ser encontrado na lista de API, Referência de API para Storage Gateway. |
Solicitações de assinatura
O Storage Gateway requer a autenticação de toda solicitação enviada 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 solicitação. Do contrário, a solicitação é rejeitada.
O Storage Gateway suporta autenticação usandoAWSSignature versão 4. O processo para calcular uma assinatura pode ser dividido em três tarefas:
-
Tarefa 1: Criar uma solicitação canônica
Reorganize sua solicitação HTTP em um formato canônico. Usar uma forma canônica é necessário porque o Storage Gateway usa a mesma forma canônica quando recalcula uma assinatura para comparar com a enviada por você.
-
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.
-
Tarefa 3: Criar uma assinatura
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. Para calcular a chave derivada, inicie sua chave de acesso secreta e use a string do escopo da credencial para criar uma série de códigos de autenticação de mensagem 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:
-
O time stamp da solicitação é "Mon, 10 Sep 2012 00:00:00" GMT.
-
O endpoint é a região Leste dos EUA (Ohio).
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: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 essa API (ou qualquer API do Storage Gateway).
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 for usada a chave de acesso secreta, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY, 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 para 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.
| Exceção | Message | Código de status HTTP |
|---|---|---|
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 ouAWSO ID da chave de acesso da 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. Verificar oAWSChave de 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 um válido (registrado)AWSID de chave de acesso ou 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 a carga JSON 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 |
OAWSO ID da chave de acesso da precisa de uma assinatura do serviço. | 400 solicitação inválida |
ThrottlingException |
Taxa excedida. | 400 solicitação inválida |
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 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.
| 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 |
| FileSystemAssociationEndpointConfigurationConflict |
A configuração de endpoint existente da File System Association entra em conflito com a configuração especificada. |
AssociateFilesystem |
| FileSystemAssociationEndPoinTipaddresSalreadyInUse |
O endereço IP do endpoint especificado já está em uso. |
AssociateFilesystem |
| FileSystemAssociationEndPoinTipAddressausente |
O endereço IP do endpoint da associação do sistema de arquivos está ausente. |
AssociateFilesystem |
| FileSystemAssociationNotFound |
Não foi encontrada a associação do sistema de arquivos especificado. |
|
| FileSystem NotFound |
O sistema de arquivos especificado não foi encontrado. |
AssociateFilesystem |
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 inválidos. | |
LocalStorageLimitExceeded |
O limite de armazenamento local foi excedido. | |
LunInvalid |
O LUN especificado é inválido. | 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:
-
Content-Type: application/x-amz-json-1.1
-
Um código de status HTTP
4xxou5xxapropriado
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.
- __type
-
Uma das exceções de Exceções.
Type: String
- error
-
Contém detalhes de erro específicos à API. Em erros genéricos (isto é, não específicos a nenhuma API), essa informação não é mostrada.
Type: Coleta
- errorCode
-
Um dos códigos de erro de operação .
Type: String
- errorDetails
-
Esse campo não é usado na versão atual da API.
Type: String
- mensagem
-
Uma das mensagens de código de erro de operação em .
Type: String
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 corresponde à 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 ver uma lista das operações do Storage Gateway, consulteAçõesnoAWS Storage GatewayReferência de API do.
