Integraciones de HTTP para las API de REST en API Gateway

Puede integrar un método de API con un punto de enlace HTTP mediante la integración de proxy HTTP o la integración HTTP personalizada.

API Gateway admite los siguientes puertos de punto de enlace: 80, 443 y 1024-65535.

Con la integración de proxy, la configuración es sencilla. Solo tiene que establecer el método HTTP y el URI del punto de enlace HTTP, según los requisitos de backend, si no le preocupa la codificación o el almacenamiento en caché del contenido.

Con la integración personalizada, la configuración requiere más pasos. Además de los pasos de configuración de integración de proxy, debe especificar cómo se mapean los datos entrantes de la solicitud a la solicitud de integración y cómo se mapean los datos resultantes de respuesta de la integración a la respuesta del método.

Configurar integraciones de proxy HTTP en API Gateway

Para configurar un recurso de proxy con el tipo de integración de proxy HTTP, cree un recurso de API con un parámetro de ruta extensiva (por ejemplo, /parent/{proxy+}) e integre este recurso con un punto de enlace HTTP del backend (por ejemplo, https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}) en el método ANY. El parámetro de ruta expansiva debe estar al final de la ruta del recurso.

Al igual que con un recurso que no es de proxy, puede configurar un recurso de proxy con la integración de proxy HTTP mediante la consola de API Gateway, importando un archivo de definición de OpenAPI o llamando a la API REST de API Gateway directamente. Para obtener instrucciones detalladas acerca de cómo utilizar la consola de API Gateway para configurar un recurso de proxy con la integración HTTP, consulte Tutorial: Creación de una API de REST con integración de proxy HTTP.

El siguiente archivo de definición de API de OpenAPI muestra un ejemplo de una API con un recurso de proxy que está integrado en el sitio 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"
        }
      }
    }
  }
}

En este ejemplo, una clave de caché se declara en el parámetro de ruta method.request.path.proxy del recurso de proxy. Esta es la configuración predeterminada al crear la API utilizando la consola de API Gateway. La ruta base de la API (/test, correspondiente a una etapa) se mapea a la página PetStore del sitio web (/petstore). La solicitud de integración replica todo el sitio web de PetStore utilizando la variable de ruta expansiva de la API y el método catch-all ANY. Los siguientes ejemplos ilustran esta replicación.

Para cualquier solicitud cliente, si la URL del punto de enlace de destino no es válida o el verbo HTTP es válido pero no es compatible, el backend devuelve una respuesta 404 Not Found. Para un método HTTP no admitido, se devuelve una respuesta 403 Forbidden.

Configurar integraciones HTTP personalizadas en API Gateway

Con la integración HTTP personalizada, obtiene más control sobre qué datos se transfieren entren un método de API y una integración de API y cómo transferir los datos. Para ello, se utilizan mapeos de datos.

Como parte de la configuración de solicitud de método, debe establecer la propiedad requestParameters en un recurso Method. Esto declara qué parámetros de solicitud de método, que se aprovisionan desde el cliente, se mapean a los parámetros de solicitud de integración o son aplicables a las propiedades de cuerpo antes de que se envíen al backend. A continuación, como parte de la configuración de solicitud de integración, debe establecer la propiedad requestParameters en el recurso correspondiente de Integration para especificar los mapeos entre parámetros. También debe establecer la propiedad requestTemplates para especificar plantillas de mapeo, una para cada tipo de contenido admitido. Dichas plantillas mapean los parámetros de solicitud de método, o el cuerpo, al cuerpo de solicitud de integración.

De forma similar, como parte de la configuración de respuesta de método, debe establecer la propiedad responseParameters en el recurso MethodResponse. Esto declara qué parámetros de respuesta de método, que se van a enviar al cliente, se mapean desde los parámetros de respuesta de integración o ciertas propiedades de cuerpo aplicables que se devolvieron desde el backend. A continuación, como parte de la configuración de respuesta de integración, debe establecer la propiedad responseParameters en el recurso IntegrationResponse correspondiente para especificar los mapeos entre parámetros. También debe establecer el mapa responseTemplates para especificar plantillas de mapeo, una para cada tipo de contenido admitido. Dichas plantillas mapean los parámetros de respuesta de integración, o bien las propiedades de cuerpo de respuesta de integración, al cuerpo de respuesta del método.

Para obtener más información sobre la configuración de plantillas de mapeo, consulte Transformaciones de datos para las API de REST en API Gateway.