La documentation de passerelle de fichiers Amazon S3 a été déplacée vers Qu’est-ce qu’une passerelle de fichiers Amazon S3 ?
La documentation Amazon FSx File Gateway a été déplacée vers Qu'est-ce qu'Amazon FSx File Gateway ?
La documentation de passerelle de bande a été déplacée vers Qu’est-ce qu’une passerelle de bande ?
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.
APIRéférence pour Storage Gateway
Outre l'utilisation de la console, vous pouvez utiliser le 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.
Note
Vous pouvez également utiliser le AWS SDKs lorsque vous développez des applications avec AWS Storage Gateway. Le AWS SDKs pour Java,. NET, et PHP encapsulez le AWS Storage Gateway API sous-jacent pour simplifier vos tâches de programmation. Pour plus d'informations sur le téléchargement des SDK bibliothèques, consultez la section Bibliothèques d'exemples de code
Rubriques
En-têtes de requêtes obligatoires pour Storage Gateway
Cette section décrit les en-têtes obligatoires que vous devez envoyer avec chaque POST demande à Storage Gateway. Vous incluez HTTP des en-têtes pour identifier les informations clés relatives à la demande, notamment l'opération que vous souhaitez invoquer, la date de la demande et les informations indiquant 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
Les en-têtes suivants doivent être inclus dans vos POST demandes adressées à 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 HTTP les transactions.
En-tête | Description |
---|---|
Authorization |
L’en-tête d’autorisation contient plusieurs informations sur la demande qui permettent à Storage Gateway de déterminer si la demande est une action valide pour la personne à l’origine de la demande. 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 l'année YourAccessKey, le mois et le jour (yyyymmdd), la région et le. CalculatedSignature Le format de l'en-tête d'autorisation est dicté par les exigences du processus de signature AWS V4. Les détails de la signature sont détaillés dans la rubrique Signature des requêtes. |
Content-Type |
Utilisez
|
Host |
Utilisez l’en-tête hôte pour spécifier le point de terminaison Storage Gateway vers lequel vous envoyez votre demande. Par exemple,
|
x-amz-date |
Vous devez fournir l'horodatage dans l'HTTP
|
x-amz-target |
Cet en-tête indique la version de l'opération API et l'opération que vous demandez. Les valeurs d'en-tête cibles sont formées en concaténant la API version avec le API nom et sont au format suivant.
La operationNamevaleur (par exemple ActivateGateway « ») peut être trouvée dans la API liste,APIRéférence pour Storage Gateway. |
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 :
-
Tâche 1 : créer une demande canonique
Réorganisez votre HTTP demande dans un format canonique. L’utilisation d’une forme canonique est nécessaire, car Storage Gateway utilise la même forme 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.
-
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 de portée des informations d'identification pour créer une série de codes d'authentification de message basés sur le hachage ()HMACs.
Exemple de calcul de signature
L'exemple suivant explique en détail comment créer 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 « Lundi 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 demande (JSONcorps compris) est la suivante :
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 cela API (ni pour aucun autre Storage GatewayAPIs).
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")
Si la clé d'accès secrète, wJalr XUtnFEMI /K7MDENG/bPxRfiCYEXAMPLEKEY, est utilisée, la signature calculée est la suivante :
6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81
L’étape finale consiste à construire l’en-tête Authorization
. Pour la clé d'accès à la démonstrationAKIAIOSFODNN7EXAMPLE, l'en-tête (avec des sauts de ligne ajoutés pour plus de lisibilité) est le suivant :
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 d'erreur InvalidSignatureException
est renvoyée par n'importe quelle API réponse en cas de problème avec la signature de la demande. Toutefois, le code d'erreur d'opération n'ActivationKeyInvalid
est renvoyé que pour le 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 AWS Storage Gateway API exceptions. 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.
Exception | Message | HTTPCode de statut |
---|---|---|
IncompleteSignatureException |
La signature spécifiée est incomplète. | 400 Requête erronée |
InternalFailure |
Le traitement de la demande 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 ou l’opération demandée n’est pas valide. | 400 Requête erronée |
InvalidClientTokenId |
Le certificat X.509 ou AWS l'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 votre clé AWS d'accès et votre méthode de signature. | 400 Requête erronée |
MissingAction |
Il manque un paramètre d’action ou d’opération dans la demande. | 400 Requête erronée |
MissingAuthenticationToken |
La demande doit contenir un ID de clé d' AWS accès valide (enregistré) ou un certificat X.509. | 403 Interdit |
RequestExpired |
La demande a dépassé la date d’expiration ou la date de la demande (l’un ou l’autre avec un remplissage de 15 minutes), ou la date de la demande 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 votre JSON charge utile est bien formée. | 400 Requête erronée |
ServiceUnavailable |
La demande a échoué en raison d’une défaillance temporaire du serveur. | 503 – Service non disponible |
SubscriptionRequiredException |
L'ID de clé d' AWS accès nécessite un abonnement pour le service. | 400 Requête erronée |
ThrottlingException |
Taux dépassé. | 400 Requête erronée |
TooManyRequests |
Nombre de demandes trop élevé. | 429 Trop de demandes |
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 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.
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 |
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 demande spécifiée contient des paramètres non valides. | |
LocalStorageLimitExceeded |
La limite de stockage local a été dépassée. | |
LunInvalid |
La valeur spécifiée LUN est incorrecte. | 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 :
-
Type de contenu : application/ -1.1 x-amz-json
-
Un code
4xx
ou un code5xx
HTTP de statut approprié
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 aux JSON erreurs présentés dans la syntaxe précédente.
- __type
-
L’une des exceptions deExceptions.
Type : chaîne
- error
-
Contient des informations API sur les erreurs spécifiques. Dans le cas des erreurs générales (c'est-à-dire qu'elles ne sont spécifiques à aucuneAPI), ces informations d'erreur ne sont pas affichées.
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 duAPI.
Type : chaîne
- message
-
Un des messages de code d’erreur d’opération .
Type : chaîne
Exemples de réponses d’erreur
Le JSON corps suivant est renvoyé si vous utilisez le DescribeStoredi SCSIVolumes API et spécifiez une entrée de ARN demande de passerelle qui n'existe pas.
{ "__type": "InvalidGatewayRequestException", "message": "The specified volume was not found.", "error": { "errorCode": "VolumeNotFound" } }
Le JSON corps suivant est renvoyé si Storage Gateway calcule une signature qui ne correspond pas à la signature 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 de Storage Gateway, reportez-vous à la section Actions de la AWS Storage Gateway APIréférence.