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.
Intégrations HTTP pour les API REST dans API Gateway
Vous pouvez intégrer une méthode API à un point de terminaison HTTP grâce à l'intégration de proxy HTTP ou à l'intégration personnalisée HTTP.
API Gateway prend en charge les ports de point de terminaison suivants : 80, 443 et 1024-65535.
Avec l'intégration de proxy, la configuration est simple. Il vous suffit de définir la méthode HTTP et l'URI du point de terminaison HTTP, en fonction des exigences du backend, si vous n'êtes pas concerné par le codage de contenu ou la mise en cache.
Avec l'intégration personnalisée, la configuration est plus complexe. Outre la configuration de l'intégration de proxy, vous devez spécifier la façon dont les données des demandes entrantes sont mappées à la demande d'intégration et la façon dont les données de réponse d'intégration résultantes sont mappées à la réponse de méthode.
Rubriques
Configuration des intégrations de proxy HTTP dans API Gateway
Pour configurer une ressource de proxy avec le type d'intégration de proxy HTTP, créez une ressource d'API avec un paramètre de chemin gourmand (par exemple, /parent/{proxy+}
) et intégrez cette ressource à un point de terminaison de backend HTTP (par exemple, https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}
) sur la méthode ANY
. Le paramètre de chemin gourmand doit se trouver à la fin du chemin de ressource.
Comme avec une ressource autre que de proxy, vous pouvez configurer une ressource de proxy avec l'intégration de proxy HTTP à l'aide de la console API Gateway, en important un fichier de définition OpenAPI ou en appelant directement l'API REST API Gateway. Pour obtenir des instructions détaillées sur l'utilisation de la console API Gateway afin de configurer une ressource de proxy avec l'intégration HTTP, veuillez consulter Tutoriel : Création d'une API REST avec intégration d'un proxy HTTP.
Le fichier de définition OpenAPI suivant montre un exemple d'API avec une ressource proxy intégrée au PetStore
Dans cet exemple, une clé de cache est déclarée sur le paramètre de chemin method.request.path.proxy
de la ressource de proxy. Il s'agit du paramètre par défaut lorsque vous créez l'API à l'aide de la console API Gateway. Le chemin de base de l'API (/test
correspondant à une étape) est mappé à la PetStore page du site Web (/petstore
). La demande d'intégration unique reflète l'ensemble du PetStore site Web en utilisant la variable de chemin gourmand de l'API et la méthode ANY
fourre-tout. Les exemples suivants illustrent cette mise en miroir.
-
Définir
ANY
en tant queGET
et{proxy+}
en tant quepets
Demande de méthode initiée depuis le serveur frontal :
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1
Demande d'intégration envoyée au backend :
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1
Les instances d'exécution de la méthode
ANY
et de la ressource de proxy sont toutes les deux valides. L'appel renvoie une réponse200 OK
avec la charge utile contenant le premier lot d'animaux domestiques, telle que retournée depuis le serveur principal. -
Définir
ANY
en tant queGET
et{proxy+}
en tant quepets?type=dog
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1
Demande d'intégration envoyée au backend :
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1
Les instances d'exécution de la méthode
ANY
et de la ressource de proxy sont toutes les deux valides. L'appel renvoie une réponse200 OK
avec la charge utile contenant le premier lot de chiens spécifiés, telle que retournée depuis le serveur principal. -
Définir
ANY
en tant queGET
et{proxy+}
en tant quepets/{petId}
Demande de méthode initiée depuis le serveur frontal :
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1
Demande d'intégration envoyée au backend :
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1
Les instances d'exécution de la méthode
ANY
et de la ressource de proxy sont toutes les deux valides. L'appel renvoie une réponse200 OK
avec la charge utile contenant l'animal spécifié, telle que retournée depuis le backend. -
Définir
ANY
en tant quePOST
et{proxy+}
en tant quepets
Demande de méthode initiée depuis le serveur frontal :
POST https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1 Content-Type: application/json Content-Length: ... { "type" : "dog", "price" : 1001.00 }
Demande d'intégration envoyée au backend :
POST http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1 Content-Type: application/json Content-Length: ... { "type" : "dog", "price" : 1001.00 }
Les instances d'exécution de la méthode
ANY
et de la ressource de proxy sont toutes les deux valides. L'appel renvoie une réponse200 OK
avec la charge utile contenant l'animal récemment créé, telle que retournée depuis le backend. -
Définir
ANY
en tant queGET
et{proxy+}
en tant quepets/cat
Demande de méthode initiée depuis le serveur frontal :
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat
Demande d'intégration envoyée au backend :
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat
L'instance d'exécution du chemin de ressource de proxy ne correspond pas au point de terminaison du backend et la demande qui en résulte n'est pas valide. Par conséquent, une réponse
400 Bad Request
est renvoyée avec le message d'erreur suivant.{ "errors": [ { "key": "Pet2.type", "message": "Missing required field" }, { "key": "Pet2.price", "message": "Missing required field" } ] }
-
Définir
ANY
en tant queGET
et{proxy+}
en tant quenull
Demande de méthode initiée depuis le serveur frontal :
GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test
Demande d'intégration envoyée au backend :
GET http://petstore-demo-endpoint.execute-api.com/petstore/pets
La ressource ciblée est le parent de la ressource de proxy, mais l'instance d'exécution de la méthode
ANY
n'est pas définie dans l'API sur cette ressource. Par conséquent, cette demandeGET
renvoie une réponse403 Forbidden
avec le message d'erreurMissing Authentication Token
comme celle renvoyée par API Gateway. Si l'API expose la méthodeANY
ouGET
sur la ressource parent (/
), l'appel renvoie une réponse404 Not Found
avec le messageCannot GET /petstore
telle que retournée depuis le serveur principal.
Pour toute demande de client, si l'URL de point de terminaison ciblée n'est pas valide ou si le verbe HTTP est valide, mais non pris en charge, le backend renvoie une réponse 404 Not Found
. Pour une méthode HTTP non prise en charge, une réponse 403 Forbidden
est renvoyée.
Configuration des intégrations personnalisées HTTP dans API Gateway
Avec l'intégration personnalisée HTTP, vous avez davantage de contrôle sur les données à transmettre entre une méthode d'API et une intégration d'API, et sur la façon de les transmettre. Pour ce faire, vous devez utiliser les mappages de données.
Dans le cadre de la configuration de la demande de méthode, vous définissez la propriété requestParameters sur une ressource Method. Cette action permet de déclarer quels paramètres de la demande de méthode (qui sont mis en service à partir du client) doivent être mappés aux paramètres de demande d'intégration ou aux propriétés de corps applicables avant d'être envoyés vers le backend. Ensuite, dans le cadre de la configuration de la demande d'intégration, vous définissez la propriété RequestParameters sur la ressource d'intégration correspondante pour spécifier les mappages. parameter-to-parameter Vous définissez également la propriété requestTemplates afin de spécifier les modèles de mappage, un par type de contenu pris en charge. Les modèles de mappage mappent les paramètres de la demande de méthode, ou le corps, au corps de la demande d'intégration.
De même, dans le cadre de la configuration de la réponse de la méthode, vous définissez la propriété ResponseParameters sur la ressource. MethodResponse Cette action permet de déclarer quels paramètres de la réponse de méthode (qui sont envoyés au client) doivent être mappés depuis les paramètres de réponse d'intégration ou certaines propriétés de corps applicables renvoyés par le backend. Ensuite, dans le cadre de la configuration de la réponse d'intégration, vous définissez la propriété ResponseParameters sur la ressource IntegrationResponsecorrespondante pour spécifier les mappages. parameter-to-parameter Vous définissez également le mappage responseTemplates afin de spécifier les modèles de mappage, un par type de contenu pris en charge. Les modèles de mappage mappent les paramètres de la réponse d'intégration, ou les propriétés du corps de la réponse d'intégration, au corps de la réponse de méthode.
Pour de plus amples informations sur la configuration des modèles de mappage, veuillez consulter Transformations de données pour REST APIs in API Gateway.