Référence d’API pour Storage Gateway

Outre l'utilisation de la console, vous pouvez utiliser l' AWS Storage Gateway API pour configurer et gérer vos passerelles par programmation. Cette section décrit les AWS Storage Gateway opérations, la signature des demandes d'authentification et le traitement des erreurs. Pour obtenir des informations sur les régions et les points de terminaison disponibles pour Storage Gateway, consultez Points de terminaison et quotas AWS Storage Gateway dans le document Références générales AWS.

En-têtes de requêtes obligatoires pour Storage Gateway

Cette section décrit les en-têtes obligatoires que vous devez envoyer avec toutes les demandes POST à Storage Gateway. Vous incluez les en-têtes HTTP pour identifier les informations clés relatives à la demande, y compris l’opération que vous souhaitez appeler, la date de la demande et les informations correspondant à votre autorisation en tant qu’expéditeur de la demande. Les en-têtes ne sont pas sensibles à la casse et leur ordre n’est pas important.

L'exemple suivant montre les en-têtes utilisés dans l'ActivateGatewayopération.

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

Voici les en-têtes qui doivent être inclus avec vos demandes POST à Storage Gateway. Les en-têtes présentés ci-dessous qui commencent par « x-amz » sont AWS des en-têtes spécifiques. Tous les autres en-têtes répertoriés sont des en-têtes courants utilisés dans les transactions 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

Signature des requêtes

Storage Gateway exige l’authentification de chaque demande que vous envoyez en la signant. Pour signer une demande, vous calculez une signature numérique à l’aide d’une fonction de hachage cryptographique. Un hachage cryptographique est une fonction qui renvoie une valeur de hachage unique basée sur l’entrée. L’entrée de la fonction de hachage contient le texte de la demande et votre clé d’accès secrète. La fonction de hachage renvoie une valeur de hachage que vous incluez dans la demande comme votre signature. La signature fait partie de l’en-tête Authorization de votre demande.

Après avoir reçu votre demande, Storage Gateway recalcule la signature en utilisant la même fonction de hachage et la même entrée que vous avez utilisées pour signer la demande. Si la signature obtenue correspond à la signature de la demande, Storage Gateway traite la demande. Sinon, la demande est rejetée.

Storage Gateway prend en charge l’authentification à l’aide de AWS Signature Version 4. Le processus de calcul d’une signature peut être divisé en trois tâches :

Exemple de calcul de signature

L'exemple suivant vous guide à travers les détails de la création d'une signature pour ListGateways. L’exemple peut être utilisé comme référence pour vérifier votre méthode de calcul de signature. D’autres calculs de référence sont inclus dans le package Signature Version 4 Test Suite du Glossaire Amazon Web Services.

Dans cet exemple il est supposé que :

La syntaxe générale de la demande (y compris le corps JSON) est :

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
{}

La forme canonique de la demande calculée pour est :

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

La dernière ligne de la demande canonique est le hachage du corps de la demande. Notez également la troisième ligne vide dans la demande canonique. Cela est dû au fait qu'il n'existe aucun paramètre de requête pour cette API (ni pour aucune autre solution Storage Gateway APIs).

La chaîne à signer pour est :

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

La première ligne de la chaîne à signer est l’algorithme, la deuxième ligne est l’horodatage, la troisième ligne comporte la portée des informations d’identification, et la dernière ligne est un hachage de la demande canonique issue de la tâche 1.

Pour , la clé dérivée peut être représentée sous la forme :

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

S'il s'agit de la clé d'accès secrète, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY, est utilisé, alors la signature calculée est :

6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81

L’étape finale consiste à construire l’en-tête Authorization. Pour la clé d'accès à la démonstration AKIAIOSFODNN7EXAMPLE, l'en-tête (avec des sauts de ligne ajoutés pour plus de lisibilité) est :

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

Réponses d’erreur

Cette section fournit des informations de référence sur AWS Storage Gateway les erreurs. Ces erreurs sont représentées par une exception et un code d’erreur opération. Par exemple, l’exception InvalidSignatureException est retournée par toute réponse d’API en cas de problème avec la signature de la demande. Toutefois, le code d'erreur d'opération n'ActivationKeyInvalidest renvoyé que pour l'ActivateGatewayAPI.

En fonction du type d’erreur, Storage Gateway peut retourner simplement une exception, ou une exception et un code d’erreur opération. Vous trouverez des exemples de réponses d’erreur dans Réponses d’erreur.

Exceptions

Le tableau suivant répertorie les exceptions AWS Storage Gateway d'API. Lorsqu'une AWS Storage Gateway opération renvoie une réponse d'erreur, le corps de la réponse contient l'une de ces exceptions. Les codes de message InternalServerError et InvalidGatewayRequestException retournent l’un des codes d’erreur d’opération Codes d’erreur d’opération qui vous donnent le code d’erreur d’opération spécifique.

Codes d’erreur d’opération

Le tableau suivant montre le mappage entre les codes d'erreur d' AWS Storage Gateway opération et APIs ceux qui peuvent renvoyer les codes. Tous les codes d’erreur de fonctionnement sont renvoyés avec l’une des deux exceptions générales (InternalServerError et InvalidGatewayRequestException) décrites dans Exceptions.

Réponses d’erreur

Lorsqu’il y a une erreur, les informations de l’en-tête de réponse contiennent :

Le corps d’une réponse d’erreur contient des informations sur l’erreur qui s’est produite. L’exemple de réponse d’erreur suivant illustre la syntaxe de sortie des éléments de réponse commune à toutes les réponses d’erreur.

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

Le tableau suivant explique les champs de réponse d’erreur JSON affichés dans la syntaxe précédente.

Exemples de réponses d’erreur

Le corps JSON suivant est renvoyé si vous utilisez l' DescribeStorediSCSIVolumesAPI et spécifiez une entrée de demande ARN de passerelle qui n'existe pas.

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

Le corps JSON suivant est retourné si Storage Gateway calcule une signature qui ne correspond pas à celle envoyée avec une demande.

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

Opérations dans Storage Gateway

Pour obtenir la liste des opérations Storage Gateway consultez Actions dans Référence d’API AWS Storage Gateway .