Configuration des intégrations HTTP dans API Gateway - Amazon API Gateway
Configuration des intégrations de proxy HTTP dans API Gateway Configuration des intégrations personnalisées HTTP

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.

Configuration des intégrations HTTP 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.

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 une intégration de proxy HTTP.

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

OpenAPI 3.0
{
   "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"
            }
         }
      }
   ]
}
OpenAPI 2.0
{
  "swagger": "2.0",
  "info": {
    "version": "2016-09-12T23:19:28Z",
    "title": "PetStoreWithProxyResource"
  },
  "host": "4z9giyi2c1.execute-api.us-east-1.amazonaws.com",
  "basePath": "/test",
  "schemes": [
    "https"
  ],
  "paths": {
    "/{proxy+}": {
      "x-amazon-apigateway-any-method": {
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "proxy",
            "in": "path",
            "required": true,
            "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"
        }
      }
    }
  }
}

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 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.

  • Définir ANY en tant que GET et {proxy+} en tant que pets

    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éponse 200 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 que GET et {proxy+} en tant que pets?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éponse 200 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 que GET et {proxy+} en tant que pets/{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éponse 200 OK avec la charge utile contenant l'animal spécifié, telle que retournée depuis le backend.

  • Définir ANY en tant que POST et {proxy+} en tant que pets

    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éponse 200 OK avec la charge utile contenant l'animal récemment créé, telle que retournée depuis le backend.

  • Définir ANY en tant que GET et {proxy+} en tant que pets/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 que GET et {proxy+} en tant que null

    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 demande GET renvoie une réponse 403 Forbidden avec le message d'erreur Missing Authentication Token comme celle renvoyée par API Gateway. Si l'API expose la méthode ANY ou GET sur la ressource parent (/), l'appel renvoie une réponse 404 Not Found avec le message Cannot 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 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 de plus amples informations sur la configuration des modèles de mappage, veuillez consulter Configuration des transformations de données pour les API REST.