Integraciones de HTTP para las API de REST en API Gateway - Amazon API Gateway

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.

  • Establecer ANY en GET y {proxy+} en pets

    Solicitud de método iniciada desde el frontend:

    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1

    Solicitud de integración enviada al backend:

    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1

    Las instancias en tiempo de ejecución del método ANY y el recurso de proxy son válidas. La llamada devolverá una respuesta 200 OK con la carga que contiene el primer lote de mascotas, tal y como se devuelve desde el backend.

  • Establecer ANY en GET y {proxy+} en pets?type=dog

    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1

    Solicitud de integración enviada al backend:

    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1

    Las instancias en tiempo de ejecución del método ANY y el recurso de proxy son válidas. La llamada devolverá una respuesta 200 OK con la carga que contiene el primer lote de perros especificados, tal y como se devuelve desde el backend.

  • Establecer ANY en GET y {proxy+} en pets/{petId}

    Solicitud de método iniciada desde el frontend:

    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1

    Solicitud de integración enviada al backend:

    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1

    Las instancias en tiempo de ejecución del método ANY y el recurso de proxy son válidas. La llamada devolverá una respuesta 200 OK con la carga que contiene la mascota especificada, tal y como se devuelve desde el backend.

  • Establecer ANY en POST y {proxy+} en pets

    Solicitud de método iniciada desde el frontend:

    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 }

    Solicitud de integración enviada al 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 }

    Las instancias en tiempo de ejecución del método ANY y el recurso de proxy son válidas. La llamada devolverá una respuesta 200 OK con la carga que contiene la mascota recién creada, tal y como se devuelve desde el backend.

  • Establecer ANY en GET y {proxy+} en pets/cat

    Solicitud de método iniciada desde el frontend:

    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat

    Solicitud de integración enviada al backend:

    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat

    La instancia en tiempo de ejecución de la ruta del recurso de proxy no se corresponde con un punto de enlace del backend y la solicitud resultante no es válida. Como resultado, se devuelve una respuesta 400 Bad Request con el siguiente mensaje de error.

    { "errors": [ { "key": "Pet2.type", "message": "Missing required field" }, { "key": "Pet2.price", "message": "Missing required field" } ] }
  • Establecer ANY en GET y {proxy+} en null

    Solicitud de método iniciada desde el frontend:

    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test

    Solicitud de integración enviada al backend:

    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets

    El recurso de destino es el elemento principal del recurso de proxy, pero la instancia en tiempo de ejecución del método ANY no está definida en la API de ese recurso. Como resultado, esta solicitud GET devuelve una respuesta 403 Forbidden con el mensaje de error Missing Authentication Token devuelto por API Gateway. Si la API expone el método ANY o GET en el recurso principal (/), la llamada devuelve una respuesta 404 Not Found con el mensaje Cannot GET /petstore, tal y como se devuelve desde el backend.

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.