Intégrations HTTP pour les API REST dans API Gateway

Vous pouvez intégrer une méthode API avec 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.

Configuration des intégrations de proxy HTTP dans API Gateway

Pour configurer une ressource 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 avec 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 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 proxy avec l’intégration HTTP, consultez Didacticiel : création d’une API REST avec une intégration de proxy HTTP.

Le fichier de définition d’API OpenAPI suivant montre un exemple d’API avec une ressource proxy intégrée avec le site web PetStore.

{
   "openapi": "3.0.0",
   "info": {
      "version": "2016-09-12T23:19:28Z",
      "title": "PetStoreWithProxyResource"
   },
   "paths": {
      "/{proxy+}": {
         "x-amazon-apigateway-any-method": {
            "parameters": [
               {
                  "name": "proxy",
                  "in": "path",
                  "required": true,
                  "schema": {
                     "type": "string"
                  }
               }
            ],
            "responses": {},
            "x-amazon-apigateway-integration": {
               "responses": {
                  "default": {
                     "statusCode": "200"
                  }
               },
               "requestParameters": {
                  "integration.request.path.proxy": "method.request.path.proxy"
               },
               "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}",
               "passthroughBehavior": "when_no_match",
               "httpMethod": "ANY",
               "cacheNamespace": "rbftud",
               "cacheKeyParameters": [
                  "method.request.path.proxy"
               ],
               "type": "http_proxy"
            }
         }
      }
   },
   "servers": [
      {
         "url": "https://4z9giyi2c1.execute-api.us-east-1.amazonaws.com/{basePath}",
         "variables": {
            "basePath": {
              "default": "/test"
            }
         }
      }
   ]
}

Dans cet exemple, une clé de cache est déclarée sur le paramètre de chemin method.request.path.proxy de la ressource 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 page PetStore page du site web (/petstore). La demande d’intégration unique met en miroir l’intégralité du site web PetStore à l’aide de la variable de chemin gourmande et de la méthode ANY de l’API. Les exemples suivants illustrent cette mise en miroir.

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 Integration correspondante pour spécifier les mappages entre les paramètres. 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 méthode, vous définissez la propriété responseParameters sur une 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 IntegrationResponse correspondante pour spécifier les mappages entre les paramètres. 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 plus d’informations sur la configuration des modèles de mappage, consultez Transformations de données pour REST APIs dans API Gateway.