Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
Référence API pour Storage Gateway
Outre la console, vous pouvez utiliser l'API AWS Storage Gateway pour configurer et gérer vos passerelles par programme. Cette section décrit les opérations AWS Storage Gateway, la signature des requêtes pour l'authentification et la gestion des erreurs. Pour plus d'informations sur les régions et points de terminaison disponibles pour Storage Gateway, consultezAWS Storage GatewayPoints de terminaison et quotasdans leAWSRéférence générale.
Note
Vous pouvez également utiliser l'AWSLes kits SDK lors du développement d'applications avec Storage Gateway. LeAWSLes kits de développement logiciel SDK pour Java, .NET et PHP enveloppent l'API Storage Gateway sous-jacente, simplifiant vos tâches de programmation. Pour de plus amples informations sur le téléchargement des bibliothèques de kits SDK, veuillez consulter Exemples de bibliothèques de codes
Rubriques
AWS Storage GatewayEn-têtes de requête obligatoires
Cette section décrit les en-têtes obligatoires que vous devez envoyer avec toutes les requêtes POST àAWS Storage Gateway. Vous incluez les en-têtes HTTP pour identifier les informations clés relatives à la requête, y compris l'opération que vous souhaitez appeler, la date de la requête et les informations correspondant à votre autorisation en tant qu'expéditeur de la requête. Les en-têtes ne sont pas sensibles à la casse et leur ordre n'est pas important.
Les exemples suivants montrent les en-têtes qui sont utilisés dans l'opération 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
Voici les en-têtes qui doivent être inclus avec vos requêtes POST àAWS Storage Gateway. Les en-têtes ci-dessous qui commencent par « x-amz » sontAWSEn-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.
| En-tête | Description |
|---|---|
Authorization |
L'en-tête d'autorisation contient plusieurs informations sur la requête qui permettent d'activerAWS Storage Gatewaypour déterminer si la requête est une action valide pour le demandeur. Le format de cet en-tête est le suivant (sauts de ligne ajoutés pour faciliter la lecture) :
Dans la syntaxe précédente, vous spécifiez YourAccessKey, l'année, le mois et le jour (AAAAMMJJ), la région et la CalculatedSignature. Le format de l'en-tête d'autorisation est déterminé par les exigences duAWSProcessus de signature V4. Les détails de la signature sont détaillés dans la rubrique Signature des requêtes. |
Content-Type |
Utiliser
|
Host |
Utilisez l'en-tête de l'hôte pour spécifier laAWS Storage Gatewaypoint de terminaison où vous envoyez votre demande. Par exemple,
|
x-amz-date |
Vous devez fournir l'horodatage dans l'en-tête HTTP
|
x-amz-target |
Cet en-tête spécifie la version de l'API et l'opération que vous demandez. Les valeurs d'en-tête cibles sont formées en concaténant la version de l'API avec le nom de l'API et ont le format suivant.
LeoperationNameLa valeur (par exemple « ActivateGateway ») se trouve dans la liste des API,Référence API pour Storage Gateway. |
Signature des requêtes
Storage Gateway exige que vous authentifiez toutes les requêtes que vous envoyez en signant la demande. 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 celles que vous avez utilisées pour signer la demande. Si la signature obtenue correspond à la signature de la requête, Storage Gateway traite la demande. Sinon, la demande est rejetée.
Storage Gateway permet l'authentification àAWSSignature Version 4. Le processus de calcul d'une signature peut être divisé en trois tâches :
-
Tâche 1 : Créer une demande canonique
Réorganiser votre demande HTTP dans un format canonique. L'utilisation d'une forme canonique est nécessaire, car Storage Gateway utilise le même formulaire canonique lorsqu'il recalcule une signature à comparer à celle que vous avez envoyée.
-
Tâche 2 : Créer une chaîne de connexion
Créez une chaîne que vous utiliserez comme une des valeurs d'entrée pour votre fonction de hachage cryptographique. La chaîne, appelée la chaîne de connexion, est une concaténation du nom de l'algorithme de hachage, de la date de la demande, d'une chaîne d'informations d'identification et de la demande convertie sous forme canonique de la tâche précédente. La chaîne d'informations d'identification elle-même est une concaténation de date, de région et d'informations de service.
-
Tâche 3 : Création d'une signature
Créez une signature pour votre demande à l'aide d'une fonction de hachage cryptographique qui accepte deux chaînes d'entrée : votre chaîne de connexion et une clé dérivée. La clé dérivée est calculée en commençant par votre clé d'accès secrète et en utilisant la chaîne d'informations d'identification pour créer un ensemble de codes d'authentification de message basés sur le hachage (HMAC).
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 :
-
L'horodatage de la demande est « Lun, 10 septembre 2012 00:00:00 GMT ».
-
Le point de terminaison est la région USA Est (Ohio).
La syntaxe générale de la requête (y compris le corps JSON) est :
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 {}
La forme canonique de la requête 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. En effet, il n'y a aucun paramètre de requête pour cette API (ou n'importe quelle API Storage Gateway).
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 requête 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")
Si la clé d'accès secrète, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY, est utilisée, la signature calculée est :
6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81
L'étape finale consiste à construire l'en-tête Authorization. Pour la clé d'accès de la démonstration AKIAIOSFODNN7EXAMPLE, l'en-tête (avec les sauts de ligne ajoutés pour faciliter la lecture) 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 les erreurs AWS Storage Gateway. 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 requête. Toutefois, le code d'erreur d'opération ActivationKeyInvalid est retourné uniquement pour l'API ActivateGateway.
En fonction du type d'erreur, Storage Gateway peut retourner uniquement 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 de l'API AWS Storage Gateway. Lorsqu'une opération AWS Storage Gateway retourne une réponse d'erreur, le corps de la réponse contient 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.
| Exception | Message | HTTP Status Code |
|---|---|---|
IncompleteSignatureException |
La signature spécifiée est incomplète. | 400 : Requête erronée |
InternalFailure |
Le traitement de la requête a échoué en raison d'une erreur inconnue, d'une exception ou d'un échec. | 500 Erreur de serveur interne |
InternalServerError |
Un des messages de code d'erreur d'opération Codes d'erreur d'opération. | 500 Erreur de serveur interne |
InvalidAction |
L'action demandée ou le fonctionnement n'est pas valide. | 400 : Requête erronée |
InvalidClientTokenId |
Le certificat X.509 ouAWSL'ID de clé d'accès fourni n'existe pas dans nos archives. | 403 : Interdit |
InvalidGatewayRequestException |
Un des messages de code d'erreur d'opération dans Codes d'erreur d'opération. | 400 : Requête erronée |
InvalidSignatureException |
La signature de demande que nous avons calculée ne correspond pas à la signature que vous avez fournie. Vérifiez votreAWSClé d'accès et méthode de signature. | 400 : Requête erronée |
MissingAction |
Il manque un paramètre d'action ou d'opération dans la requête. | 400 : Requête erronée |
MissingAuthenticationToken |
La requête doit comporter un document valide (enregistré)AWSID de clé d'accès ou un certificat X.509. | 403 : Interdit |
RequestExpired |
La requête a dépassé la date d'expiration ou la date de la requête (l'un ou l'autre avec un remplissage de 15 minutes), ou la date de la requête se produit dans 15 minutes à l'avenir. | 400 : Requête erronée |
SerializationException |
Une erreur s'est produite lors de la sérialisation. Vérifiez que la charge utile JSON est bien formée. | 400 : Requête erronée |
ServiceUnavailable |
La requête a échoué en raison d'une défaillance temporaire du serveur. | 503 – Service non disponible |
SubscriptionRequiredException |
LeAWSL'ID de clé d'accès a besoin d'un abonnement pour le service. | 400 : Requête erronée |
ThrottlingException |
Taux dépassé. | 400 : Requête erronée |
UnknownOperationException |
Une opération inconnue a été spécifiée. Les opérations valides sont répertoriées dans Opérations dans Storage Gateway. | 400 : Requête erronée |
UnrecognizedClientException |
Le jeton de sécurité inclus dans la demande n'est pas valide. | 400 : Requête erronée |
ValidationException |
La valeur du paramètre d'entrée est inexacte ou hors de portée. | 400 : Requête erronée |
Codes d'erreur d'opération
Le tableau suivant illustre le mappage entre les codes d'erreur d'opération AWS Storage Gateway et les API qui peuvent retourner les codes. Tous les codes d'erreur d'opération sont renvoyés avec l'une des deux exceptions générales suivantes :InternalServerErroretInvalidGatewayRequestException—décrit dansExceptions.
| Code d'erreur d'opération | Message | Opérations qui retournent ce code d'erreur |
|---|---|---|
ActivationKeyExpired |
La clé d'activation spécifiée a expiré. | ActivateGateway |
ActivationKeyInvalid |
La clé d'activation spécifiée n'est pas valide. | ActivateGateway |
ActivationKeyNotFound |
La clé d'activation spécifiée n'a pas été trouvée. | ActivateGateway |
BandwidthThrottleScheduleNotFound |
La limitation de bande passante spécifiée est introuvable. | DeleteBandwidthRateLimit |
CannotExportSnapshot |
L'instantané spécifié ne peut pas être exporté. | |
InitiatorNotFound |
L'initiateur spécifié est introuvable. | DeleteChapCredentials |
DiskAlreadyAllocated |
Le disque spécifié est déjà attribué. | |
DiskDoesNotExist |
Le disque spécifié n'existe pas. | |
DiskSizeNotGigAligned |
Le disque spécifié n'est pas aligné avec les Go. | |
DiskSizeGreaterThanVolumeMaxSize |
La taille du disque spécifiée est supérieure à la taille maximum du volume. | CreateStorediSCSIVolume |
DiskSizeLessThanVolumeSize |
La taille de disque spécifiée est inférieure à la taille du volume. | CreateStorediSCSIVolume |
DuplicateCertificateInfo |
Les informations de certificat spécifiées sont en doublon. | ActivateGateway |
| Conflit de configuration des points de terminaison de l'association de systèmes de fichiers |
La configuration du point de terminaison de l'association de systèmes de fichiers existante est en conflit avec la configuration |
Système de fichiers associé |
| Adresse IP d'association de systèmes de fichiers déjà en cours d'utilisation |
L'adresse IP du point de terminaison spécifiée est déjà utilisée. |
Système de fichiers associé |
| Adresse IP de l'association du système de fichiers de terminaison manquante |
L'adresse IP du point de terminaison de File System Association est manquante. |
Système de fichiers associé |
| Association de systèmes de fichiers introuvable |
L'association de système de fichiers spécifiée est introuvable. |
Mettre à jour l'association de systèmes de fichiers |
| Système de fichiers introuvable |
Le système de fichiers spécifié est introuvable. |
Système de fichiers associé |
GatewayInternalError |
Une erreur interne de passerelle est survenue. | |
GatewayNotConnected |
La passerelle spécifiée n'est pas connectée. | |
GatewayNotFound |
La passerelle spécifiée est introuvable. | |
GatewayProxyNetworkConnectionBusy |
La connexion réseau du proxy de la passerelle spécifiée est occupée. | |
InternalError |
Une erreur interne s'est produite. | |
InvalidParameters |
La requête spécifiée contient des paramètres non valides. | |
LocalStorageLimitExceeded |
La limite de stockage local a été dépassée. | |
LunInvalid |
Le préfixe LUN spécifié est non valide. | CreateStorediSCSIVolume |
MaximumVolumeCountExceeded |
Le nombre de volumes maximum a été dépassé. | |
NetworkConfigurationChanged |
La configuration du réseau de la passerelle a été modifiée. | |
NotSupported |
L'opération spécifiée n'est pas prise en charge. | |
OutdatedGateway |
La passerelle spécifiée n'est pas à jour. | ActivateGateway |
SnapshotInProgressException |
L'instantané spécifié est en cours. | DeleteVolume |
SnapshotIdInvalid |
L'instantané spécifié n'est pas valide. | |
StagingAreaFull |
La zone intermédiaire est pleine. | |
TargetAlreadyExists |
La cible spécifiée existe déjà. | |
TargetInvalid |
La cible spécifiée n'est pas valide. | |
TargetNotFound |
La cible spécifiée est introuvable. | |
UnsupportedOperationForGatewayType |
L'opération spécifiée n'est pas valide pour le type de passerelle. | |
VolumeAlreadyExists |
Le volume spécifié existe déjà. | |
VolumeIdInvalid |
Le volume spécifié n'est pas valide. | DeleteVolume |
VolumeInUse |
Le volume spécifié est déjà en cours d'utilisation. | DeleteVolume |
VolumeNotFound |
Le volume spécifié est introuvable. | |
VolumeNotReady |
Le volume spécifié n'est pas prêt. |
Réponses d'erreur
Lorsqu'il y a une erreur, les informations de l'en-tête de réponse contiennent :
-
Content-Type: application/x-amz-json-1.1
-
Un code d'état HTTP approprié
4xxou5xx
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.
- __type
-
L'une des exceptions deExceptions.
Type : Chaîne
- error
-
Contient les détails de l'erreur propres à l'API. Dans les erreurs générales (par exemple, celles qui ne sont pas spécifiques à une API en particulier), ces informations d'erreur n'apparaissent pas.
Type : Collection
- errorCode
-
L'un des codes d'erreur d'opération
Type : Chaîne
- errorDetails
-
Ce champ n'est pas utilisé dans la version actuelle de l'API.
Type : Chaîne
- message
-
Un des messages de code d'erreur d'opération .
Type : Chaîne
Exemples de réponses d'erreur
Le corps JSON suivant est renvoyé si vous utilisez l'API DescribeStorediSCSIVolumes et que vous spécifiez une entrée de demande d'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 requête.
{ "__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, consultezActionsdans leAWS Storage GatewayAPI Reference.
