# Desarrollo de las API de REST en API Gateway En Amazon API Gateway, las API REST se crean como una colección de entidades programables conocidas como [recursos](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) de API Gateway. Por ejemplo, se utiliza un recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) para representar una API que puede contener una colección de entidades [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html). Cada entidad `Resource` puede tener uno o más recursos [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html). Un `Method` es una solicitud entrante enviada por el cliente y puede contener los siguientes parámetros de solicitud: un parámetro de ruta, un encabezado o un parámetro de cadena de consulta. Además, según el método HTTP, la solicitud puede contener un cuerpo. El método define cómo el cliente accede al `Resource` expuesto. Para integrar el `Method` con un punto de conexión de backend, también conocido como punto de conexión de integración, se crea un recurso de [integración](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). Esto reenvía la solicitud entrante a un URI de punto de conexión de integración específico. Si es necesario, puede transformar los parámetros de la solicitud o el cuerpo de la solicitud para cumplir con los requisitos de backend o puede crear una integración de proxy, en la que API Gateway envía la solicitud completa en un formato estandarizado al URI del punto de conexión de integración y luego envía directamente la respuesta al cliente. Para las respuestas, puede crear un recurso [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) para representar una respuesta recibida por el cliente y crear un recurso [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) para representar la respuesta que devuelve el backend. Utilice una respuesta de integración para transformar los datos de respuesta del backend antes de devolver los datos al cliente o transferir la respuesta del backend tal y como está al cliente. ## Recurso de ejemplo para una API de REST En el siguiente diagrama se muestra cómo API Gateway implementa este modelo de solicitud/respuesta para un proxy HTTP y una integración HTTP sin proxy para el recurso `GET /pets`. El cliente envía el encabezado `x-version:beta` a API Gateway y API Gateway envía el código de estado `204` al cliente. En la integración sin proxy, API Gateway realiza transformaciones de datos para cumplir con los requisitos de backend, mediante la modificación de la solicitud de integración y la respuesta de integración. En una integración sin proxy, puede acceder al cuerpo en la solicitud del método, pero lo transforma en la solicitud de integración. Cuando el punto de conexión de integración devuelve una respuesta con un cuerpo, se accede a ella y se transforma en la respuesta de integración. No puede modificar el cuerpo en la respuesta del método. En la integración de proxy, el punto de conexión de integración modifica la solicitud y la respuesta. API Gateway no modifica la solicitud de integración ni la respuesta de integración y envía la solicitud entrante al backend tal cual. Independientemente del tipo de integración, el cliente ha enviado una solicitud a API Gateway y API Gateway ha respondido de forma sincrónica. ------ #### [ Non-proxy integration ] ![\[Diagrama de integración sin proxy de API Gateway\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/develop-non-proxy.png) ------ #### [ Proxy integration ] ![\[Diagrama de integración de proxy de API Gateway\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/develop-proxy.png) ------ Los siguientes registros de ejecución de ejemplo muestran lo que API Gateway registraría en el ejemplo anterior. Para mayor claridad, se han eliminado algunos valores y registros iniciales: ------ #### [ Non-proxy integration ] ``` Wed Feb 12 23:56:44 UTC 2025 : Starting execution for request: abcd-1234-5678 Wed Feb 12 23:56:44 UTC 2025 : HTTP Method: GET, Resource Path: /pets Wed Feb 12 23:56:44 UTC 2025 : Method request path: {} Wed Feb 12 23:56:44 UTC 2025 : Method request query string: {} Wed Feb 12 23:56:44 UTC 2025 : Method request headers: {x-version=beta} Wed Feb 12 23:56:44 UTC 2025 : Method request body before transformations: Wed Feb 12 23:56:44 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:56:44 UTC 2025 : Endpoint request headers: {app-version=beta} Wed Feb 12 23:56:44 UTC 2025 : Endpoint request body after transformations: Wed Feb 12 23:56:44 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:56:45 UTC 2025 : Received response. Status: 200, Integration latency: 123 ms Wed Feb 12 23:56:45 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:56:45 GMT} Wed Feb 12 23:56:45 UTC 2025 : Endpoint response body before transformations: Wed Feb 12 23:56:45 UTC 2025 : Method response body after transformations: (null) Wed Feb 12 23:56:45 UTC 2025 : Method response headers: {X-Amzn-Trace-Id=Root=1-abcd-12345} Wed Feb 12 23:56:45 UTC 2025 : Successfully completed execution Wed Feb 12 23:56:45 UTC 2025 : Method completed with status: 204 ``` ------ #### [ Proxy integration ] ``` Wed Feb 12 23:59:42 UTC 2025 : Starting execution for request: abcd-1234-5678 Wed Feb 12 23:59:42 UTC 2025 : HTTP Method: GET, Resource Path: /pets Wed Feb 12 23:59:42 UTC 2025 : Method request path: {} Wed Feb 12 23:59:42 UTC 2025 : Method request query string: {} Wed Feb 12 23:59:42 UTC 2025 : Method request headers: {x-version=beta} Wed Feb 12 23:59:42 UTC 2025 : Method request body before transformations: Wed Feb 12 23:59:42 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:59:42 UTC 2025 : Endpoint request headers: { x-version=beta} Wed Feb 12 23:59:42 UTC 2025 : Endpoint request body after transformations: Wed Feb 12 23:59:42 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:59:43 UTC 2025 : Received response. Status: 204, Integration latency: 123 ms Wed Feb 12 23:59:43 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT} Wed Feb 12 23:59:43 UTC 2025 : Endpoint response body before transformations: Wed Feb 12 23:59:43 UTC 2025 : Method response body after transformations: Wed Feb 12 23:59:43 UTC 2025 : Method response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT} Wed Feb 12 23:59:43 UTC 2025 : Successfully completed execution Wed Feb 12 23:59:43 UTC 2025 : Method completed with status: 204 ``` ------ Para importar una API similar y probarla en la Consola de administración de AWS, consulte la [API de ejemplo](api-gateway-create-api-from-example.md). ## Características adicionales de la API de REST para el desarrollo API Gateway admite características adicionales para el desarrollo de la API de REST. Por ejemplo, para ayudar a los clientes a comprender la API, puede proporcionar documentación para la API. Para ello, agregue un recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) para una entidad de API compatible. Para controlar el modo en que los clientes llaman a la API, utilice [permisos de IAM](permissions.md), un [autorizador de Lambda](apigateway-use-lambda-authorizer.md) o un [grupo de usuarios de Amazon Cognito](apigateway-integrate-with-cognito.md). Para medir el uso de la API, configure [planes de uso](api-gateway-api-usage-plans.md) para limitar las solicitudes a la API. Puede habilitar estos elementos al crear o al actualizar la API. En el siguiente diagrama se muestran las características disponibles para el desarrollo de la API de REST y dónde se configuran estas características en el modelo de solicitud/respuesta. ![\[Diagrama de las características de API Gateway\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/develop-features.png) Para obtener una introducción sobre cómo crear una API, consulte [Tutorial: Creación de una API de REST con una integración de proxy de Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md). Para obtener más información sobre las funciones de API Gateway que puede utilizar al desarrollar una API de REST, consulte los siguientes temas. Estos temas contienen información conceptual y procedimientos que puede realizar a través de la consola de API Gateway, la API de REST de API Gateway, la AWS CLI o uno de los AWS SDK. **Topics** + [ ## Recurso de ejemplo para una API de REST ](#rest-api-develop-example) + [ ## Características adicionales de la API de REST para el desarrollo ](#rest-api-develop-details) + [ # Tipos de punto de conexión para las API de REST en API Gateway ](api-gateway-api-endpoint-types.md) + [ # Políticas de seguridad de las API de REST en API Gateway ](apigateway-security-policies.md) + [ # Tipos de direcciones IP para API de REST en API Gateway ](api-gateway-ip-address-type.md) + [ # Métodos de API de REST en API Gateway ](how-to-method-settings.md) + [ # Control y administración del acceso a las API de REST en API Gateway ](apigateway-control-access-to-api.md) + [ # Integraciones para las API de REST en API Gateway ](how-to-integration-settings.md) + [ # Solicitud de la validación de las API de REST en API Gateway ](api-gateway-method-request-validation.md) + [ # Transformaciones de datos para las API de REST en API Gateway ](rest-api-data-transformations.md) + [ # Respuestas de Gateway para las API de REST en API Gateway ](api-gateway-gatewayResponse-definition.md) + [ # CORS para las API de REST en API Gateway ](how-to-cors.md) + [ # Tipos de medios binarios para las API de REST en API Gateway ](api-gateway-payload-encodings.md) + [ # Invocación de las API de REST en API Gateway ](how-to-call-api.md) + [ # Desarrollo de API de REST mediante OpenAPI en API Gateway ](api-gateway-import-api.md) # Tipos de punto de conexión para las API de REST en API Gateway Los tipos de *[punto de enlace de API](api-gateway-basic-concept.md#apigateway-definition-api-endpoints)* hacen referencia al nombre de host de la API. El tipo de punto de conexión de la API puede ser *optimizado para sistemas perimetrales*, *regional* o *privado*, en función de dónde se origine la mayoría del tráfico de la API. ## Punto de enlace de API optimizado para bordes Un *[punto de conexión de API optimizada para límites](api-gateway-basic-concept.md#apigateway-definition-edge-optimized-api-endpoint)* normalmente dirige las solicitudes al punto de presencia (POP) de CloudFront más cercano, lo que podría ayudar en caso de que sus clientes estén en distintas ubicaciones geográficas. Este es el tipo de punto de enlace predeterminado para las API REST de API Gateway. Las API optimizadas para sistemas perimetrales utilizan mayúsculas en la inicial de los nombres de los [encabezados HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) (por ejemplo, `Cookie`). CloudFront ordena las cookies HTTP según su nombre antes de reenviar la solicitud al origen. Para obtener más información sobre el modo en que CloudFront procesa las cookies, consulte [Almacenamiento en caché de contenido en función de cookies](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Cookies.html). Cualquier nombre de dominio personalizado que se utilice con una API optimizada para sistemas perimetrales se aplicará a todas las regiones. ## Puntos de enlace de API regionales Un *[punto de conexión de la API regional](api-gateway-basic-concept.md#apigateway-definition-regional-api-endpoint)* está destinado a los clientes que se encuentran en la misma región. Cuando un cliente que se ejecuta en una instancia de EC2 llama a una API en la misma región o cuando una API tiene por objeto servir a una cantidad reducida de clientes con altas demandas, una API regional reduce la sobrecarga de conexión. Para una API regional, el nombre de dominio personalizado es específico de la región en la que está implementada la API. Si implementa una API regional en varias regiones, esta puede tener el mismo nombre de dominio personalizado en todas las regiones. Puede utilizar dominios personalizados junto con Amazon Route 53 para realizar tareas como el [direccionamiento basado en latencia](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html#routing-policy-latency). Para obtener más información, consulte [Configuración de un nombre de dominio personalizado regional en API Gateway](apigateway-regional-api-custom-domain-create.md) y [Configuración de un nombre de dominio personalizado optimizado para la periferia para en API Gateway](how-to-edge-optimized-custom-domain-name.md). Los puntos de enlace de API regionales transfieren todos los nombres de encabezado tal y como están. **nota** En los casos en que los clientes de la API están dispersos geográficamente, sigue teniendo sentido utilizar un punto de conexión de API regional, junto con su propia distribución de Amazon CloudFront para garantizar que API Gateway no asocia la API con distribuciones de CloudFront controladas por servicios. Para obtener más información acerca de este caso de uso, consulte la sección sobre [cómo configurar API Gateway con mi propia distribución de CloudFront](https://repost.aws/knowledge-center/api-gateway-cloudfront-distribution). ## Puntos de enlace de API privados Un *[punto de enlace de API privado](api-gateway-basic-concept.md#apigateway-definition-private-api-endpoint)* es un punto de enlace de la API al que solo se pueda obtener acceso desde una Amazon Virtual Private Cloud (VPC) mediante un punto de enlace de la VPC de tipo interfaz, que es una interfaz de red de punto de enlace (ENI) que se crea en la VPC. Para obtener más información, consulte [API de REST privadas en API Gateway](apigateway-private-apis.md). Los puntos de enlace de API privados transfieren todos los nombres de encabezado tal y como están. # Cambio del tipo de punto de conexión de una API pública o privada en API Gateway Para cambiar el tipo de un punto de conexión de API, es preciso actualizar la configuración de la API. Puede cambiar un tipo de API existente a través de la consola de API Gateway, la AWS CLI o un AWS SDK para API Gateway. El tipo de punto de conexión no puede volver a cambiarse hasta que se complete el cambio actual, pero la API estará disponible. Se admiten los siguientes cambios de tipo de puntos de conexión: + De optimizado para bordes a regional o privado + De regional a optimizado para bordes o privado + De privado a regional No puede transformar una API privada en una API optimizada para límites. Si va a cambiar una API pública de optimizada para borde a regional o viceversa, tenga en cuenta que una API optimizada para borde puede comportarse de forma distinta a una API regional. Por ejemplo, una API optimizada para límites elimina el encabezado `Content-MD5`. Cualquier valor de hash MD5 transmitido al backend se puede expresar en un parámetro de cadena de solicitud o una propiedad del cuerpo. Sin embargo, la API regional transmite este encabezado, aunque puede reasignar el nombre de encabezado a otro nombre. Comprender estas diferencias le ayudará a decidir cómo actualizar una API optimizada para borde a una regional o cómo actualizar una API regional a una optimizada para borde. **Topics** + [ ## Uso de la consola de API Gateway para cambiar el tipo de punto de conexión de la API ](#migrate-api-using-console) + [ ## Uso de la AWS CLI para cambiar el tipo de punto de conexión de una API ](#migrate-api-using-aws-cli) ## Uso de la consola de API Gateway para cambiar el tipo de punto de conexión de la API Para cambiar el tipo de punto de conexión de la API, siga uno de estos procedimientos: **Para convertir un punto de conexión público de regional u optimizado para límites y viceversa** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. Elija **Configuración de la API**. 1. En la sección **Detalles de la API**, elija **Editar**. 1. En **Tipo de punto de conexión de la API**, seleccione **Optimizado para límites** o **Regional**. 1. Seleccione **Save changes (Guardar cambios)**. 1. Vuelva a implementar la API para que los cambios surtan efecto. **Conversión de un punto de conexión privado en un punto de conexión regional** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. Modifique la política de recursos de la API para eliminar cualquier mención a VPC o puntos de conexión de VPC, de modo que tanto las llamadas a la API que se realicen desde fuera de la VPC como las que se realicen desde dentro se ejecuten correctamente. 1. Elija **Configuración de la API**. 1. En la sección **Detalles de la API**, elija **Editar**. 1. En **Tipo de punto de conexión de la API**, seleccione **Regional**. 1. Seleccione **Save changes (Guardar cambios)**. 1. Quite la política de recursos de la API. 1. Vuelva a implementar la API para que los cambios surtan efecto. Como está migrando el tipo de punto de conexión de privado a regional, API Gateway cambia el tipo de dirección IP a IPv4. Para obtener más información, consulte [Tipos de direcciones IP para API de REST en API Gateway](api-gateway-ip-address-type.md). **Conversión de un punto de conexión regional en un punto de conexión privado** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. Cree una política de recursos que conceda acceso a la VPC o al punto de conexión de VPC. Para obtener más información, consulte [Paso 3: Configuración de una política de recursos para una API privada](apigateway-private-api-create.md#apigateway-private-api-set-up-resource-policy). 1. Elija **Configuración de la API**. 1. En la sección **Detalles de la API**, elija **Editar**. 1. En **Tipo de punto de conexión de la API**, seleccione **Privado**. 1. (Opcional) Para **ID del punto de conexión de VPC**, seleccione los ID de punto de conexión de VPC que desea asociar a la API privada. 1. Seleccione **Save changes (Guardar cambios)**. 1. Vuelva a implementar la API para que los cambios surtan efecto. Como está migrando el tipo de punto de conexión de regional a privado, API Gateway cambia el tipo de dirección IP a pila doble. Para obtener más información, consulte [Tipos de direcciones IP para API de REST en API Gateway](api-gateway-ip-address-type.md). ## Uso de la AWS CLI para cambiar el tipo de punto de conexión de una API El siguiente comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) permite actualizar una API optimizada para bordes a una API regional: ``` aws apigateway update-rest-api \ --rest-api-id a1b2c3 \ --patch-operations op=replace,path=/endpointConfiguration/types/EDGE,value=REGIONAL ``` La respuesta correcta tiene un código de estado `200 OK` y una carga similar a la siguiente: ``` { "createdDate": "2017-10-16T04:09:31Z", "description": "Your first API with Amazon API Gateway. This is a sample API that integrates via HTTP with our demo Pet Store endpoints", "endpointConfiguration": { "types": "REGIONAL" }, "id": "a1b2c3", "name": "PetStore imported as edge-optimized" } ``` El siguiente comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) permite actualizar una API regional a una API optimizada para bordes: ``` aws apigateway update-rest-api \ --rest-api-id a1b2c3 \ --patch-operations op=replace,path=/endpointConfiguration/types/REGIONAL,value=EDGE ``` Dado que [put-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-rest-api.html) se utiliza para actualizar definiciones de API, no puede utilizarse para actualizar un tipo de punto de conexión de API. # Políticas de seguridad de las API de REST en API Gateway Una *política de seguridad* es una combinación predefinida de versión mínima de TLS y conjuntos de cifrado que ofrece API Gateway. Cuando los clientes realizan un establecimiento de comunicación de TLS en la API o el nombre de dominio personalizado, la política de seguridad aplica la versión de TLS y el conjunto de cifrado aceptado por API Gateway. Las políticas de seguridad protegen las API y los nombres de dominio personalizados de los problemas de seguridad de red como, por ejemplo, la manipulación y el espionaje entre un cliente y el servidor. API Gateway admite políticas de seguridad heredadas y políticas de seguridad mejoradas. `TLS_1_0` y `TLS_1_2` son políticas de seguridad heredadas. Utilice estas políticas de seguridad para compatibilidad con versiones anteriores. Cualquier política que comience con `SecurityPolicy_` es una política de seguridad mejorada. Utilice estas políticas para cargas de trabajo reguladas, una gobernanza avanzada o para utilizar la criptografía poscuántica. Al utilizar una política de seguridad mejorada, también debe configurar el modo de acceso de punto de conexión para una mayor gobernanza. Para obtener más información, consulte [Modo de acceso de punto de conexión](#apigateway-security-policies-endpoint-access-mode). ## Cómo aplica API Gateway las políticas de seguridad El siguiente ejemplo muestra cómo API Gateway aplica las políticas de seguridad mediante la política de seguridad `SecurityPolicy_TLS13_1_3_2025_09` como ejemplo. La política de seguridad `SecurityPolicy_TLS13_1_3_2025_09` acepta el tráfico de TLS 1.3 y rechaza el tráfico de TLS 1.2 y TLS 1.0. Para el tráfico de TLS 1.3, la política de seguridad acepta los siguientes conjuntos de cifrado: + `TLS_AES_128_GCM_SHA256` + `TLS_AES_256_GCM_SHA384` + `TLS_CHACHA20_POLY1305_SHA256` API Gateway no acepta ningún otro conjunto de sistemas de cifrado. Por ejemplo, la política de seguridad rechazaría cualquier tráfico de TLS 1.3 que utilice el conjunto de cifrado de `AES128-SHA`. Para obtener más información acerca de los cifrados y versiones de TLS, consulte [Políticas de seguridad admitidas](apigateway-security-policies-list.md). Para supervisar qué protocolo TLS y qué cifrado utilizan los clientes para acceder a la API Gateway, puede utilizar las variables de contexto `$context.tlsVersion` y `$context.cipherSuite` en los registros de acceso. Para obtener más información, consulte [Supervisión de las API de REST en API Gateway](rest-api-monitor.md). ## Modo de acceso de punto de conexión El modo de acceso de punto de conexión es un parámetro adicional que debe especificar para cualquier API de REST o nombre de dominio personalizado que utilice una política de seguridad mejorada que comience por `SecurityPolicy_`. Esto se hace al crear el recurso o al cambiar la política de seguridad de una política heredada a una política mejorada. Cuando el modo de acceso de punto de conexión está configurado como `STRICT`, cualquier solicitud a la API de REST o al nombre de dominio personalizado debe superar las siguientes comprobaciones: + La solicitud debe provenir del mismo tipo de punto de conexión de API Gateway que el recurso. Puede provenir de un punto de conexión regional, optimizado para bordes o privado. + Si utiliza un punto de conexión regional o privado, API Gateway usa la coincidencia de host de SNI. Si utiliza un punto de conexión optimizado para bordes, API Gateway cumple con la protección de domain fronting de CloudFront. Para obtener más información, consulte [Domain fronting](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/CNAMEs.html#alternate-domain-names-restrictions). Si no se cumple alguna de estas condiciones, API Gateway rechaza la solicitud. Le recomendamos que utilice el modo de acceso de punto de conexión `STRICT` siempre que sea posible. Para migrar una API o un nombre de dominio existentes para utilizar un modo de acceso estricto de punto de conexión, primero actualice la política de seguridad a una política de seguridad mejorada y mantenga el modo de acceso de punto de conexión configurado en `BASIC`. Tras validar los registros de tráfico y acceso, configure el modo de acceso de punto de conexión en `STRICT`. Al migrar el modo de acceso de punto de conexión de `STRICT` a `BASIC`, el punto de conexión no estará disponible durante unos 15 minutos a medida que se propaguen los cambios. No debe configurar el modo de acceso de punto de conexión como `STRICT` para determinadas arquitecturas de aplicaciones, sino configurar el modo de acceso de punto de conexión como `BASIC`. En la siguiente tabla se muestran algunas arquitecturas de aplicaciones y una recomendación para que la API de REST o el nombre de dominio personalizado puedan utilizar el modo de acceso de punto de conexión `STRICT`. | Arquitectura | Migración sugerida | | --- | --- | | Uso de un punto de conexión de VPC para acceder a un nombre de dominio personalizado público. | Esta arquitectura utiliza tráfico de tipo cruzado entre puntos de conexión. Se recomienda que migre a [Nombres de dominio personalizados para API privadas en API Gateway](apigateway-private-custom-domains.md). | | Uso de cualquier método para invocar una API privada que no utilice un nombre de dominio personalizado o nombres de DNS privados. | Esta arquitectura crea una discordancia entre el encabezado del host y el SNI utilizado en el establecimiento de comunicación de TLS y no supera las restricciones de domain fronting de CloudFront. Le recomendamos que migre la VPC para usar un DNS privado. | | Uso de la partición de dominios para distribuir contenido en varios dominios o subdominios. | Esta arquitectura crea una discordancia entre el encabezado del host y el SNI utilizado en el establecimiento de comunicación de TLS y no supera las restricciones de domain fronting de CloudFront. Le recomendamos utilizar `HTTP/2` y dejar de utilizar este antipatrón. | A continuación, se incluyen consideraciones que se deben tener a la hora de utilizar el modo de acceso de punto de conexión: + Si el modo de acceso de punto de conexión de una API o un nombre de dominio es `STRICT`, no puede cambiar el tipo de punto de conexión. Para cambiar el tipo de punto de conexión, primero cambie el modo de acceso del punto de conexión a `BASIC`. + Tras cambiar el modo de acceso del punto de conexión de `BASIC` a `STRICT`, API Gateway tarda 15 minutos en aplicar el modo de acceso estricto del punto de conexión. + Al cambiar una política de seguridad de una política que comienza con `SecurityPolicy_` a una política heredada, debe desactivar el modo de acceso del punto de conexión a `""`. ## Consideraciones A continuación, se muestran consideraciones sobre las políticas de seguridad para las API de REST en API Gateway: + Puede importar la política de seguridad en un archivo de definición de OpenAPI. Para obtener más información, consulte [x-amazon-apigateway-endpoint-access-modex-amazon-apigateway-security-policy](openapi-extensions-security-policy.md). + La API se puede asignar a un nombre de dominio personalizado con una política de seguridad diferente a la de la API. Al invocar ese nombre de dominio personalizado, API Gateway utiliza la política de seguridad de la API para negociar el establecimiento de comunicación TLS. Si desactiva el punto de conexión de la API predeterminado, esto podría afectar a la forma en que los intermediarios pueden invocar a la API. + Si cambia la política de seguridad, esta tardará unos 15 minutos en completarse. Puede supervisar el `apiStatus` de la API. A medida que la API se actualice, el `apiStatus` será `UPDATING` y cuando se complete será `AVAILABLE`. Si el estado de la API es `UPDATING`, puede seguir invocándola. + API Gateway admite políticas de seguridad en todas las API. Sin embargo, solo puede elegir una política de seguridad para las API de REST. API Gateway solo admite la política de seguridad `TLS_1_2` para las API HTTP o de WebSocket. + No puede actualizar la política de seguridad de una API de `TLS_1_0` a `TLS_1_2`. + Algunas políticas de seguridad admiten los conjuntos de cifrado ECDSA y RSA. Si utiliza este tipo de política con un nombre de dominio personalizado, los conjuntos de cifrado coinciden con el tipo de clave de certificado proporcionada por el cliente, ya sea RSA o ECDSA. Si utiliza este tipo de política con una API de REST, los conjuntos de cifrado coinciden con los conjuntos de cifrado compatibles con los tipos de certificados RSA. # Políticas de seguridad admitidas En las siguientes tablas se describen las [políticas de seguridad](apigateway-security-policies.md) que se pueden especificar para cada tipo de punto de conexión de API de REST y tipo de nombre de dominio personalizado. Estas políticas le permiten controlar las conexiones entrantes. API Gateway solo admite TLS 1.2 en salida. Puede actualizar la política de seguridad de la API o nombre de dominio personalizado en cualquier momento. Las políticas que contienen `FIPS` en el título son compatibles con el Estándar de procesamiento de la información federal (FIPS), que es un estándar de los gobiernos de EE. UU. y Canadá que especifica los requisitos de seguridad de los módulos criptográficos que protegen información confidencial. Para obtener más información, consulte [Estándar de procesamiento de la información federal (FIPS) 140-3](https://aws.amazon.com/compliance/fips/) en la página Conformidad de *Seguridad en la nube de AWS*. Todas las políticas FIPS utilizan el módulo criptográfico AWS-LC validado para FIPS. Para obtener más información, consulte la página del [módulo criptográfico AWS-LC](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4631) en el sitio *NIST Cryptographic Module Validation Program*. Las políticas que contienen `PQ` en el título utilizan la [criptografía poscuántica (PQC)](https://aws.amazon.com/security/post-quantum-cryptography/) para implementar algoritmos híbridos de intercambio de claves para TLS a fin de garantizar la confidencialidad del tráfico contra las futuras amenazas de la computación cuántica. Las políticas que contienen `PFS` en el título utilizan [Perfect Forward Secrecy (PFS)](https://en.wikipedia.org/wiki/Forward_secrecy) para garantizar que las claves de sesión no se vean comprometidas. Las políticas que contienen `FIPS` y `PQ` en su título admiten estas características. ## Políticas de seguridad predeterminadas Al crear una nueva API de REST o un dominio personalizado, se asigna al recurso una política de seguridad predeterminada. En la tabla siguiente se muestra la política de seguridad predeterminada para estos recursos. | **Recurso** | **Nombre de la política de seguridad predeterminada** | | --- | --- | | API regionales | TLS\$11\$10 | | API optimizadas para límites | TLS\$11\$10 | | API privadas | TLS\$11\$12 | | Dominio regional | TLS\$11\$12 | | Dominio optimizado para bordes | TLS\$11\$12 | | Dominio privado | TLS\$11\$12 | ## Políticas de seguridad compatibles para las API regionales y privadas y los nombres de dominio personalizados En la siguiente tabla se describen las políticas de seguridad que se pueden especificar para API regionales y privadas y nombres de dominio personalizados: | **Política de seguridad** | **Versiones compatibles de TLS** | **Cifrados compatibles** | | --- | --- | --- | | SecurityPolicy\$1TLS13\$11\$13\$12025\$109 | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1TLS13\$11\$13\$1FIPS\$12025\$109 | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1TLS13\$11\$12\$1PFS\$1PQ\$12025\$109 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1TLS13\$11\$12\$1PQ\$12025\$109 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | TLS\$11\$12 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | TLS\$11\$10 | TLS1.3 TLS1.2 TLS1.1 TLS1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) | ## Políticas de seguridad compatibles para las API optimizadas para bordes y los nombres de dominio personalizados En la siguiente tabla se describen las políticas de seguridad que se pueden especificar para API optimizadas para bordes y nombres de dominio personalizados optimizados para bordes: | **Nombre de política de seguridad** | **Versiones compatibles de TLS** | **Cifrados compatibles** | | --- | --- | --- | | SecurityPolicy\$1TLS13\$12025\$1EDGE | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1TLS12\$1PFS\$12025\$1EDGE | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1TLS12\$12018\$1EDGE | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | TLS\$11\$10 | TLS1.3 TLS1.2 TLS1.1 TLS1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-security-policies-list.html) | ## Nombre del cifrado OpenSSL y RFC OpenSSL e IETF RFC 5246 utilizan nombres distintos para los mismos cifrados. En la siguiente tabla se asigna el nombre de OpenSSL al nombre de RFC para cada uno de los cifrados. Para obtener más información, consulte [cifrados](https://docs.openssl.org/1.1.1/man1/ciphers/) en la documentación de OpenSSL. | **Nombre del cifrado de OpenSSL** | **Nombre del cifrado de RFC** | | --- | --- | | TLS\$1AES\$1128\$1GCM\$1SHA256 | TLS\$1AES\$1128\$1GCM\$1SHA256 | | TLS\$1AES\$1256\$1GCM\$1SHA384 | TLS\$1AES\$1256\$1GCM\$1SHA384 | | TLS\$1CHACHA20\$1POLY1305\$1SHA256 | TLS\$1CHACHA20\$1POLY1305\$1SHA256 | | ECDHE-RSA-AES128-GCM-SHA256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 | | ECDHE-RSA-AES128-SHA256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 | | ECDHE-RSA-AES128-SHA | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA | | ECDHE-RSA-AES256-GCM-SHA384 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 | | ECDHE-RSA-AES256-SHA384 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | | ECDHE-RSA-AES256-SHA | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA | | AES128-GCM-SHA256 | TLS\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 | | AES256-GCM-SHA384 | TLS\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 | | AES128-SHA256 | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 | | AES256-SHA | TLS\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA | | AES128-SHA | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA | | DES-CBC3-SHA | TLS\$1RSA\$1WITH\$13DES\$1EDE\$1CBC\$1SHA | # Cómo cambiar una política de seguridad Puede cambiar la política de seguridad para la API. Si envía tráfico a las API a través del nombre de dominio personalizado, no es necesario que la API y el nombre de dominio personalizado tengan la misma política de seguridad. Al invocar ese nombre de dominio personalizado, API Gateway utiliza la política de seguridad de la API para negociar el establecimiento de comunicación TLS. Sin embargo, para mantener la coherencia, le recomendamos que utilice la misma política de seguridad para el nombre de dominio y la API personalizados. Si cambia la política de seguridad, esta tardará unos 15 minutos en completarse. Puede supervisar el `apiStatus` de la API. A medida que la API se actualice, el `apiStatus` será `UPDATING` y cuando se complete será `AVAILABLE`. Cuando se actualice la API, puede seguir invocándola. ------ #### [ Consola de administración de AWS ] **Cambio de la política de seguridad de una API** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. Elija **Configuración de la API** y, a continuación, elija **Editar**. 1. Para **Política de seguridad**, seleccione una nueva política que comience con `SecurityPolicy_`. 1. Para **Modo de acceso de punto de conexión**, elija **Estricto**. 1. Seleccione **Save changes (Guardar cambios)**. Vuelva a implementar la API para que los cambios se apliquen. Como ha cambiado el modo de acceso del punto de conexión a estricto, los cambios tardarán unos 15 minutos en propagarse por completo. ------ #### [ AWS CLI ] El comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) siguiente permite actualizar una API para utilizar la política de seguridad `SecurityPolicy_TLS13_1_3_2025_09`: ``` aws apigateway update-rest-api \ --rest-api-id abcd1234 \ --patch-operations '[ { "op": "replace", "path": "/securityPolicy", "value": "SecurityPolicy_TLS13_1_3_2025_09" }, { "op": "replace", "path": "/endpointAccessMode", "value": "STRICT" } ]' ``` El resultado será similar al siguiente: ``` { "id": "abcd1234", "name": "MyAPI", "description": "My API with a new security policy", "createdDate": "2025-02-04T11:47:06-08:00", "apiKeySource": "HEADER", "endpointConfiguration": { "types": [ "REGIONAL" ], "ipAddressType": "dualstack" }, "tags": {}, "disableExecuteApiEndpoint": false, "securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09", "endpointAccessMode": "STRICT" "rootResourceId": "efg456" } ``` El comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) siguiente actualiza una API que usaba una política de seguridad mejorada para utilizar la política de seguridad de `TLS_1_0`. ``` aws apigateway update-rest-api \ --rest-api-id abcd1234 \ --patch-operations '[ { "op": "replace", "path": "/securityPolicy", "value": "TLS_1_0" }, { "op": "replace", "path": "/endpointAccessMode", "value": "" } ]' ``` El resultado será similar al siguiente: ``` { "id": "abcd1234", "name": "MyAPI", "description": "My API with a new security policy", "createdDate": "2025-02-04T11:47:06-08:00", "apiKeySource": "HEADER", "endpointConfiguration": { "types": [ "REGIONAL" ], "ipAddressType": "dualstack" }, "tags": {}, "disableExecuteApiEndpoint": false, "securityPolicy": "TLS_1_0", "rootResourceId": "efg456" } ``` ------ # Tipos de direcciones IP para API de REST en API Gateway Al crear una API, se especifica el tipo de direcciones IP que puede invocar la API. Puede elegir IPv4 para resolver las direcciones IPv4 para invocar la API o puede elegir pila doble para permitir que las direcciones IPv4 e IPv6 invoquen la API. Le recomendamos que establezca el tipo de dirección IP en pila doble para mitigar el agotamiento del espacio IP o para mejorar la postura de seguridad. Para obtener más información sobre los beneficios de un tipo de dirección IP de pila doble, consulte [IPv6 en AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html). Para restringir la API solo al tráfico IPv6, puede crear una política de recursos y restringir las direcciones IP de origen solo a los rangos de IPv6. Puede cambiar el tipo de dirección IP actualizando la configuración de la API. Este cambio se efectuará de forma inmediata y no es necesario que vuelva a implementar la API. Para obtener más información, consulte [Ejemplo: Cómo denegar el tráfico a una API para una dirección o un rango de direcciones IP de origen](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example) ## Consideraciones para los tipos de direcciones IP Es posible que las siguientes consideraciones afecten al uso de los tipos de direcciones IP: + El tipo de dirección IP predeterminado para todas las API regionales y optimizadas para la periferia es IPv4. + Las API privadas solo pueden tener un tipo de dirección IP de pila doble. + Si cambia el tipo de dirección IP de una API existente de IPv4 a pila doble, confirme que todas las políticas que controlan el acceso a las API se hayan actualizado para tener en cuenta las llamadas de IPv6. Cuando cambia el tipo de dirección IP, el cambio surte efecto inmediatamente. + Si migra el tipo de punto de conexión de una API de regional u optimizada para la periferia a privada, API Gateway cambia el tipo de dirección IP a pila doble. Para obtener más información, consulte [Cambio del tipo de punto de conexión de una API pública o privada en API Gateway](apigateway-api-migration.md). + Si migra el tipo de punto de conexión de una API de privada a regional, debe configurar el tipo de dirección IP en pila doble. Una vez finalizada la migración del punto de conexión, puede cambiar el tipo de dirección IP a IPv4. Para obtener más información, consulte [Cambio del tipo de punto de conexión de una API pública o privada en API Gateway](apigateway-api-migration.md). + La API se puede asignar a un nombre de dominio personalizado con un tipo de dirección IP diferente al de la API. Si desactiva el punto de conexión de la API predeterminado, esto podría afectar a la forma en que los intermediarios pueden invocar a la API. + No puede usar un archivo de definición externo para configurar el tipo de dirección IP de la API. # Cambio del tipo de dirección IP de una API de REST Puede cambiar el tipo de dirección IP actualizando la configuración de la API. Puede actualizar la configuración de la API mediante el uso de la Consola de administración de AWS, la AWS CLI, CloudFormation o un AWS SDK. Si cambia el tipo de dirección IP de la API, no es necesario volver a implementar la API para que los cambios surtan efecto. Antes de cambiar el tipo de dirección IP, confirme que las políticas que controlan el acceso a las API se hayan actualizado para tener en cuenta las llamadas de IPv6. ------ #### [ Consola de administración de AWS ] **Cambio del tipo de dirección IP de una API de REST** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. Elija **Configuración de la API** y, a continuación, elija **Editar**. 1. Para tipo de dirección IP, seleccione **IPv4** o **Pila doble**. 1. Seleccione **Save changes (Guardar cambios)**. El cambio en la configuración de la API se aplicará de forma inmediata. ------ #### [ AWS CLI ] El siguiente comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) actualiza una API para que tenga un tipo de dirección IP de pila doble: ``` aws apigateway update-rest-api \ --rest-api-id abcd1234 \ --patch-operations "op='replace',path='/endpointConfiguration/ipAddressType',value='dualstack'" ``` El resultado será similar al siguiente: ``` { "id": "abcd1234", "name": "MyAPI", "description": "My API with a dualstack IP address type", "createdDate": "2025-02-04T11:47:06-08:00", "apiKeySource": "HEADER", "endpointConfiguration": { "types": [ "REGIONAL" ], "ipAddressType": "dualstack" }, "tags": {}, "disableExecuteApiEndpoint": false, "rootResourceId": "efg456" } ``` ------ # Métodos de API de REST en API Gateway En API Gateway, un método de API incluye una [solicitud de método](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) y una [respuesta de método](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). Se configura un método de API para definir lo que un cliente debería o debe hacer para enviar una solicitud de acceso al servicio en el backend y para definir las respuestas que recibe a cambio el cliente. Para la entrada, puede elegir los parámetros de solicitud de método, o bien una carga aplicable, para que el cliente proporcione los datos necesarios u opcionales en el tiempo de ejecución. Para la salida, se determina el código de estado de respuesta del método, los encabezados y el cuerpo aplicable como destinos a los que asignar los datos de respuesta del backend, antes de que se devuelvan al cliente. Para ayudar al desarrollador cliente a comprender los comportamientos y los formatos de entrada y salida de su API, puede [documentar la API](api-gateway-documenting-api.md) y [ofrecer mensajes de error adecuados](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) para [solicitudes no válidas](api-gateway-method-request-validation.md). Una solicitud de método de API es una solicitud HTTP. Para configurar la solicitud de método, debe configurar un método (o verbo) HTTP, la ruta a un [recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) de API, los encabezados y los parámetros de cadenas de consulta aplicables. También configura una carga cuando el método HTTP es `POST`, `PUT`o `PATCH`. Por ejemplo, para recuperar una mascota con la [API de muestra PetStore](api-gateway-create-api-from-example.md), define la solicitud de método de API de `GET /pets/{petId}`, donde `{petId}` es un parámetro de ruta que puede tomar un número en tiempo de ejecución. ``` GET /pets/1 Host: apigateway.us-east-1.amazonaws.com ... ``` Si el cliente especifica una ruta incorrecta, por ejemplo, `/pet/1` o `/pets/one` en lugar de `/pets/1`, se lanza una excepción. Una respuesta de método de API es una respuesta HTTP con un código de estado determinado. Para una integración que no sea de proxy, debe configurar respuestas de método para especificar los destinos necesarios u opcionales de las asignaciones. Estos transforman los encabezados o el cuerpo de respuesta de la integración en encabezados o en cuerpo de respuesta de método. El mapeo puede ser tan sencillo como una [transformación de identidad](https://en.wikipedia.org/wiki/Identity_transform) que pasa los encabezados o el cuerpo a través de la integración tal y como están. Por ejemplo, la siguiente respuesta de método `200` muestra un ejemplo de transferencia de una respuesta de integración correcta tal y como está. ``` 200 OK Content-Type: application/json ... { "id": "1", "type": "dog", "price": "$249.99" } ``` En principio, puede definir una respuesta de método correspondiente a una respuesta específica desde el backend. Normalmente, esto implica cualquier respuesta 2XX, 4XX y 5XX. Sin embargo, puede que no sea práctico, porque a menudo es posible que no sepa con antelación todas las respuestas que puede devolver un backend. En la práctica, puede designar una respuesta de método como predeterminada para gestionar las respuestas desconocidas o no asignadas desde el backend. Es una buena práctica designar la respuesta 500 como predeterminada. En cualquier caso, debe configurar al menos una respuesta de método para integraciones que no sean de proxy. De lo contrario, API Gateway devuelve una respuesta de error 500 al cliente incluso cuando la solicitud se completa correctamente en el backend. Para admitir un SDK con establecimiento inflexible de tipos para la API, como un SDK de Java, debe definir el modelo de datos de entrada para la solicitud de método y definir el modelo de datos de salida de la respuesta de método. ## Requisitos previos Antes de configurar un método de API, verifique lo siguiente: + El método debe estar disponible en API Gateway. Siga las instrucciones en [Tutorial: Creación de una API de REST con integración no de proxy HTTP](api-gateway-create-api-step-by-step.md). + Si desea que el método se comunique con una función de Lambda, debe haber creado ya el rol de invocación de Lambda y el rol de ejecución de Lambda en IAM. También debe haber creado la función de Lambda con la que el método se comunicará en AWS Lambda. Para crear los roles y funciones, utilice las instrucciones de [Creación de una función de Lambda para la integración de Lambda no de proxy](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda) de [Elección de un tutorial de integración de AWS Lambda](getting-started-with-lambda-integration.md). + Si desea que el método se comunique con una integración HTTP o de proxy HTTP, debe haber creado y tener acceso a la URL del punto de conexión HTTP con la que se comunicará el método. + Compruebe que API Gateway admite los certificados de los puntos de conexión HTTP y proxy de HTTP. Para obtener más información, consulte [Entidades de certificación compatibles con API Gateway para las integraciones HTTP y Proxy HTTP en API Gateway](api-gateway-supported-certificate-authorities-for-http-endpoints.md). **Topics** + [ ## Requisitos previos ](#method-setting-prerequisites) + [ # Configurar una solicitud de método en API Gateway ](api-gateway-method-settings-method-request.md) + [ # Configuración de una respuesta de método en API Gateway ](api-gateway-method-settings-method-response.md) + [ # Configuración de un método con la consola de API Gateway ](how-to-set-up-method-using-console.md) # Configurar una solicitud de método en API Gateway Configurar una solicitud de método implica realizar las siguientes tareas, después de la creación de un recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html): 1. Creación de una nueva API o elección de una entidad [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) de API existente. 1. Creación de un recurso [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) de API que sea un verbo HTTP específico en el `Resource` nuevo o elegido de la API. Esta tarea se puede dividir aún más en las siguientes subtareas: + Añadido de un método HTTP a la solicitud de métodos + Configuración de parámetros de solicitudes + Definición de un modelo para el cuerpo de la solicitud + Aplicación de un esquema de autorización + Habilitación de la validación de la solicitud Puede realizar estas tareas con los siguientes métodos: + [Consola de API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console) + Comandos de la AWS CLI ([create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) y [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html)) + Función del SDK de AWS (como, en Node.js, [createResource](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#createResource-property) y [putMethod](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#putMethod-property)) + API REST de API Gateway ([resource:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateResource.html) y [method:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html)). **Topics** + [ ## Configurar recursos de API ](#setup-method-resources) + [ ## Configurar un método HTTP ](#setup-method-add-http-method) + [ ## Configurar parámetros de solicitud de método ](#setup-method-request-parameters) + [ ## Configuración de un modelo de solicitud de método ](#setup-method-request-model) + [ ## Configurar la autorización de solicitud de método ](#setup-method-request-authorization) + [ ## Configurar la validación de solicitud de método ](#setup-method-request-validation) ## Configurar recursos de API En una API de API Gateway, los recursos que se pueden dirigir se exponen como un árbol de entidades [Resources](https://docs.aws.amazon.com/apigateway/latest/api/API_GetResources.html) de API, con el recurso de raíz (`/`) en la parte superior de la jerarquía. El recurso de raíz depende de la URL base de la API, que se compone del punto de conexión de la API y un nombre de etapa. En la consola de API Gateway, este URI base se denomina **Invoke URI** y se muestra en el editor de etapas de la API una vez que se implementa la API. El punto de conexión de la API puede ser un nombre de host predeterminado o un nombre de dominio personalizado. El nombre de host predeterminado tiene el siguiente formato: ``` {api-id}.execute-api.{region}.amazonaws.com ``` En este formato, la *\$1api-id\$1* representa el identificador de la API que genera API Gateway. La variable `{region}` representa la región de AWS (por ejemplo, `us-east-1`) que eligió al crear la API. Un nombre de dominio personalizado es cualquier nombre fácil de recordar en un dominio de Internet válido. Por ejemplo, si ha registrado un dominio de Internet de `example.com`, `*.example.com` es un nombre de dominio personalizado válido. Para obtener más información, consulte [configurar nombres de dominio personalizados](how-to-custom-domains.md). Para la [API de ejemplo de PetStore](api-gateway-create-api-from-example.md), el recurso de raíz (`/`) expone la tienda de mascotas. El recurso `/pets` representa la variedad de mascotas disponibles en la tienda. El `/pets/{petId}` expone una mascota individual de un identificador concreto (`petId`). El parámetro de la ruta de `{petId}` forma parte de los parámetros de solicitudes. Para configurar un recurso de API, se elige un recurso existente como principal y, a continuación, se crea el recurso secundario bajo el recurso principal. Se empieza con el recurso raíz como principal, se añade un recurso a este principal, se añade otro recurso a este recurso secundario como nuevo principal, etc., a su identificador principal. A continuación, se añade el recurso designado al principal. El siguiente comando [get-resources](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-resources.html) permite recuperar todos los recursos de una API: ``` aws apigateway get-resources --rest-api-id apiId ``` En la API del ejemplo de PetStore, el resultado sería similar al siguiente: ``` { "items": [ { "path": "/pets", "resourceMethods": { "GET": {} }, "id": "6sxz2j", "pathPart": "pets", "parentId": "svzr2028x8" }, { "path": "/pets/{petId}", "resourceMethods": { "GET": {} }, "id": "rjkmth", "pathPart": "{petId}", "parentId": "6sxz2j" }, { "path": "/", "id": "svzr2028x8" } ] } ``` Cada elemento enumera los identificadores del recurso (`id`) y, excepto el recurso raíz, su recurso principal inmediato (`parentId`), así como el nombre del recurso (`pathPart`). El recurso raíz es especial, ya que no tiene ninguno principal. Después de elegir un recurso como principal, use el siguiente comando para agregar un recurso secundario. ``` aws apigateway create-resource --rest-api-id apiId \ --parent-id parentId \ --path-part resourceName ``` Por ejemplo, para agregar comida para mascotas a la venta en el sitio web de PetStore, use el siguiente comando: ``` aws apigateway create-resource --rest-api-id a1b2c3 \ --parent-id svzr2028x8 \ --path-part food ``` El resultado será similar al siguiente: ``` { "path": "/food", "pathPart": "food", "id": "xdsvhp", "parentId": "svzr2028x8" } ``` ### Utilizar un recurso proxy para simplificar la configuración de API A medida que crece el negocio, el propietario de PetStore puede que decida añadir a la venta alimentos, juguetes y otros artículos relacionados con mascotas. Para sustentarlo, puede añadir `/food`, `/toys` y otros recursos debajo del recurso raíz. Debajo de cada categoría de venta, es posible que también desee añadir más recursos, como por ejemplo `/food/{type}/{item}`, `/toys/{type}/{item}`, etc. Esto puede ser una tarea tediosa. Si decide añadir una capa intermedia `{subtype}` a las rutas de recursos para cambiar la jerarquía de rutas a `/food/{type}/{subtype}/{item}`, `/toys/{type}/{subtype}/{item}`, etc., los cambios afectarán a la configuración existente de la API. Para evitarlo, puede utilizar un [recurso de proxy](api-gateway-set-up-simple-proxy.md) de API Gateway para exponer un conjunto de recursos de la API a la vez. API Gateway define un recurso de proxy como un marcador de posición para que un recurso se especifique cuando se envíe la solicitud. Un recurso de proxy se expresa mediante un parámetro de ruta especial de `{proxy+}`, a menudo denominado parámetro de ruta expansiva. El signo `+` indica los recursos secundarios que lleva asociados. El marcador de posición `/parent/{proxy+}` equivale a cualquier recurso que coincida con el patrón de ruta de `/parent/*`. Puede usar cualquier cadena para el nombre del parámetro de ruta expansiva. El siguiente comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) permite crear un recurso de proxy bajo la raíz (`/{proxy+}`): ``` aws apigateway create-resource --rest-api-id apiId \ --parent-id rootResourceId \ --path-part {proxy+} ``` El resultado será similar al siguiente: ``` { "path": "/{proxy+}", "pathPart": "{proxy+}", "id": "234jdr", "parentId": "svzr2028x8" } ``` Para el ejemplo de API de `PetStore`, puede utilizar `/{proxy+}` para representar tanto `/pets` como `/pets/{petId}`. Este recurso de proxy también puede hacer referencia a cualquier otro recurso (existente o que se vaya a añadir), como por ejemplo `/food/{type}/{item}`, `/toys/{type}/{item}`, etc., o `/food/{type}/{subtype}/{item}`, `/toys/{type}/{subtype}/{item}`, etc. El desarrollador del backend determina la jerarquía de recursos y el desarrollador cliente es responsable de comprenderlo. API Gateway simplemente transfiere lo que envíe el cliente al backend. Una API puede tener más de un recurso de proxy. Por ejemplo, los siguientes recursos de proxy están permitidos dentro de una API, lo que supone que `/parent/{proxy+}` no está en el mismo segmento principal que `/parent/{child}/{proxy+}`. ``` /{proxy+} /parent/{proxy+} /parent/{child}/{proxy+} ``` Cuando un recurso de proxy tiene elementos secundarios que no son de proxy, los recursos secundarios se excluyen de la representación del recurso de proxy. En los ejemplos anteriores, `/{proxy+}` hace referencia a cualquier recurso bajo el recurso raíz, excepto los recursos `/parent[/*]`. En otras palabras, una solicitud de método realizada para un recurso específico prevalece sobre una solicitud de método realizada para un recurso genérico en el mismo nivel de la jerarquía de recursos. En la siguiente tabla se muestra cómo API Gateway enruta las solicitudes a los siguientes recursos para la etapa `prod` de una API. ``` ANY /{proxy+} GET /pets/{proxy+} GET /pets/dog ``` | Solicitud | Ruta seleccionada | Explicación | | --- | --- | --- | | `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/dog` | `GET /pets/dog` | La solicitud coincide completamente con este recurso. | | `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/cats` | `GET /pets/{proxy+}` | La variable de ruta expansiva `/pets/{proxy+}` captura esta solicitud. | | `GET https://api-id.execute-api.region.amazonaws.com/prod/animals` | `GET /{proxy+}` | La variable de ruta expansiva `/{proxy+}` captura esta solicitud. | Un recurso de proxy no puede tener cualquier recurso secundario. Un recurso de API después de `{proxy+}` es redundante y ambiguo. Los siguientes recursos de proxy no se permiten dentro de una API. ``` /{proxy+}/child /parent/{proxy+}/{child} /parent/{child}/{proxy+}/{grandchild+} ``` ## Configurar un método HTTP Una solicitud de métodos de API se encapsula mediante el recurso [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) de API Gateway. Para configurar la solicitud de método, primero debe iniciar el recurso `Method`, configurando al menos un método HTTP y un tipo de autorización en el método. API Gateway, estrechamente asociado con el recurso de proxy, admite un método HTTP de `ANY`. Este método `ANY` representa cualquier método HTTP que se suministre en el tiempo de ejecución. Le permite utilizar una sola configuración de método de API para todos los métodos HTTP admitidos de `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` y `PUT`. También puede configurar el método `ANY` en un recurso que no sea de proxy. Al combinar el método `ANY` con un recurso de proxy, obtiene una configuración de método de API único para todos los métodos compatibles con HTTP frente a cualquier recurso de una API. Además, el backend puede evolucionar sin que afecte a la configuración de API existente. Antes de configurar un método de API, tenga en cuenta quién puede llamar al método. Establezca el tipo de autorización según su plan. Para un acceso abierto, establézcalo en `NONE`. Para utilizar permisos de IAM, establezca el tipo de autorización en `AWS_IAM`. Para utilizar una función de autorizador de Lambda, establezca esta propiedad en `CUSTOM`. Para utilizar un grupo de usuarios de Amazon Cognito, establezca el tipo de autorización en `COGNITO_USER_POOLS`. El siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) permite crear una solicitud de método para el verbo `ANY` utilizando permisos de IAM para controlar el acceso. ``` aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method ANY \ --authorization-type AWS_IAM ``` Para crear una solicitud de método de API con un tipo de autorización distinta, consulte [Configurar la autorización de solicitud de método](#setup-method-request-authorization). ## Configurar parámetros de solicitud de método Los parámetros de solicitud de método son una forma para que un cliente proporcione los datos de entrada o el contexto de ejecución necesarios para completar la solicitud de métodos. Un parámetro de método puede ser un método de ruta, un encabezado o un parámetro de cadena de consulta. Como parte de la configuración de solicitud de método, debe declarar los parámetros de solicitud necesarios para que estén disponibles para el cliente. Para la integración que no sea de proxy, puede traducir estos parámetros de solicitud en un formato que sea compatible con el requisito del backend. Por ejemplo, para la solicitud de métodos `GET /pets/{petId}`, la variable de ruta `{petId}` es un parámetro de solicitud necesario. Puede declarar este parámetro de ruta cuando llame al comando `put-method` de la AWS CLI. El siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) permite crear un método con un parámetro de ruta obligatorio: ``` aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id rjkmth \ --http-method GET \ --authorization-type "NONE" \ --request-parameters method.request.path.petId=true ``` Si un parámetro no es necesario, puede establecerlo en `false` en `request-parameters`. Por ejemplo, si el método `GET /pets` utiliza un parámetro de cadena de consulta opcional de `type` y un parámetro de encabezado opcional de `age`, puede declararlos usando el siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html): ``` aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --authorization-type "NONE" \ --request-parameters method.request.querystring.type=false,method.request.header.age=false ``` En lugar de esta forma abreviada, puede utilizar una cadena de JSON para establecer el valor `request-parameters`: ``` '{"method.request.querystring.type":false,"method.request.header.age":false}' ``` Con esta configuración, el cliente puede consultar las mascotas por tipo: ``` GET /pets?type=dog ``` Y el cliente puede consultar qué perros son cachorros de la siguiente manera: ``` GET /pets?type=dog age:puppy ``` Para obtener información sobre cómo asignar parámetros de solicitud de método a parámetros de solicitud de integración, consulte [Integraciones para las API de REST en API Gateway](how-to-integration-settings.md). ## Configuración de un modelo de solicitud de método Para un método de API que pueda tomar datos de entrada en una carga, puede utilizar un modelo. Un modelo se expresa en un [esquema JSON, borrador 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) y describe la estructura de datos del cuerpo de la solicitud. Con un modelo, un cliente puede determinar cómo construir una carga de solicitud de métodos como entrada. Y lo que es más importante, API Gateway utiliza el modelo para [validar una solicitud](api-gateway-method-request-validation.md), [generar un SDK](how-to-generate-sdk.md) e inicializar una plantilla de mapeo para configurar la integración en la consola de API Gateway. Para obtener información sobre cómo crear un [modelo](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html), consulte [Comprensión de los modelos de datos](models-mappings-models.md). En función de los tipos de contenido, una carga de método puede tener diferentes formatos. Un modelo se indexa frente al tipo de medio de la carga aplicada. API Gateway utiliza el encabezado de la solicitud `Content-Type` para determinar el tipo de contenido. Para configurar modelos de solicitud de método, añada pares de clave-valor con el formato `"media-type":"model-name"` al mapa `requestModels` cuando llame al comando AWS CLI de la `put-method`. Para utilizar el mismo modelo independientemente del tipo de contenido, especifique `$default` como la clave. Por ejemplo, para establecer un modelo en la carga útil de JSON de la solicitud del método `POST /pets` de la API de ejemplo de PetStore, puede usar el siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html): ``` aws apigateway put-method \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method POST \ --authorization-type "NONE" \ --request-models '{"application/json":"petModel"}' ``` Aquí, `petModel` es el valor de propiedad `name` de un recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) que describe una mascota. La definición del esquema real se expresa como un valor de cadena JSON de la propiedad [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema) del recurso `Model`. En un SDK Java de la API, u otro tipo de SDK con establecimiento inflexible de tipos, los datos de entrada se forman como la clase `petModel` derivada de la definición del esquema. Con el modelo de solicitud, los datos de entrada en el SDK generado se forman en la clase `Empty`, que se deriva del modelo `Empty` predeterminado. En este caso, el cliente no puede crear una instancia de la clase de datos correcta para proporcionar la entrada necesaria. ## Configurar la autorización de solicitud de método Para controlar quién puede llamar al método de la API, puede configurar el [tipo de autorización](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType) en el método. Puede utilizar este tipo para aplicar uno de los autorizadores admitidos, incluidos roles y políticas de IAM (`AWS_IAM`), un grupo de usuarios de Amazon Cognito (`COGNITO_USER_POOLS`), o un autorizador de Lambda basado en funciones de Lambda (`CUSTOM`). Para utilizar permisos de IAM para autorizar el acceso al método de la API, establezca la propiedad de entrada `authorization-type` en **AWS\$1IAM**. Cuando esta opción está establecida, API Gateway verifica la firma del intermediario en la solicitud en función de las credenciales del intermediario. Si el usuario verificado tiene permiso para llamar al método, se acepta la solicitud. De lo contrario, rechaza la solicitud y el intermediario recibe una respuesta de error no autorizado. La llamada al método no se realiza correctamente a menos que el intermediario tenga permiso para invocar el método de la API. La siguiente política de IAM concede permiso al intermediario para llamar a cualquier método de API creado dentro de la misma Cuenta de AWS: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": "arn:aws:execute-api:*:*:*" } ] } ``` ------ Para obtener más información, consulte [Control del acceso a una API de REST con permisos de IAM](permissions.md). Actualmente, solo puedes conceder esta política a los usuarios, grupos y roles de la Cuenta de AWS del propietario de la API. Los usuarios de una Cuenta de AWS diferente pueden llamar a los métodos de la API solo si se les permite asumir un rol de la Cuenta de AWS del propietario de la API con los permisos necesarios para llamar a la acción `execute-api:Invoke`. Para obtener más información sobre los permisos entre cuentas, consulte [Uso de roles de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html). Puede utilizar la AWS CLI, un AWS SDK o un cliente de API de REST, como [Postman](https://www.postman.com/), que implementa la [firma de Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html). Para utilizar un autorizador de Lambda con el fin de autorizar el acceso al método de la API, establezca la propiedad de entrada `authorization-type` en `CUSTOM` y establezca la propiedad de entrada [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) en el valor de propiedad [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) de un autorizador de Lambda que ya exista. El autorizador de Lambda al que se hace referencia puede ser del tipo `TOKEN` o `REQUEST`. Para obtener información acerca de cómo crear un autorizador de Lambda, consulte [Uso de autorizadores Lambda de API Gateway](apigateway-use-lambda-authorizer.md). Para utilizar un grupo de usuarios de Amazon Cognito con el fin de autorizar el acceso al método de la API, establezca la propiedad de entrada `authorization-type` en `COGNITO_USER_POOLS` y establezca la propiedad de entrada [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) en el valor de propiedad [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) del autorizador `COGNITO_USER_POOLS` que ya se creó. Para obtener información sobre la creación de un autorizador de grupo de usuarios de Amazon Cognito, consulte [Control del acceso a las API de REST con grupos de usuarios de Amazon Cognito como autorizador](apigateway-integrate-with-cognito.md). ## Configurar la validación de solicitud de método Puede habilitar la validación de solicitud al configurar una solicitud de método de API. Primero debe crear un [validador de solicitudes](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html). El siguiente comando [create-request-validator](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-request-validator.html) permite crear un validador de solicitud de solo cuerpo. ``` aws apigateway create-request-validator \ --rest-api-id 7zw9uyk9kl \ --name bodyOnlyValidator \ --validate-request-body \ --no-validate-request-parameters ``` El resultado será similar al siguiente: ``` { "validateRequestParameters": false, "validateRequestBody": true, "id": "jgpyy6", "name": "bodyOnlyValidator" } ``` Con este validador de solicitud, puede usar la validación de solicitudes como parte de la configuración de solicitudes del método. El siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) permite crear una solicitud de método que requiera que el cuerpo de la solicitud entrante coincida con el `PetModel` y tiene dos parámetros de solicitud que no son obligatorios: ``` aws apigateway put-method \ --rest-api-id 7zw9uyk9kl \ --resource-id xdsvhp \ --http-method PUT \ --authorization-type "NONE" \ --request-parameters '{"method.request.querystring.type": false, "method.request.querystring.page":false}' \ --request-models '{"application/json":"petModel"}' \ --request-validator-id jgpyy6 ``` Para incluir un parámetro de solicitud en la validación de la solicitud, debe establecer `validateRequestParameters` en `true` para el validador de solicitudes, y establecer el parámetro de solicitud específico en `true` en el comando `put-method`. # Configuración de una respuesta de método en API Gateway Una respuesta de método de API encapsula el resultado de una solicitud de método de API que el cliente recibirá. Los datos de salida incluyen un código de estado HTTP, algunos encabezados y posiblemente un cuerpo. Con las integraciones que no sean de proxy, los parámetros de respuesta especificados y el cuerpo se pueden asignar desde los datos de respuesta de integración asociados o se les pueden asignar determinados valores estáticos según las asignaciones. Estas asignaciones se especifican en la respuesta de integración. La asignación puede ser una transformación idéntica que transfiere la respuesta de integración tal y como es. Con una integración de proxy, API Gateway transfiere la respuesta del backend a la respuesta del método automáticamente. No es necesario configurar la respuesta del método de API. Sin embargo, con la integración proxy de Lambda, la función de Lambda debe devolver un resultado de [este formato de salida](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format) para que API Gateway asigne correctamente la respuesta de integración a una respuesta de método. Mediante programación, la configuración de la respuesta de método equivale a crear un recurso [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) de API Gateway y a establecer las propiedades de [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode), [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) y [responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels). Al establecer códigos de estado para un método de API, debe elegir uno como predeterminado para gestionar cualquier respuesta de integración de un código de estado no previsto. Es razonable establecer `500` como predeterminado, ya que esto equivale a emitir respuestas que de otro modo no estarían asignadas como un error del servidor. Por motivos de instrucción, la consola de API Gateway establece la respuesta `200` como la opción predeterminada. Pero puede restablecerla en la respuesta `500`. Para configurar una respuesta de método, debe haber creado la solicitud de método. ## Configurar el código de estado de la respuesta de método El código de estado de una respuesta de método define un tipo de respuesta. Por ejemplo, las respuestas de 200, 400 y 500 indican respuestas de éxito, de error del lado del cliente y de error del lado del servidor, respectivamente. Para configurar un código de estado de respuesta de método, establezca la propiedad [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode) en un código de estado HTTP. El siguiente comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) permite crear la respuesta del método `200`. ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 ``` ## Configurar parámetros de respuesta de métodos Los parámetros de respuesta de método definen qué encabezados recibe el cliente en respuesta a la solicitud de método asociado. Los parámetros de respuesta también especifican un objetivo al que API Gateway asigna un parámetro de respuesta de integración, según los mapeos prescritos en la respuesta de integración del método de la API. Para configurar los parámetros de respuesta de método, agregue al mapa [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) de `MethodResponse` pares de clave-valor con el formato `"{parameter-name}":"{boolean}"`. El siguiente comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) permite establecer el encabezado `my-header`. ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 \ --response-parameters method.response.header.my-header=false ``` ## Configurar modelos de respuesta de método Un modelo de respuesta de método define un formato del cuerpo de la respuesta del método. Es necesario configurar un modelo de respuesta de método al generar un SDK con establecimiento inflexible de tipos para la API. Garantiza que el resultado se emite en una clase apropiada en Java u Objective-C. En otros casos, la configuración de un modelo es opcional. Antes de configurar el modelo de respuesta, primero debe crear el modelo en API Gateway. Para ello, puede llamar al comando `[create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html)`. El siguiente comando [create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html) permite crear un modelo `PetStorePet` para describir el cuerpo de la respuesta para la solicitud del método `GET /pets/{petId}`. ``` aws apigateway create-model \ --rest-api-id vaz7da96z6 \ --content-type application/json \ --name PetStorePet \ --schema '{ \ "$schema": "http://json-schema.org/draft-04/schema#", \ "title": "PetStorePet", \ "type": "object", \ "properties": { \ "id": { "type": "number" }, \ "type": { "type": "string" }, \ "price": { "type": "number" } \ } \ }' ``` El resultado se crea como un recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) de API Gateway. Para configurar los modelos de respuesta de método para definir el formato de la carga, agregue el par de clave-valor "application/json":"PetStorePet" al mapa [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels) del recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). El siguiente comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) permite crear un método de respuesta que utilice un modelo de respuesta para definir el formato de carga útil: ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 \ --response-parameters method.response.header.my-header=false \ --response-models '{"application/json":"PetStorePet"}' ``` # Configuración de un método con la consola de API Gateway Al crear un método mediante la consola de la API de REST, se configuran la solicitud de integración y la solicitud del método. De forma predeterminada, API Gateway crea la respuesta del método `200` para el método. Las siguientes instrucciones muestran cómo editar la configuración de la solicitud de método y cómo crear respuestas de método adicionales para el método. **Topics** + [ ## Edición de una solicitud de método de API Gateway en la consola de API Gateway ](#how-to-method-settings-callers-console) + [ ## Configurar una respuesta de método de API Gateway en la consola de API Gateway ](#how-to-method-response-settings-console) ## Edición de una solicitud de método de API Gateway en la consola de API Gateway Estas instrucciones presuponen que ya ha creado la solicitud de método. Para obtener más información sobre cómo crear un método, consulte [Configuración de una solicitud de integración de la API mediante la consola de API Gateway](how-to-method-settings-console.md). 1. En el panel **Recursos**, elija el método y, a continuación, elija la pestaña **Solicitud de método**. 1. En la sección **Configuración de solicitud de método**, elija **Editar**. 1. En **Autorización**, seleccione un autorizador disponible. 1. Para habilitar el acceso abierto al método a cualquier usuario, elija **Ninguno**. Este paso se puede omitir si el ajuste predeterminado no se ha cambiado. 1. Para utilizar permisos de IAM para controlar el acceso de clientes al método, seleccione `AWS_IAM`. Con esta opción, solo los usuarios de los roles de IAM con la política correcta de IAM asociada pueden llamar a este método. Para crear el rol de IAM, especifique una política de acceso con un formato como el siguiente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/" ] } ] } ``` ------ En esta política de acceso, `arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/` es el ARN del método. Puede encontrar el ARN del método mediante la selección del método en la página de **Recursos**. Para obtener más información acerca de cómo establecer los permisos de IAM, consulte [Control del acceso a una API de REST con permisos de IAM](permissions.md). Para crear un rol de IAM, puede adaptar las instrucciones del siguiente tutorial, [Creación de una función de Lambda para la integración de Lambda no de proxy](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda). 1. Para usar un autorizador de Lambda, seleccione un token o un autorizador de solicitudes. Cree un autorizador de Lambda para que esta opción se muestre en el menú desplegable. Para obtener más información sobre cómo crear un autorizador de Lambda, consulte [Uso de autorizadores Lambda de API Gateway](apigateway-use-lambda-authorizer.md). 1. Para utilizar un grupo de usuarios de Amazon Cognito, elija un grupo de usuarios disponible en **Cognito user pool authorizers (Autorizadores de grupos de usuarios de Cognito)**. Cree un grupo de usuarios en Amazon Cognito y un autorizador de grupo de usuarios de Amazon Cognito en API Gateway para que esta opción se muestre en el menú desplegable. Para obtener información sobre cómo crear un autorizador de grupo de usuarios de Amazon Cognito, consulte [Control del acceso a las API de REST con grupos de usuarios de Amazon Cognito como autorizador](apigateway-integrate-with-cognito.md). 1. Para especificar la validación de la solicitud, seleccione un valor en el menú desplegable **Validador de solicitudes**. Para desactivar la validación de solicitudes, seleccione **Ninguna**. Para obtener más información acerca de cada opción, consulte [Solicitud de la validación de las API de REST en API Gateway](api-gateway-method-request-validation.md). 1. Seleccione **Clave de API obligatoria** para que se requiera una clave de API. Cuando se habilita, las claves de API se utilizan en [planes de uso](api-gateway-api-usage-plans.md) para limitar el tráfico del cliente. 1. De forma opcional, para asignar un nombre de operación en un SDK de Java de esta API, generado por API Gateway, ingrese un nombre en **Nombre de operación**. Por ejemplo, para la solicitud de método de `GET /pets/{petId}`, el nombre de operación de SDK de Java correspondiente es por defecto `GetPetsPetId`. Este nombre se crea a partir del verbo HTTP del método (`GET`) y los nombres de variables de la ruta de recursos (`Pets` y `PetId`). Si establece el nombre de operación como `getPetById`, el nombre de operación de SDK pasa a ser `GetPetById`. 1. Para añadir un parámetro de cadena de consulta al método, haga lo siguiente: 1. Elija **Parámetros de cadenas de consulta de URL** y, a continuación, elija **Agregar cadena de consulta**. 1. En **Nombre**, escriba el nombre del parámetro de cadena de consulta. 1. Seleccione **Obligatorio** si el parámetro de cadena de consulta recién creado debe utilizarse para la validación de solicitudes. Para obtener más información sobre la validación de solicitud, consulte [Solicitud de la validación de las API de REST en API Gateway](api-gateway-method-request-validation.md). 1. Seleccione **Almacenamiento en caché** si el parámetro de cadena de consulta recién creado va a utilizarse como parte de una clave de almacenamiento en caché. Para obtener más información acerca del almacenamiento en caché, consulte [Usar parámetros de método o integración como claves de caché para indexar las respuestas almacenadas en caché](api-gateway-caching.md#enable-api-gateway-cache-keys). Para eliminar el parámetro de cadena de consulta, seleccione **Eliminar**. 1. Para añadir un parámetro de encabezado al método, haga lo siguiente: 1. Elija **Encabezados de solicitud HTTP** y, a continuación, elija **Agregar encabezado**. 1. En **Nombre**, ingrese el nombre del encabezado. 1. Seleccione **Obligatorio** si el encabezado recién creado debe utilizarse para la validación de solicitudes. Para obtener más información sobre la validación de solicitud, consulte [Solicitud de la validación de las API de REST en API Gateway](api-gateway-method-request-validation.md). 1. Seleccione **Almacenamiento en caché** si el encabezado recién creado va a utilizarse como parte de una clave de almacenamiento en caché. Para obtener más información acerca del almacenamiento en caché, consulte [Usar parámetros de método o integración como claves de caché para indexar las respuestas almacenadas en caché](api-gateway-caching.md#enable-api-gateway-cache-keys). Para eliminar el encabezado, elija **Eliminar**. 1. Para declarar el formato de carga de una solicitud de método con el verbo HTTP `POST`, `PUT` o `PATCH`, elija **Cuerpo de la solicitud** y realice lo siguiente: 1. Elija **Add model (Añadir modelo)**. 1. En **Content-type**, escriba un tipo de MIME (por ejemplo, `application/json`). 1. En **Modelo**, seleccione un modelo en el menú desplegable. Los modelos disponibles actualmente para la API incluyen los modelos predeterminados `Empty` y `Error`, así como cualquier modelo que haya creado y agregado a la colección [Models](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) de la API. Para obtener más información acerca de la creación de un modelo, consulte [Modelos de datos para las API de REST](models-mappings-models.md). **nota** El modelo es útil para informar al cliente del formato de datos esperado de una carga. Resulta útil para generar una plantilla de asignación de esqueleto. Es importante para generar un SDK con establecimiento inflexible de tipos de la API en idiomas como Java, C \$1, Objective-C y Swift. Solo es necesario si se habilita la validación de solicitudes frente a la carga. 1. Seleccione **Save**. ## Configurar una respuesta de método de API Gateway en la consola de API Gateway Un método de API puede tener una o más respuestas. Cada respuesta se indexa mediante su código de estado HTTP. De forma predeterminada, la consola de API Gateway agrega la respuesta `200` a las respuestas de método. Puede modificarla, por ejemplo, para que el método devuelva `201` en su lugar. Puede añadir otras respuestas, por ejemplo, `409` para la denegación de acceso y `500` para las variables de etapa sin inicializar utilizadas. Para utilizar la consola de API Gateway para modificar, eliminar o agregar una respuesta a un método de API, siga estas instrucciones. 1. En el panel de **Recursos**, elija el método y, a continuación, elija la pestaña **Respuesta de método**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña. 1. En la sección **Configuración de respuesta del método**, elija **Crear respuesta**. 1. Para **Código de estado HTTP**, ingrese un código de estado HTTP como `200`, `400` o `500`. Si una respuesta devuelta del backend no tiene una respuesta de método correspondiente definida, API Gateway no puede devolver la respuesta al cliente. En su lugar, devuelve una respuesta de error `500 Internal server error`. 1. Elija **Agregar encabezado**. 1. En **Nombre del encabezado**, escriba un nombre. Para devolver un encabezado del backend al cliente, agregue el encabezado en la respuesta del método. 1. Elija **Agregar modelo** para definir un formato del cuerpo de la respuesta del método. Ingrese el tipo de medio de la carga de respuesta de **Tipo de contenido** y elija un modelo en el menú desplegable **Modelos**. 1. Seleccione **Save**. Para modificar una respuesta existente, navegue hasta la respuesta de su método y, a continuación, elija **Editar**. Para cambiar el **Código de estado HTTP**, elija **Eliminar** y cree una nueva respuesta de método. Para cada respuesta que devuelve el backend, debe tener una respuesta compatible configurada como respuesta de método. Sin embargo, los encabezados de respuesta de método de configuración y el modelo de carga son opcionales, a menos que asigne el resultado del backend a la respuesta de método antes de volver al cliente. Además, un modelo de carga de respuesta de método es importante si está generando un SDK con establecimiento inflexible de tipos para su API. # Control y administración del acceso a las API de REST en API Gateway API Gateway admite varios mecanismos para controlar y administrar el acceso a la API. Puede utilizar os siguientes mecanismos para realizar la autenticación y autorización: + Gracias a las **políticas de recursos**, puede crear políticas basadas en recursos para permitir o denegar el acceso a sus API y métodos desde determinadas direcciones IP de origen o determinados puntos de enlace de la VPC. Para obtener más información, consulte [Control del acceso a una API de REST con políticas de recursos de API Gateway](apigateway-resource-policies.md). + **Los roles y las políticas estándar de AWS IAM** ofrecen controles de acceso flexibles y robustos que se pueden aplicar a toda una API o a métodos individuales. Puede usar roles y políticas de IAM para controlar quién puede crear y administrar sus API, así como quién puede invocarlas. Para obtener más información, consulte [Control del acceso a una API de REST con permisos de IAM](permissions.md). + Las **etiquetas de IAM** se pueden utilizar con políticas de IAM para controlar el acceso. Para obtener más información, consulte [Uso de etiquetas para controlar el acceso a los recursos API de REST de API Gateway](apigateway-tagging-iam-policy.md). + Las **políticas de punto de enlace para los puntos de enlace de la VPC de interfaz** le permiten asociar las políticas de recursos de IAM a puntos de enlace de interfaz de la VPC para mejorar la seguridad de sus [API privadas](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html). Para obtener más información, consulte [Uso de políticas de punto de conexión de VPC para API privadas en API Gateway](apigateway-vpc-endpoint-policies.md). + Los **autorizadores Lambda** son funciones de Lambda que controlan el acceso a los métodos de la API REST utilizando la autenticación de token al portador, así como la información descrita por los encabezados, rutas, cadenas de consulta, variables de etapa o parámetros de solicitud de variables contextuales. Los autorizadores Lambda se utilizan para controlar quién puede invocar los métodos REST API. Para obtener más información, consulte [Uso de autorizadores Lambda de API Gateway](apigateway-use-lambda-authorizer.md). + Los **grupos de usuarios de Amazon Cognito** permiten crear soluciones personalizables de autenticación y autorización para las API REST. Los grupos de usuarios de Amazon Cognito se utilizan para controlar quién puede invocar los métodos de la API REST. Para obtener más información, consulte [Control del acceso a las API de REST con grupos de usuarios de Amazon Cognito como autorizador](apigateway-integrate-with-cognito.md). Puede utilizar los siguientes mecanismos para realizar otras tareas relacionadas con el control de acceso: + El **uso compartido de recursos entre orígenes (CORS)** permite controlar la forma en que la API REST responde a las solicitudes de recursos entre dominios. Para obtener más información, consulte [CORS para las API de REST en API Gateway](how-to-cors.md). + Los **certificados SSL del lado del cliente** pueden utilizarse para verificar que las solicitudes HTTP dirigidas a su sistema backend proceden de API Gateway. Para obtener más información, consulte [Generación y configuración de un certificado SSL para la autenticación de backend en API Gateway](getting-started-client-side-ssl-authentication.md). + **AWS WAF** se puede utilizar para proteger la API de API Gateway frente a ataques web comunes. Para obtener más información, consulte [Uso de AWS WAF para proteger sus API de REST en API Gateway](apigateway-control-access-aws-waf.md). Puede utilizar los siguientes mecanismos para rastrear y limitar el acceso concedido a los clientes autorizados: + Los **planes de uso** permiten proporcionar **claves de API** a sus clientes y, después, realizar un seguimiento y limitar el uso de etapas y métodos de API para cada clave de API. Para obtener más información, consulte [Planes de uso y clave de API para las API de REST en API Gateway](api-gateway-api-usage-plans.md). # Control del acceso a una API de REST con políticas de recursos de API Gateway Las *políticas de recursos* de Amazon API Gateway son documentos de política JSON que se asocian a una API para controlar si una entidad principal especificada (por lo general, un rol o un grupo de IAM) puede invocar la API. Puede utilizar las políticas de recursos de API Gateway para permitir la invocación segura de la API por parte de: + Los usuarios de una cuenta de AWS especificada. + Los intervalos de direcciones IP o bloques de CIDR especificados. + Las nubes privadas virtuales (VPC) o los puntos de conexión de VPC (de cualquier cuenta) especificados. Puede asociar una política de recursos para cualquier tipo de punto de conexión de la API en API Gateway mediante la Consola de administración de AWS, la CLI de AWS o los AWS SDK. Para [API privadas](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html), puede utilizar las políticas de recursos junto con las políticas de punto de conexión de VPC para controlar qué entidades principales tienen acceso a qué recursos y acciones. Para obtener más información, consulte [Uso de políticas de punto de conexión de VPC para API privadas en API Gateway](apigateway-vpc-endpoint-policies.md). Las políticas de recursos de API Gateway son diferentes de las políticas basadas en entidades de IAM. Las políticas basadas en identidades de IAM se asocian a usuarios, grupos o roles de IAM y definen qué acciones pueden realizar esas identidades y en qué recursos. Las políticas de recursos de API Gateway están asociadas a recursos. Puede utilizar las políticas de recursos de API Gateway junto con las políticas de IAM. Para obtener más información, consulte [Políticas basadas en identidad y políticas basadas en recursos](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html). **Topics** + [ # Información general del lenguaje de políticas de acceso para Amazon API Gateway ](apigateway-control-access-policy-language-overview.md) + [ # Cómo afectan las políticas de recursos de API Gateway al flujo de trabajo de autorización ](apigateway-authorization-flow.md) + [ # Ejemplos de políticas de recursos de API Gateway ](apigateway-resource-policies-examples.md) + [ # Creación y asociación de una política de recursos de API Gateway a una API ](apigateway-resource-policies-create-attach.md) + [ # AWSClaves de condición de que se pueden utilizar en las políticas de recursos de API Gateway ](apigateway-resource-policies-aws-condition-keys.md) # Información general del lenguaje de políticas de acceso para Amazon API Gateway Esta página describe los elementos básicos utilizados en las políticas de recursos de Amazon API Gateway. Las políticas de recursos se especifican utilizando la misma sintaxis que para las políticas de IAM. Para obtener información completa acerca del lenguaje de políticas, consulte [Información general de políticas de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) y [Referencia de políticas de AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) en la *Guía del usuario de IAM*. Para obtener información sobre cómo decide un servicio de AWS si se permite o se deniega una solicitud determinada, consulte [Determinar si se permite o deniega una solicitud](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#policy-eval-denyallow). ## Elementos comunes en una política de acceso Una política de recursos contiene los siguientes elementos básicos: + **Recursos**: las API son los recursos de Amazon API Gateway para los que puede conceder o denegar permisos. En una política, se usa el nombre de recurso de Amazon (ARN) para identificar el recurso. También puede utilizar sintaxis abreviada, que API Gateway expande automáticamente al ARN completo al guardar una política de recursos. Para obtener más información, consulte [Ejemplos de políticas de recursos de API Gateway](apigateway-resource-policies-examples.md). Para conocer el formato del elemento `Resource` completo, consulte [Formato de Resource de permisos para ejecutar la API en API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-iam-policy-resource-format-for-executing-api). + **Acciones**: para cada recurso, Amazon API Gateway admite un conjunto de operaciones. Con las palabras clave de acción puede identificar las operaciones del recurso que desea permitir o denegar. Por ejemplo, el permiso `execute-api:Invoke` autorizará al usuario a invocar una API previa solicitud del cliente. Para conocer el formato del elemento `Action`, consulte [Formato de Action de permisos para ejecutar la API en API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-iam-policy-action-format-for-executing-api). + **Efecto**: el efecto que se obtendrá cuando el usuario solicite la acción específica. Puede ser `Allow` o `Deny`. También puede denegar de forma explícita el acceso a un recurso para asegurarse de que un usuario no obtenga acceso a él, aunque otra política se lo conceda. **nota** "Denegar de forma implícita" es lo mismo que "denegar de forma predeterminada". Una "negación implícita" es diferente de una "negación explícita". Para obtener más información, consulte [Diferencia entre denegar de forma predeterminada y la denegación explícita](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#AccessPolicyLanguage_Interplay). + **Principal** (Entidad principal): la cuenta o el usuario con permiso de acceso a las acciones y los recursos en la instrucción. En una política de recursos, la entidad principal es el usuario o la cuenta que recibe este permiso. La política de recursos del ejemplo siguiente muestra los elementos comunes de política anteriores. La política concede acceso a la API bajo el *account-id* especificado en la *región* especificada a cualquier usuario cuya dirección IP de origen está en el bloque de direcciones *123.4.5.6/24*. La política deniega todo el acceso a la API si la IP de origen del usuario no está dentro del rango. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-east-1:111111111111:*" }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-east-1:111111111111:*", "Condition": { "NotIpAddress": { "aws:SourceIp": "123.4.5.6/24" } } } ] } ``` ------ # Cómo afectan las políticas de recursos de API Gateway al flujo de trabajo de autorización Cuando API Gateway evalúa la política de recursos asociada a la API, el resultado depende del tipo de autenticación que se haya definido para la API, tal y como se muestra en los diagramas de flujo de las siguientes secciones. **Topics** + [ ## Solo política de recursos de API Gateway ](#apigateway-authorization-flow-resource-policy-only) + [ ## Autorizador de Lambda y política de recursos ](#apigateway-authorization-flow-lambda) + [ ## Autenticación de IAM y política de recursos ](#apigateway-authorization-flow-iam) + [ ## Política de recursos y autenticación de Amazon Cognito ](#apigateway-authorization-flow-cognito) + [ ## Tablas de resultados de evaluación de políticas ](#apigateway-resource-policies-iam-policies-interaction) ## Solo política de recursos de API Gateway En este flujo de trabajo, una política de recursos de API Gateway está asociada a la API, pero no se ha definido ningún tipo de autenticación para la API. Para evaluar la política ay que buscar un permiso explícito en función de los criterios de entrada del intermediario. Una denegación implícita o cualquier denegación explícita provoca la denegación del intermediario. ![\[Solo flujo de autorización de una política de recursos.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/apigateway-auth-resource-policy-only.png) El siguiente ejemplo muestra dicha política. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-east-1:111111111111:api-id/", "Condition": { "IpAddress": { "aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ] } } } ] } ``` ------ ## Autorizador de Lambda y política de recursos En este flujo de trabajo, un autorizador de Lambda está configurado para la API, además de una política de recursos. La política de recursos se evalúan en dos fases. Antes de llamar al autorizador de Lambda, API Gateway primero evalúa la política y comprueba si hay denegaciones explícitas. Si se encuentran, se deniega inmediatamente el acceso al intermediario. De lo contrario, se llamada al autorizador de Lambda, que devuelve un [documento de política](api-gateway-lambda-authorizer-output.md), que se evalúa junto con la política de recursos. Si el autorizador utiliza el almacenamiento en caché, es posible que API Gateway devuelva el documento de política almacenado en caché. El resultado se determina en función de la [Tabla A](#apigateway-resource-policies-iam-policies-interaction). La siguiente política de recursos de ejemplo solo permite llamadas desde el punto de enlace de la VPC cuyo ID de punto de enlace de la VPC sea `vpce-1a2b3c4d`. Durante la evaluación "previa a la autenticación"·, solo se permiten las llamadas procedentes del punto de enlace de la VPC que se indican l el ejemplo para seguir adelante y evaluar el autorizador de Lambda. Todas las llamadas restantes se bloquean. Este flujo de trabajo de autorización es el mismo si utiliza un nombre de dominio personalizado para una API privada. ![\[Flujo de autorización para una política de recursos y un autorizador de Lambda.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/apigateway-auth-lambda-resource-policy.png) ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-1a2b3c4d" } } } ] } ``` ------ ## Autenticación de IAM y política de recursos En este flujo de trabajo, puede configurar la autenticación de IAM para la API, además de una política de recursos. Después de autenticar al usuario con el servicio de IAM, la API evalúa las políticas asociadas al usuario y a la política de recursos. El resultado varía en función de si el intermediario se encuentra en la misma Cuenta de AWS o una Cuenta de AWS diferente, del propietario de la API. Si el intermediario y el propietario de la API proceden de cuentas distintas, las políticas de IAM y la política de recursos permiten explícitamente al intermediario continuar. Para obtener más información, consulte la [Tabla B](#apigateway-resource-policies-iam-policies-interaction). Sin embargo, si el intermediario y el propietario de la API se encuentran en la misma Cuenta de AWS, las políticas del usuario de IAM o la política de recursos deben permitir explícitamente al intermediario continuar. Para obtener más información, consulte la [Tabla A](#apigateway-resource-policies-iam-policies-interaction). ![\[Flujo de autorización para una política de recursos y una autenticación de IAM.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/apigateway-auth-iam-resource-policy.png) El siguiente ejemplo muestra una política de recursos entre cuentas. Si presuponemos que la política de IAM contiene un efecto Allow (Permitir), esta política de recursos solo permite llamadas desde la VPC cuyo ID de VPC sea `vpc-2f09a348`. Para obtener más información, consulte la [Tabla B](#apigateway-resource-policies-iam-policies-interaction). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/" ], "Condition" : { "StringEquals": { "aws:SourceVpc": "vpc-2f09a348" } } } ] } ``` ------ ## Política de recursos y autenticación de Amazon Cognito En este flujo de trabajo, se configura un [grupo de usuarios de Amazon Cognito](apigateway-integrate-with-cognito.md) para la API, además de una política de recursos. API Gateway intenta primero autenticar a la persona que llama a través de Amazon Cognito. Esto se realiza normalmente a través de un [token JWT](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) proporcionado por la persona que llama. Si la autenticación se realiza correctamente, la política de recursos se evalúa de forma independiente, y se requiere un permiso explícito. Una denegación o "ni permitir ni denegar" da como resultado una denegación. El siguiente ejemplo muestra una política de recursos que podrían utilizarse junto con grupos de usuarios de Amazon Cognito. ![\[Flujo de autorización para una política de recursos y un autorizador de Amazon Cognito.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/apigateway-auth-cognito-resource-policy.png) El siguiente ejemplo muestra una política de recursos que solo permite llamadas desde direcciones IP de origen específicas, suponiendo que el token de autenticación de Amazon Cognito contiene un permiso. Para obtener más información, consulte la [Tabla B](#apigateway-resource-policies-iam-policies-interaction). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-east-1:111111111111:api-id/", "Condition": { "IpAddress": { "aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ] } } } ] } ``` ------ ## Tablas de resultados de evaluación de políticas La tabla A muestra el comportamiento resultante cuando el acceso a una API de API Gateway está controlado por una política de IAM o un autorizador de Lambda y una política de recursos de API Gateway, que se encuentran en la misma Cuenta de AWS. | **Política de IAM (o autorizador de Lambda)** | **Política de recursos de API Gateway** | **Comportamiento resultante** | | --- | --- | --- | | Allow | Allow | Allow | | Allow | Ni permitir ni denegar | Allow | | Allow | Denegar | Denegación explícita | | Ni permitir ni denegar | Allow | Allow | | Ni permitir ni denegar | Ni permitir ni denegar | Denegar de forma implícita | | Ni permitir ni denegar | Denegar | Denegación explícita | | Denegar | Allow | Denegación explícita | | Denegar | Ni permitir ni denegar | Denegación explícita | | Denegar | Denegar | Denegación explícita | La tabla B muestra el comportamiento resultante cuando el acceso a una API de API Gateway está controlado por una política de IAM o un autorizador de grupos de usuarios de Amazon Cognito y una política de recursos de API Gateway, que se encuentran en diferentes Cuentas de AWS. Si no existe un permiso ni una denegación, el acceso entre cuentas se deniega. Esto se debe a que el acceso entre cuentas requiere que la política de recursos y la política de IAM o el autorizador de grupos de usuarios de Amazon Cognito concedan acceso de forma explícita. | **Política de IAM (o autorizador de grupos de usuarios de Amazon Cognito)** | **Política de recursos de API Gateway** | **Comportamiento resultante** | | --- | --- | --- | | Allow | Allow | Allow | | Allow | Ni permitir ni denegar | Denegar de forma implícita | | Allow | Denegar | Denegación explícita | | Ni permitir ni denegar | Allow | Denegar de forma implícita | | Ni permitir ni denegar | Ni permitir ni denegar | Denegar de forma implícita | | Ni permitir ni denegar | Denegar | Denegación explícita | | Denegar | Allow | Denegación explícita | | Denegar | Ni permitir ni denegar | Denegación explícita | | Denegar | Denegar | Denegación explícita | # Ejemplos de políticas de recursos de API Gateway En esta página se presentan algunos ejemplos de casos de uso típicos de políticas de recursos de API Gateway. Las políticas de ejemplo siguientes utilizan una sintaxis simplificada para especificar el recurso de API. Esta sintaxis simplificada es una forma abreviada de hacer referencia a un recurso de API, en lugar de especificar el nombre de recursos de Amazon (ARN) completo. API Gateway convierte la sintaxis abreviada en el ARN completo al guardar la política. Por ejemplo, puede especificar el recurso `execute-api:/stage-name/GET/pets` en una política de recursos. API Gateway convierte el recurso en `arn:aws:execute-api:us-east-2:123456789012:aabbccddee/stage-name/GET/pets` cuando se guarda la política de recursos. API Gateway crea el ARN completo utilizando la región actual, el ID de su cuenta de AWS y el ID de la API REST con la que está asociada la política de recursos. Puede utilizar `execute-api:/*` para representar todas las etapas, métodos y rutas de la API actual. Para obtener información acerca del lenguaje de la política de acceso, consulte [Información general del lenguaje de políticas de acceso para Amazon API Gateway](apigateway-control-access-policy-language-overview.md). **Topics** + [ ## Ejemplo: permitir que los roles de otra cuenta de AWS utilicen una API ](#apigateway-resource-policies-cross-account-example) + [ ## Ejemplo: Cómo denegar el tráfico a una API para una dirección o un rango de direcciones IP de origen ](#apigateway-resource-policies-source-ip-address-example) + [ ## Ejemplo: Denegar el tráfico de API basado en la dirección IP de origen o rango cuando se utiliza una API privada ](#apigateway-resource-policies-source-ip-address-vpc-example) + [ ## Ejemplo: Permitir el tráfico de una API privada en función del punto de conexión de VPC o la VPC de origen ](#apigateway-resource-policies-source-vpc-example) ## Ejemplo: permitir que los roles de otra cuenta de AWS utilicen una API En la siguiente política de recursos de ejemplo, se otorga acceso a la API de una cuenta de AWS a dos roles de una cuenta de AWS diferente a través de los protocolos [Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html) (SigV4) o [Signature Version 4a](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html#how-sigv4a-works) (SigV4a). En concreto, se concede al rol de desarrollador y administrador de la cuenta de AWS identificados por `account-id-2` la acción `execute-api:Invoke` para ejecutar la acción `GET` en el recurso `pets` (API) en la cuenta de AWS. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:role/developer", "arn:aws:iam::111122223333:role/Admin" ] }, "Action": "execute-api:Invoke", "Resource": [ "execute-api:/stage/GET/pets" ] } ] } ``` ------ ## Ejemplo: Cómo denegar el tráfico a una API para una dirección o un rango de direcciones IP de origen El siguiente ejemplo de política de recursos deniega (bloquea) el tráfico entrante a una API privada procedente de dos bloques de direcciones IP de origen especificadas. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "IpAddress": { "aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ] } } } ] } ``` ------ Si utiliza políticas de usuario de IAM o políticas de recursos de API Gateway para controlar el acceso a API Gateway o a cualquier API de API Gateway, confirme que las políticas estén actualizadas para incluir los rangos de direcciones IPv6. Las políticas que no se actualizan para gestionar las direcciones IPv6 pueden afectar al acceso del cliente a API Gateway cuando comiencen a utilizar el punto de conexión de pila doble. Para obtener más información, consulte [Uso de direcciones IPv6 en políticas de IAM](api-ref.md#api-reference-service-endpoints-dualstack-iam). ## Ejemplo: Denegar el tráfico de API basado en la dirección IP de origen o rango cuando se utiliza una API privada El siguiente ejemplo de política de recursos deniega (bloquea) el tráfico entrante a una API privada procedente de dos bloques de direcciones IP de origen especificadas. Cuando se utilizan API privadas, el punto de conexión final de VPC para `execute-api` vuelve a escribir la dirección IP de origen original. La condición `aws:VpcSourceIp` filtra la solicitud contra la dirección IP del solicitante original. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "IpAddress": { "aws:VpcSourceIp": ["192.0.2.0/24", "198.51.100.0/24"] } } } ] } ``` ------ ## Ejemplo: Permitir el tráfico de una API privada en función del punto de conexión de VPC o la VPC de origen En el ejemplo siguiente, las políticas de recursos permiten el tráfico entrante en una API privada solo desde una nube virtual privada (VPC) o un punto de conexión de VPC especificados. Esta política de recursos de ejemplo especifica una VPC de origen: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpc": "vpc-1a2b3c4d" } } } ] } ``` ------ Esta política de recursos de ejemplo especifica un punto de conexión de VPC de origen: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-1a2b3c4d" } } } ] } ``` ------ # Creación y asociación de una política de recursos de API Gateway a una API Para permitir a un usuario acceder a la API llamando al servicio de ejecución de la API, debe crear una política de recursos de API Gateway y asociar la política a la API. Al asociar una política a la API, se aplican los permisos de la política a los métodos de la API. Si actualiza la política de recursos, tendrá que implementar la API. **Topics** + [ ## Requisitos previos ](#apigateway-resource-policies-prerequisites) + [ ## Asociación de una política de recursos a una API de API Gateway ](#apigateway-resource-policies-create-attach-procedure) + [ ## Solución de problemas de política de recursos ](#apigateway-resource-policies-troubleshoot) ## Requisitos previos Para actualizar una política de recursos de API Gateway, necesitará el permiso `apigateway:UpdateRestApiPolicy` y el permiso `apigateway:PATCH`. Para una API regional u optimizada para sistemas perimetrales, puede adjuntar la política de recursos a la API a medida que la crea o después de implementarla. Para una API privada, no puede implementar la API sin una política de recursos. Para obtener más información, consulte [API de REST privadas en API Gateway](apigateway-private-apis.md). ## Asociación de una política de recursos a una API de API Gateway El siguiente procedimiento muestra cómo asociar una política de recursos a una API de API Gateway. ------ #### [ Consola de administración de AWS ] **Para asociar una política de recursos a una API de API Gateway** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. En el panel de navegación principal, elija **Política de recursos**. 1. Elija **Crear política**. 1. (Opcional) Elija **Seleccionar una plantilla** para generar una política de ejemplo. En las políticas de ejemplo, los marcadores de posición se indican mediante llaves (`"{{placeholder}}"`). Sustituya cada uno de los marcadores de posición, incluidas las llaves, por la información necesaria. 1. Si no utiliza uno de los ejemplos de plantilla, ingrese la política de recursos. 1. Seleccione **Save changes (Guardar cambios)**. Si la API se ha implementado anteriormente en la consola de API Gateway, tendrá que volver a implementarla para que la política de recursos surta efecto. ------ #### [ AWS CLI ] Para usar la AWS CLI para crear una nueva API y asociarla a una política de recursos, use el siguiente comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html): ``` aws apigateway create-rest-api \ --name "api-name" \ --policy "{\"jsonEscapedPolicyDocument\"}" ``` Para usar la AWS CLI para asociar una política de recursos a una API existente, use el siguiente comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html): ``` aws apigateway update-rest-api \ --rest-api-id api-id \ --patch-operations op=replace,path=/policy,value='"{\"jsonEscapedPolicyDocument\"}"' ``` También puede adjuntar la política de recursos como archivo `policy.json` independiente e incluirla en el comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html). El siguiente comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) crea una nueva API con una política de recursos: ``` aws apigateway create-rest-api \ --name "api-name" \ --policy file://policy.json ``` El archivo `policy.json` es una política de recursos de API Gateway, como [Ejemplo: Cómo denegar el tráfico a una API para una dirección o un rango de direcciones IP de origen](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example). ------ #### [ AWS CloudFormation ] Puede utilizar CloudFormation para crear una API con una política de recursos. En el siguiente ejemplo, se crea una API de REST con la política de recursos de ejemplo, [Ejemplo: Cómo denegar el tráfico a una API para una dirección o un rango de direcciones IP de origen](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example). ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: testapi Policy: Statement: - Action: 'execute-api:Invoke' Effect: Allow Principal: '*' Resource: 'execute-api:/*' - Action: 'execute-api:Invoke' Effect: Deny Principal: '*' Resource: 'execute-api:/*' Condition: IpAddress: 'aws:SourceIp': ["192.0.2.0/24", "198.51.100.0/24" ] Version: 2012-10-17 Resource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'helloworld' MethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref Resource HttpMethod: GET ApiKeyRequired: false AuthorizationType: NONE Integration: Type: MOCK RequestTemplates: application/json: '{"statusCode": 200}' IntegrationResponses: - StatusCode: 200 ResponseTemplates: application/json: '{}' MethodResponses: - StatusCode: 200 ResponseModels: application/json: 'Empty' ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - MethodGet Properties: RestApiId: !Ref Api StageName: test ``` ------ ## Solución de problemas de política de recursos La siguiente guía de solución de problemas puede ayudar a resolver los problemas relacionados con la política de recursos. ### Mi API devuelve \$1"Mensaje": El usuario: anónimo no está autorizado a realizar: execute-api:Invoke en resource: arn:aws:execute-api:us-east-1:\$1\$1\$1\$1\$1\$1\$1\$1/\$1\$1\$1\$1/\$1\$1\$1\$1/"\$1 En la política de recursos, si establece la entidad principal en una entidad principal de AWS, por ejemplo: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111111111111:role/developer", "arn:aws:iam::111111111111:role/Admin" ] }, "Action": "execute-api:Invoke", "Resource": [ "execute-api:/stage/GET/pets" ] } ] } ``` ------ Debe usar la autorización de `AWS_IAM` para todos los métodos de la API o, de lo contrario, la API devolverá el mensaje de error anterior. Para obtener más instrucciones sobre cómo activar la autorización de `AWS_IAM` para un método, consulte [Métodos de API de REST en API Gateway](how-to-method-settings.md). ### Mi política de recursos no se actualiza Si actualiza la política de recursos después de crear la API, tendrá que implementar la API para propagar los cambios después de asociar la política actualizada. Si únicamente se actualiza o se guarda la política, no se modifica el comportamiento en tiempo de ejecución de la API. Para obtener más información acerca cómo implementar una API, consulte [Implementación de las API de REST en API Gateway](how-to-deploy-api.md). ### Mi política de recursos devuelve el siguiente error: Documento de política no válido. Compruebe la sintaxis de la política y asegúrese de que las entidades principales sean válidas. Para solucionar este error, primero le recomendamos que compruebe la sintaxis de la política. Para obtener más información, consulte [Información general del lenguaje de políticas de acceso para Amazon API Gateway](apigateway-control-access-policy-language-overview.md). También le recomendamos que compruebe que todas las entidades principales especificadas sean válidas y que no se hayan eliminado. Además, si la API se encuentra en una [región de suscripción](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html?icmpid=docs_homepage_addtlrcs#optinregion), compruebe que todas las cuentas de la política de recursos tengan la región habilitada. # AWSClaves de condición de que se pueden utilizar en las políticas de recursos de API Gateway La siguiente tabla contiene las claves de condición de AWS que se pueden utilizar en las políticas de recursos de las API de API Gateway con cada tipo de autorización. Para obtener más información acerca de las claves de condición de AWS, consulte [Claves de contexto de condición global de AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html). | **Claves de condición** | **Criterios** | **Necesita `AuthN`?** | **Tipo de autorización** | | --- | --- | --- | --- | | aws:CurrentTime | Ninguno | No | Todos | | aws:EpochTime | Ninguno | No | Todos | | aws:TokenIssueTime | La clave solo está en las solicitudes que se firman con credenciales de seguridad temporales. | Sí | IAM | | aws:MultiFactorAuthPresent | La clave solo está en las solicitudes que se firman con credenciales de seguridad temporales. | Sí | IAM | | aws:MultiFactorAuthAge | La clave solo está si se utiliza la MFA en las solicitudes. | Sí | IAM | | aws:PrincipalAccount | Ninguno | Sí | IAM | | aws:PrincipalArn | Ninguno | Sí | IAM | | aws:PrincipalOrgID | Esta clave solamente se incluye en el contexto de la solicitud si la entidad principal es miembro de una organización. | Sí | IAM | | aws:PrincipalOrgPaths | Esta clave solamente se incluye en el contexto de la solicitud si la entidad principal es miembro de una organización. | Sí | IAM | | aws:PrincipalTag | Esta clave solamente se incluye en el contexto de la solicitud si la entidad principal está usando un usuario de IAM con etiquetas asociadas. Se incluye para una entidad principal que utiliza un rol de IAM con etiquetas o etiquetas de sesión asociadas. | Sí | IAM | | aws:PrincipalType | Ninguno | Sí | IAM | | aws:Referer | La clave solo está si el valor lo proporciona el intermediario en el encabezado HTTP. | No | Todos | | aws:SecureTransport | Ninguno | No | Todos | | aws:SourceArn | Ninguno | No | Todos | | aws:SourceIp | Ninguno | No | Todos | | aws:SourceVpc | Esta clave solo se puede utilizar con las API privadas. | No | Todos | | aws:SourceVpce | Esta clave solo se puede utilizar con las API privadas. | No | Todos | | aws:VpcSourceIp | Esta clave solo se puede utilizar con las API privadas. | No | Todos | | aws:UserAgent | La clave solo está si el valor lo proporciona el intermediario en el encabezado HTTP. | No | Todos | | aws:userid | Ninguno | Sí | IAM | | aws:username | Ninguno | Sí | IAM | # Control del acceso a una API de REST con permisos de IAM Puede controlar el acceso a su API de Amazon API Gateway con [permisos de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html) controlando el acceso a los dos procesos de componentes de API Gateway siguientes: + Para crear, implementar y administrar una API en API Gateway, debe conceder al desarrollador de la API permisos para realizar las acciones necesarias admitidas por el componente de administración de la API de API Gateway. + Para llamar a una API implementada o para actualizar el almacenamiento en caché de la API, debe conceder al intermediario de la API permisos para realizar las acciones de IAM necesarias admitidas por el componente de ejecución de la API de API Gateway. El control de acceso para los dos procesos implica diferentes modelos de permisos, que se explican a continuación. ## Modelo de permisos de API Gateway para crear y administrar una API Para permitir a un desarrollador de API crear y administrar una API en API Gateway debe [crear políticas de permisos de IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) que permitan a un desarrollador de la API especificado crear, actualizar, implementar, ver o eliminar las [entidades de API](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) necesarias. Al asociar la política de permisos a un usuario, rol o grupo. Para dar acceso, agregue permisos a los usuarios, grupos o roles: + Usuarios y grupos en AWS IAM Identity Center: Cree un conjunto de permisos. Siga las instrucciones de [Creación de un conjunto de permisos](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) en la *Guía del usuario de AWS IAM Identity Center*. + Usuarios gestionados en IAM a través de un proveedor de identidades: Cree un rol para la federación de identidades. Siga las instrucciones descritas en [Creación de un rol para un proveedor de identidad de terceros (federación)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) en la *Guía del usuario de IAM*. + Usuarios de IAM: + Cree un rol que el usuario pueda aceptar. Siga las instrucciones descritas en [Creación de un rol para un usuario de IAM](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) en la *Guía del usuario de IAM*. + (No recomendado) Adjunte una política directamente a un usuario o agregue un usuario a un grupo de usuarios. Siga las instrucciones descritas en [Adición de permisos a un usuario (consola)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) de la *Guía del usuario de IAM*. Para obtener más información sobre cómo usar este modelo de permisos, consulte [Políticas basadas en identidades de API Gateway](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies). ## Modelo de permisos de API Gateway para invocar una API Para permitir a un intermediario de la API invocar la API o actualizar su caché, debe crear políticas de IAM que permitan a un intermediario de la API especificado invocar el método de API para el que se ha habilitado la autenticación de usuarios. El desarrollador de la API establece la propiedad `authorizationType` del método en `AWS_IAM` para exigir que el intermediario envíe las credenciales del usuario que se va a autenticar. API Gateway admite Signature Version 4a (SigV4a) y Signature Version 4 (SigV4) para autenticar las credenciales del usuario. Para obtener más información, consulte [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). A continuación, adjunte la política a un usuario, rol o grupo. En esta instrucción de política de permisos de IAM, el elemento `Resource` de IAM contiene una lista de métodos de la API implementada identificados por verbos HTTP y [rutas de recursos](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) de API Gateway. El elemento `Action` de IAM contiene las acciones de ejecución de API de API Gateway necesarias. Estas acciones incluyen `execute-api:Invoke` o `execute-api:InvalidateCache`, donde `execute-api` designa el componente de ejecución de la API subyacente de API Gateway. Para obtener más información sobre cómo usar este modelo de permisos, consulte [Controlar el acceso para invocar una API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). Cuando una API está integrada con un servicio de AWS (por ejemplo, AWS Lambda) en el backend, API Gateway también debe tener permisos para obtener acceso a los recursos de AWS integrados (por ejemplo, invocar una función de Lambda) en nombre de la persona que llama a la API. Para otorgar estos permisos, cree un rol de IAM del tipo **servicio de AWS para API Gateway**. Cuando crea este rol en la consola de administración de IAM, este rol resultante contiene la siguiente política de confianza de IAM que designa a API Gateway como la entidad de confianza capaz de asumir el rol: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ Si crea el rol de IAM llamando al comando [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) de la CLI o a un método del SDK correspondiente, debe proporcionar la política de confianza anterior como el parámetro de entrada de `assume-role-policy-document`. No intente crear esta política directamente en la consola de administración de IAM ni llamando al comando de la AWS CLI [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) ni a un método del SDK correspondiente. Para que API Gateway llame al servicio de AWS integrado, también debe adjuntar a este rol las políticas de permisos de IAM correspondientes para llamar a los servicios de AWS integrados. Por ejemplo, para llamar a una función de Lambda, debe incluir la siguiente política de permisos de IAM en el rol de IAM: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "*" } ] } ``` ------ Tenga en cuenta que Lambda admite la política de acceso basada en recursos, que combina políticas de confianza y de permisos. Cuando integre una API con una función de Lambda mediante la consola de API Gateway, no se le pedirá que establezca este rol de IAM explícitamente, porque la consola establece los permisos basados en recursos en la función de Lambda por usted, con su consentimiento. **nota** Para establecer el control del acceso a un servicio de AWS, puede utilizar el modelo de permisos basado en el intermediario, donde una política de permisos se asocia directamente al usuario o grupo del intermediario, o el modelo de permisos basado en rol, donde una política de permisos se asocia a un rol de IAM que API Gateway puede asumir. Los permisos de políticas pueden ser diferentes en los dos modelos. Por ejemplo, la política basada en el intermediario bloquea el acceso, mientras que la política basada en roles lo permite. Puede aprovechar esto para exigir que un usuario tenga acceso a un servicio de AWS solo a través de la API de API Gateway. # Controlar el acceso para invocar una API En esta sección, obtendrá información sobre el modelo de permisos para controlar el acceso a su API mediante permisos de IAM. Cuando la autorización de IAM está habilitada, los clientes deben utilizar Signature Version 4a (SigV4a) y Signature Version 4 (SigV4) para firmar las solicitudes con credenciales de AWS. Para obtener más información, consulte [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). En esta sección, mostramos una plantilla de declaración de política de IAM y la referencia de la declaración de política. La referencia de la declaración de política incluye los formatos de los campos `Action` y `Resource` relacionados con el servicio de ejecución de la API. Utilice estas referencias para crear su declaración de política de IAM. Cuando cree la declaración de política de IAM, es posible que deba tener en cuenta la forma en que las políticas de recursos de API Gateway afectan al flujo de trabajo de autorización. Para obtener más información, consulte [Cómo afectan las políticas de recursos de API Gateway al flujo de trabajo de autorización](apigateway-authorization-flow.md). Para API privadas, debe utilizar una combinación de una política de recursos de API Gateway y una política de punto de enlace de la VPC. Para obtener más información, consulte los siguientes temas: + [Control del acceso a una API de REST con políticas de recursos de API Gateway](apigateway-resource-policies.md) + [Uso de políticas de punto de conexión de VPC para API privadas en API Gateway](apigateway-vpc-endpoint-policies.md) ## Controlar quién puede llamar a una API de API Gateway con políticas de IAM Para controlar quién puede o no puede llamar a una API implementada con permisos de IAM, cree un documento de política de IAM con los permisos necesarios. A continuación, se muestra una plantilla para un documento de política como este. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Permission", "Action": [ "execute-api:Execution-operation" ], "Resource": [ "arn:aws:execute-api:region:123456789012:api-id/stage/METHOD_HTTP_VERB/Resource-path" ] } ] } ``` ------ Aquí, `Permission` se sustituirá por `Allow` o `Deny` dependiendo de si desea conceder o revocar los permisos incluidos. `Execution-operation` se sustituirá por las operaciones compatibles con el servicio de ejecución de la API. `METHOD_HTTP_VERB` hace referencia a un verbo HTTP compatible con los recursos especificados. `Resource-path` es el marcador de posición de la ruta URL de una instancia de `[Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)` de la API implementada que admite el `METHOD_HTTP_VERB` mencionado. Para obtener más información, consulte [Referencia de instrucciones de políticas de IAM para ejecutar la API en API Gateway](#api-gateway-calling-api-permissions). **nota** Para que las políticas de IAM sean eficaces, debe haber habilitado la autenticación de IAM en los métodos de API configurando `AWS_IAM` para la propiedad `[authorizationType](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType)` de los métodos. En caso contrario, estos métodos de API serán accesibles públicamente. Por ejemplo, para conceder a un usuario permiso para ver una lista de mascotas expuesta por una API determinada, pero denegarle permiso para agregar una mascota a la lista, se podría incluir la siguiente instrucción en la política de IAM: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/*/GET/pets" ] }, { "Effect": "Deny", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/*/POST/pets" ] } ] } ``` ------ Para conceder a un usuario permiso para ver una mascota específica expuesta por una API que se configura como `GET /pets/{petId}`, podría incluir la siguiente declaración en la política de IAM: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111122223333:api-id/*/GET/pets/a1b2" ] } ] } ``` ------ ## Referencia de instrucciones de políticas de IAM para ejecutar la API en API Gateway La siguiente información describe el formato de Action y Resource de las instrucciones de política de IAM de permisos de acceso para ejecutar una API. ### Formato de Action de permisos para ejecutar la API en API Gateway La expresión `Action` de ejecución de API tiene el siguiente formato general: ``` execute-api:action ``` donde *action* es una acción de ejecución de API disponible: + **\$1**, que representa todas las acciones siguientes. + **Invoke**, que se utiliza para invocar una API previa solicitud del cliente. + **InvalidateCache**, que se utiliza para invalidar la caché de API previa solicitud del cliente. ### Formato de Resource de permisos para ejecutar la API en API Gateway La expresión `Resource` de ejecución de API tiene el siguiente formato general: ``` arn:aws:execute-api:region:account-id:api-id/stage-name/HTTP-VERB/resource-path-specifier ``` donde: + *region* es la región de AWS (como **us-east-1** o **\$1** para todas las regiones de AWS) que se corresponde con la API implementada para el método. + *account-id* es el ID de cuenta de 12 dígitos de AWS del propietario de la API de REST. + *api-id* es el identificador que API Gateway asignó a la API para el método. + *stage-name* es el nombre de la etapa asociada al método. + *HTTP-VERB* es el verbo HTTP del método. Puede ser uno de las siguientes: GET, POST, PUT, DELETE, PATCH. + *resource-path-specifier* es la ruta al método deseado. **nota** Si especifica un comodín (`*`), la expresión `Resource` aplica el comodín al resto de la expresión. Algunos ejemplos de expresiones de recursos incluyen: + **arn:aws:execute-api:\$1:\$1:\$1** para cualquier ruta de recurso en cualquier etapa, para cualquier API de cualquier región de AWS. + **arn:aws:execute-api:us-east-1:\$1:\$1** para cualquier ruta de recurso en cualquier etapa, para cualquier API en la región de AWS `us-east-1`. + **arn:aws:execute-api:us-east-1:\$1:*api-id*/\$1** para cualquier ruta de recurso en cualquier etapa, para la API con el identificador *api-id* de la región de AWS us-east-1. + **arn:aws:execute-api:us-east-1:\$1:*api-id*/`test`/\$1** para cualquier ruta de recurso en la etapa de `test`, para la API con el identificador de *api-id* de la región de AWS us-east-1. Para obtener más información, consulte [Referencia del nombre de recurso de Amazon (ARN) de API Gateway](arn-format-reference.md). # Ejemplos de política de IAM para permisos de ejecución de la API Para ver el modelo de permisos y otra información de referencia, consulte [Controlar el acceso para invocar una API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). La siguiente instrucción de política otorga al usuario permiso para llamar a cualquier método POST en la ruta `mydemoresource`, en la etapa `test`, para la API con el identificador `a123456789`, suponiendo que la API correspondiente se ha implementado en la región de AWS us-east-1: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:*:a123456789/test/POST/my-demo-resource-path/*" ] } ] } ``` ------ La siguiente instrucción de política de ejemplo concede al usuario permiso para llamar a cualquier método en la ruta del recurso `petstorewalkthrough/pets`, en cualquier etapa, para la API con el identificador `a123456789`, en cualquier región de AWS en la que se haya implementado la API correspondiente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:*:*:a123456789/*/*/petstorewalkthrough/pets" ] } ] } ``` ------ # Uso de políticas de punto de conexión de VPC para API privadas en API Gateway Para mejorar la seguridad de la API privada, puede crear una política de punto de conexión de VPC. Una política de punto de conexión de VPC es una política de recursos de IAM que se adjunta a un punto de conexión de VPC. Para obtener más información, consulte [Control del acceso a los servicios con Puntos de conexión de VPC](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html). Es posible que desee crear una política de punto de conexión de VPC para realizar las siguientes tareas. + Permita que solo determinadas organizaciones o recursos accedan al punto de conexión de VPC e invoquen la API. + Use una sola política y evite las políticas basadas en sesiones o roles para controlar el tráfico a la API. + Refuerce el perímetro de seguridad de la aplicación al migrar de en las instalaciones a AWS. ## Consideraciones de la política del punto de conexión de VPC A continuación, se incluyen algunas consideraciones para la política de puntos de conexión de VPC: + La identidad del invocador se evalúa en función del valor `Authorization` del encabezado. Primero se evalúa la política de puntos de conexión de VPC y, a continuación, API Gateway evalúa la solicitud en función del tipo de autorización configurado en la solicitud del método. En la siguiente tabla se muestra cómo se evalúa la política de puntos de conexión de VPC en función del contenido del valor del encabezado `Authorization`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-vpc-endpoint-policies.html) + Si el control de acceso depende del uso de un token de portador, como un autorizador de Lambda o Amazon Cognito, puede controlar el perímetro de seguridad mediante las [propiedades del recurso](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-properties). + Si los controles de autorización utilizan la autorización de IAM, puede controlar el perímetro de seguridad mediante las [propiedades del recurso](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-properties) y las [propiedades de la entidad principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-principal). + Las políticas de punto de conexión de VPC se pueden utilizar junto con políticas de recursos de API Gateway. La política de recursos de API Gateway especifica qué entidades principales pueden acceder a la API. La política de puntos de conexión especifica quién puede acceder a la VPC y qué API se puede llamar desde el punto de conexión de VPC. La API privada necesita una política de recursos pero no necesita crear una política de punto de conexión de VPC personalizada. ## Ejemplos de políticas de puntos de conexión de VPC Puede crear políticas para los puntos de conexión de Amazon Virtual Private Cloud para Amazon API Gateway en las que puede especificar lo siguiente. + La entidad principal que puede realizar acciones. + Las acciones que se pueden realizar. + Los recursos en los que se pueden realizar acciones. Esto puede depender del contenido del encabezado de autorización. Para obtener más información, consulte [Consideraciones de la política del punto de conexión de VPC](#apigateway-vpc-endpoint-policies-considerations). Para obtener ejemplos de políticas adicionales, consulte [Data perimeter policy examples](https://github.com/aws-samples/data-perimeter-policy-examples) en el sitio web de GitHub. Para asociar la política al punto de conexión de VPC, tendrá que utilizar la consola de VPC. Para obtener más información, consulte [Control del acceso a los servicios con Puntos de conexión de VPC](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html). ## Ejemplo 1: Política de punto de conexión de VPC que otorga acceso a dos API El siguiente ejemplo de política otorga acceso solo a dos API específicas a través del punto de conexión de VPC al que está asociado la política. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Principal": "*", "Action": [ "execute-api:Invoke" ], "Effect": "Allow", "Resource": [ "arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*", "arn:aws:execute-api:us-east-1:123412341234:aaaaa11111/*" ] } ] } ``` ------ ## Ejemplo 2: Política de punto de conexión de VPC que otorga acceso a métodos GET El siguiente ejemplo de política otorga acceso a los usuarios a los métodos `GET` para una API específica a través del punto de conexión de VPC al que está asociada la política. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Principal": "*", "Action": [ "execute-api:Invoke" ], "Effect": "Allow", "Resource": [ "arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/stageName/GET/*" ] } ] } ``` ------ ## Ejemplo 3: Política de punto de conexión de VPC que otorga acceso a un usuario específico a una API específica El siguiente ejemplo de política otorga acceso a un usuario específico a una API específica a través del punto de conexión de VPC al que está asociada la política. En este caso, como la política restringe el acceso a entidades principales de IAM específicas, debe establecer el `authorizationType` del método en `AWS_IAM` o `NONE`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Principal": { "AWS": [ "arn:aws:iam::123412341234:user/MyUser" ] }, "Action": [ "execute-api:Invoke" ], "Effect": "Allow", "Resource": [ "arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*" ] } ] } ``` ------ ## Ejemplo 4: Política de punto de conexión de VPC que otorga a los usuarios acceso a un nombre de dominio personalizado específico y a todas las API asignadas al dominio El siguiente ejemplo de política otorga acceso a los usuarios a un determinado nombre de dominio personalizado para API privadas a través del punto de conexión de VPC al que está asociada la política. Con esta política, siempre que el usuario haya creado una asociación de acceso a nombre de dominio entre el punto de conexión de VPC y el nombre de dominio personalizado y se le otorgue acceso para invocar el nombre de dominio personalizado y cualquier API privada asignada al nombre de dominio personalizado, el usuario puede invocar cualquier API asignada a este nombre de dominio personalizado. Para obtener más información, consulte [Nombres de dominio personalizados para API privadas en API Gateway](apigateway-private-custom-domains.md). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": "execute-api:Invoke", "Resource": [ "*" ], "Condition": { "ArnEquals": { "execute-api:viaDomainArn": "arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.test.com+f4g5h6", } } } ] } ``` ------ ## Ejemplo 5: Política de punto de conexión de VPC que otorga o deniega el acceso a determinadas API y recursos de dominio La siguiente política de ejemplo otorga a los usuarios acceso a determinadas API y recursos de dominio. Con esta política, siempre que el usuario haya creado una asociación de acceso a nombre de dominio entre el punto de conexión de VPC y el nombre de dominio personalizado y se le otorgue acceso para invocar el nombre de dominio personalizado y cualquier API privada asignada al nombre de dominio personalizado, el usuario puede invocar las API privadas y los recursos de dominio permitidos. Para obtener más información, consulte [Nombres de dominio personalizados para API privadas en API Gateway](apigateway-private-custom-domains.md). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.test.com+f4g5h6", "arn:aws:execute-api:us-west-2:111122223333:a1b2c3d4e5/*" ] }, { "Effect": "Deny", "Principal": { "AWS": "*" }, "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:us-west-2:111122223333:a1b2c3d4e5/admin/*", "arn:aws:execute-api:us-west-2:111122223333:bcd123455/*" ] } ] } ``` ------ ## Ejemplo 6: política de punto de conexión de VPC que concede o deniega el acceso a entidades principales y recursos que pertenecen a una organización La siguiente política de ejemplo concede acceso a entidades principales y recursos que pertenecen a una organización. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Condition": { "StringEquals": { "aws:ResourceOrgID": "o-abcd1234", "aws:PrincipalOrgID": "o-abcd1234" } }, "Action": "*", "Resource": "*", "Effect": "Allow", "Principal": { "AWS": "*" }, "Sid": "AllowRequestsByOrgsIdentitiesToOrgsResources" } ] } ``` ------ # Uso de etiquetas para controlar el acceso a las API de REST en API Gateway El permiso para obtener acceso a las API REST se puede ajustar mediante el control de acceso basado en atributos en las políticas de IAM. Para obtener más información, consulte [Uso de etiquetas para controlar el acceso a los recursos API de REST de API Gateway](apigateway-tagging-iam-policy.md). # Uso de autorizadores Lambda de API Gateway Utilice un *autorizador de Lambda* (que anteriormente se denominaba *autorizador personalizado*) para controlar el acceso a su API. Cuando un cliente realiza una solicitud al método de la API, API Gateway llama al autorizador de Lambda. El autorizador de Lambda toma la identidad del intermediario como entrada y devuelve una política de IAM como salida. Utilice un autorizador de Lambda para implementar un esquema de autorización personalizado. El esquema puede utilizar los parámetros de la solicitud para determinar la identidad del intermediario o utilizar una estrategia de autenticación de token de portador como OAuth o SAML. Cree un autorizador de Lambda en la consola de la API de REST de API Gateway mediante la AWS CLI o un SDK de AWS. ## Flujo del trabajo de autorización del autorizador de Lambda El siguiente diagrama muestra el flujo de trabajo de autorización para un autorizador de Lambda. ![\[Flujo de trabajo de autorización de Lambda en API Gateway\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/custom-auth-workflow.png) **Flujo de trabajo de autorización de Lambda en API Gateway** 1. El cliente llama a un método en una API de API Gateway, pasando un token de portador o parámetros de solicitud. 1. API Gateway comprueba si la solicitud de método está configurada con un autorizador de Lambda. Si es así, API Gateway llama a la función de Lambda. 1. La función de Lambda autentica al intermediario. La función puede autenticarse de una de las siguientes formas: + Llamando a un proveedor de OAuth para obtener un token de acceso de OAuth. + Llamando a un proveedor de SAML para obtener una aserción de SAML. + Generando una política de IAM basada en los valores de los parámetros de la solicitud. + Recuperando credenciales de una base de datos. 1. La función de Lambda devuelve una política de IAM y un identificador de entidad principal. Si la función de Lambda no devuelve esa información, se produce un error en la llamada. 1. API Gateway evalúa la política de IAM. + Si se deniega el acceso, API Gateway devuelve un código de estado HTTP apropiado, como por ejemplo `403 ACCESS_DENIED`. + Si se permite el acceso, API Gateway invoca el método. Si habilita el almacenamiento en caché de la autorización, API Gateway almacena en caché la política de modo que no es necesario volver a invocar la función del autorizador de Lambda. Asegúrese de que la política se aplique a todos los recursos y métodos de la API. Puede personalizar las respuestas de la puerta de enlace `403 ACCESS_DENIED` o `401 UNAUTHORIZED`. Para obtener más información, consulte [Respuestas de Gateway para las API de REST en API Gateway](api-gateway-gatewayResponse-definition.md). ## Elección de un tipo de autorizador de Lambda Hay dos tipos de autorizadores Lambda: **Autorizador de Lambda basado en parámetros de solicitud (autorizador `REQUEST`)** Un autorizador `REQUEST` recibe la identidad de la persona que llama en una combinación de encabezados, parámetros de cadenas de consulta, [`stageVariables`](api-gateway-mapping-template-reference.md#stagevariables-template-reference) y variables [`$context`](api-gateway-mapping-template-reference.md#context-variable-reference). Puede usar un autorizador `REQUEST` para crear políticas detalladas basadas en la información de varios orígenes de identidad, como las variables de contexto `$context.path` y `$context.httpMethod`. Si activa el almacenamiento en caché de autorizaciones para un autorizador `REQUEST`, API Gateway verifica que todos los orígenes de identidad especificados estén presentes en la solicitud. Si falta algún origen de identidad especificado, o bien es nulo o está vacío, API Gateway devolverá una respuesta HTTP `401 Unauthorized` sin llamar a la función del autorizador de Lambda. Cuando se definen varios orígenes de identidad, se utilizan todos para obtener la clave de caché del autorizador, manteniendo el mismo orden. Puede definir una clave de caché detallada mediante el uso de varios orígenes de identidad. Si cambia cualquiera de las partes de la clave de caché y vuelve a implementar su API, el autorizador descartará el documento de políticas almacenado en caché y generará otro nuevo. Si desactiva el almacenamiento en caché de autorizaciones para un autorizador `REQUEST`, API Gateway pasa directamente la solicitud a la función de Lambda. **Autorizador de Lambda basado en token (autorizador `TOKEN`)** Un autorizador `TOKEN` recibe la identidad del intermediario en un token de portador, como, por ejemplo, un JSON Web Token (JWT) o un token de OAuth. Si activa el almacenamiento en caché de autorizaciones para un autorizador `TOKEN`, el nombre del encabezado especificado en el origen del token pasará a ser la clave de caché. Además, puede utilizar la validación del token para introducir una instrucción RegEx. API Gateway realiza la validación inicial del token de entrada con respecto a esta expresión e invoca la función del autorizador de Lambda tras una validación correcta. Esto ayuda a reducir las llamadas a la API. La propiedad `IdentityValidationExpression` solo es compatible con autorizadores `TOKEN`. Para obtener más información, consulte [Objeto x-amazon-apigateway-authorizer](api-gateway-swagger-extensions-authorizer.md). **nota** Le recomendamos que utilice un autorizador `REQUEST` para controlar el acceso a su API. Puede controlar el acceso a su API en función de varios orígenes de identidad al utilizar un autorizador `REQUEST`, en comparación con un único origen de identidad al utilizar un autorizador `TOKEN`. Además, puede separar las claves de caché utilizando varios orígenes de identidad para un autorizador `REQUEST`. ## Ejemplo de función de Lambda con un autorizador `REQUEST` El siguiente código de ejemplo crea una función del autorizador de Lambda que permite realizar una solicitud si el encabezado `HeaderAuth1`, el parámetro de consulta `QueryString1` y la variable de etapa de `StageVar1` proporcionados por el cliente coinciden con los valores especificados de `headerValue1`, `queryValue1` y `stageValue1` respectivamente. ------ #### [ Node.js ] ``` // A simple request-based authorizer example to demonstrate how to use request // parameters to allow or deny a request. In this example, a request is // authorized if the client-supplied HeaderAuth1 header, QueryString1 // query parameter, and stage variable of StageVar1 all match // specified values of 'headerValue1', 'queryValue1', and 'stageValue1', // respectively. export const handler = function(event, context, callback) { console.log('Received event:', JSON.stringify(event, null, 2)); // Retrieve request parameters from the Lambda function input: var headers = event.headers; var queryStringParameters = event.queryStringParameters; var pathParameters = event.pathParameters; var stageVariables = event.stageVariables; // Parse the input for the parameter values var tmp = event.methodArn.split(':'); var apiGatewayArnTmp = tmp[5].split('/'); var awsAccountId = tmp[4]; var region = tmp[3]; var restApiId = apiGatewayArnTmp[0]; var stage = apiGatewayArnTmp[1]; var method = apiGatewayArnTmp[2]; var resource = '/'; // root resource if (apiGatewayArnTmp[3]) { resource += apiGatewayArnTmp[3]; } // Perform authorization to return the Allow policy for correct parameters and // the 'Unauthorized' error, otherwise. if (headers.HeaderAuth1 === "headerValue1" && queryStringParameters.QueryString1 === "queryValue1" && stageVariables.StageVar1 === "stageValue1") { callback(null, generateAllow('me', event.methodArn)); } else { callback(null, generateDeny('me', event.methodArn)); } } // Help function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { // Required output: var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17'; // default version policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; // default action statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; } var generateAllow = function(principalId, resource) { return generatePolicy(principalId, 'Allow', resource); } var generateDeny = function(principalId, resource) { return generatePolicy(principalId, 'Deny', resource); } ``` ------ #### [ Python ] ``` # A simple request-based authorizer example to demonstrate how to use request # parameters to allow or deny a request. In this example, a request is # authorized if the client-supplied headerauth1 header, QueryString1 # query parameter, and stage variable of StageVar1 all match # specified values of 'headerValue1', 'queryValue1', and 'stageValue1', # respectively. def lambda_handler(event, context): print(event) # Retrieve request parameters from the Lambda function input: headers = event['headers'] queryStringParameters = event['queryStringParameters'] pathParameters = event['pathParameters'] stageVariables = event['stageVariables'] # Parse the input for the parameter values tmp = event['methodArn'].split(':') apiGatewayArnTmp = tmp[5].split('/') awsAccountId = tmp[4] region = tmp[3] restApiId = apiGatewayArnTmp[0] stage = apiGatewayArnTmp[1] method = apiGatewayArnTmp[2] resource = '/' if (apiGatewayArnTmp[3]): resource += apiGatewayArnTmp[3] # Perform authorization to return the Allow policy for correct parameters # and the 'Unauthorized' error, otherwise. if (headers['HeaderAuth1'] == "headerValue1" and queryStringParameters['QueryString1'] == "queryValue1" and stageVariables['StageVar1'] == "stageValue1"): response = generateAllow('me', event['methodArn']) print('authorized') return response else: print('unauthorized') response = generateDeny('me', event['methodArn']) return response # Help function to generate IAM policy def generatePolicy(principalId, effect, resource): authResponse = {} authResponse['principalId'] = principalId if (effect and resource): policyDocument = {} policyDocument['Version'] = '2012-10-17' policyDocument['Statement'] = [] statementOne = {} statementOne['Action'] = 'execute-api:Invoke' statementOne['Effect'] = effect statementOne['Resource'] = resource policyDocument['Statement'] = [statementOne] authResponse['policyDocument'] = policyDocument authResponse['context'] = { "stringKey": "stringval", "numberKey": 123, "booleanKey": True } return authResponse def generateAllow(principalId, resource): return generatePolicy(principalId, 'Allow', resource) def generateDeny(principalId, resource): return generatePolicy(principalId, 'Deny', resource) ``` ------ En este ejemplo, la función del autorizador de Lambda comprueba los parámetros de entrada y actúa como se indica a continuación: + Si todos los valores de los parámetros necesarios coinciden con los valores previstos, la función del autorizador devuelve una respuesta HTTP `200 OK` y una política de IAM que tiene un aspecto similar al siguiente, y la solicitud del método se lleva a cabo correctamente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] } ``` ------ + De lo contrario, la función del autorizador devuelve una respuesta HTTP `401 Unauthorized` y la solicitud al método produce un error. Además de devolver una política de IAM, la función del autorizador de Lambda también debe devolver el identificador principal del intermediario. Opcionalmente, puede devolver un objeto `context`, que contiene información adicional que puede pasarse al backend de integración. Para obtener más información, consulte [Salida de un autorizador de Lambda de API Gateway](api-gateway-lambda-authorizer-output.md). En el código de producción, es posible que necesite autenticar al usuario antes de conceder la autorización. En tal caso, puede agregar la lógica de autenticación a la función de Lambda llamando a un proveedor de autenticación de la forma que se indica en la documentación de ese proveedor. ## Ejemplo de función de Lambda con un autorizador `TOKEN` El siguiente código de ejemplo crea una función del autorizador de Lambda `TOKEN` que permite al intermediario invocar un método si el valor del token proporcionado por el cliente es `allow`. El intermediario no puede invocar la solicitud si el valor del token es `deny`. Si el valor del token es `unauthorized` o una cadena vacía, la función del autorizador devolverá una respuesta `401 UNAUTHORIZED`. ------ #### [ Node.js ] ``` // A simple token-based authorizer example to demonstrate how to use an authorization token // to allow or deny a request. In this example, the caller named 'user' is allowed to invoke // a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke // the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty // string, the authorizer function returns an HTTP 401 status code. For any other token value, // the authorizer returns an HTTP 500 status code. // Note that token values are case-sensitive. export const handler = function(event, context, callback) { var token = event.authorizationToken; switch (token) { case 'allow': callback(null, generatePolicy('user', 'Allow', event.methodArn)); break; case 'deny': callback(null, generatePolicy('user', 'Deny', event.methodArn)); break; case 'unauthorized': callback("Unauthorized"); // Return a 401 Unauthorized response break; default: callback("Error: Invalid token"); // Return a 500 Invalid token response } }; // Help function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17'; policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; } ``` ------ #### [ Python ] ``` # A simple token-based authorizer example to demonstrate how to use an authorization token # to allow or deny a request. In this example, the caller named 'user' is allowed to invoke # a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke # the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty # string, the authorizer function returns an HTTP 401 status code. For any other token value, # the authorizer returns an HTTP 500 status code. # Note that token values are case-sensitive. import json def lambda_handler(event, context): token = event['authorizationToken'] if token == 'allow': print('authorized') response = generatePolicy('user', 'Allow', event['methodArn']) elif token == 'deny': print('unauthorized') response = generatePolicy('user', 'Deny', event['methodArn']) elif token == 'unauthorized': print('unauthorized') raise Exception('Unauthorized') # Return a 401 Unauthorized response return 'unauthorized' try: return json.loads(response) except BaseException: print('unauthorized') return 'unauthorized' # Return a 500 error def generatePolicy(principalId, effect, resource): authResponse = {} authResponse['principalId'] = principalId if (effect and resource): policyDocument = {} policyDocument['Version'] = '2012-10-17' policyDocument['Statement'] = [] statementOne = {} statementOne['Action'] = 'execute-api:Invoke' statementOne['Effect'] = effect statementOne['Resource'] = resource policyDocument['Statement'] = [statementOne] authResponse['policyDocument'] = policyDocument authResponse['context'] = { "stringKey": "stringval", "numberKey": 123, "booleanKey": True } authResponse_JSON = json.dumps(authResponse) return authResponse_JSON ``` ------ En este ejemplo, cuando la API recibe una solicitud de método, API Gateway pasa el token de origen a esta función de autorizador de Lambda en el atributo `event.authorizationToken`. La función del autorizador de Lambda lee el token y actúa como se indica a continuación: + Si el valor del token es `allow`, la función del autorizador devuelve una respuesta HTTP `200 OK` y una política de IAM que tiene un aspecto similar al siguiente, y la solicitud del método se lleva a cabo correctamente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] } ``` ------ + Si el valor del token es `deny`, la función del autorizador devolverá una respuesta HTTP `200 OK` y una política `Deny` de IAM similar a la siguiente y se producirá un error en la solicitud del método: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Deny", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] } ``` ------ **nota** Fuera del entorno de prueba, API Gateway devuelve una respuesta HTTP `403 Forbidden` y la solicitud del método produce un error. + Si el valor del token es `unauthorized` o una cadena vacía, la función del autorizador devolverá una respuesta HTTP `401 Unauthorized` y la llamada al método producirá un error. + Si el token es cualquier otra cosa, el cliente recibirá una respuesta `500 Invalid token` y la llamada al método producirá un error. Además de devolver una política de IAM, la función del autorizador de Lambda también debe devolver el identificador principal del intermediario. Opcionalmente, puede devolver un objeto `context`, que contiene información adicional que puede pasarse al backend de integración. Para obtener más información, consulte [Salida de un autorizador de Lambda de API Gateway](api-gateway-lambda-authorizer-output.md). En el código de producción, es posible que necesite autenticar al usuario antes de conceder la autorización. En tal caso, puede agregar la lógica de autenticación a la función de Lambda llamando a un proveedor de autenticación de la forma que se indica en la documentación de ese proveedor. ## Ejemplos adicionales de funciones del autorizador de Lambda En la siguiente lista, se muestran ejemplos adicionales de funciones del autorizador de Lambda. Puede crear una función de Lambda en la misma cuenta desde la que creó la API o en una cuenta diferente. Para las funciones de Lambda del ejemplo anterior, puede utilizar el [AWSLambdaBasicExecutionRole](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html) integrado, ya que estas funciones no llaman a otros servicios de AWS. Si su función de Lambda llama a otros servicios de AWS, tendrá que asignar un rol de ejecución de IAM para la función de Lambda. Para crear el rol, siga las instrucciones de [Rol de ejecución de AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html). **Ejemplos adicionales de funciones del autorizador de Lambda** + Para ver una aplicación de ejemplo, consulte [Open Banking Brazil - Ejemplos de autorización](https://github.com/aws-samples/openbanking-brazilian-auth-samples) en GitHub. + Para ver más ejemplos de funciones de Lambda, consulte [aws-apigateway-lambda-authorizer-blueprints](https://github.com/awslabs/aws-apigateway-lambda-authorizer-blueprints) en GitHub. + Puede crear un autorizador de Lambda que autentique a los usuarios mediante grupos de usuarios de Amazon Cognito y autorice a los intermediarios en función de un almacén de políticas mediante permisos verificados. Para obtener más información, consulte [Control del acceso en función de los atributos de una identidad con Verified Permissions](apigateway-lambda-authorizer-verified-permissions.md). + La consola de Lambda ofrece un proyecto de Python, que se puede utilizar eligiendo **Use a blueprint (Utilizar un proyecto)** y eligiendo el proyecto **api-gateway-authorizer-python**. # Configuración de un autorizador de Lambda de API Gateway Tras crear una función de Lambda, debe configurarla como un autorizador para su API. A continuación, configure su método para invocar su autorizador de Lambda y determinar si un intermediario puede invocar su método. Puede crear una función de Lambda en la misma cuenta desde la que creó la API o en una cuenta diferente. Puede probar su autorizador de Lambda mediante las herramientas integradas en la consola de API Gateway o con [Postman](https://www.postman.com/). Para obtener instrucciones sobre cómo usar Postman para probar la función del autorizador de Lambda, consulte [Llamada a una API con un autorizador de Lambda de API Gateway](call-api-with-api-gateway-lambda-authorization.md). ## Configuración de un autorizador de Lambda (consola) El siguiente procedimiento muestra cómo crear un autorizador de Lambda en la consola de la API de REST de API Gateway. Para obtener más información sobre los distintos tipos de autorizadores de Lambda, consulte [Elección de un tipo de autorizador de Lambda](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-choose). ------ #### [ REQUEST authorizer ] **Configuración de un autorizador de Lambda `REQUEST`** 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Seleccione una API y, a continuación, elija **Autorizadores**. 1. Elija **Crear autorizador**. 1. En **Nombre del autorizador**, ingrese un nombre para el autorizador. 1. En **Tipo de autorizador**, seleccione **Lambda**. 1. En **Función de Lambda**, seleccione la Región de AWS en la que creó la función de autorizador de Lambda y, a continuación, ingrese el nombre de la función. 1. Deje en blanco **Rol de invocación de Lambda** para permitir que la consola de la API de REST de API Gateway defina una política basada en recursos. La política concede permisos a API Gateway para invocar la función del autorizador de Lambda. También puede escribir el nombre de un rol de IAM para permitir que API Gateway invoque la función del autorizador de Lambda. Para ver un rol de ejemplo, consulte [Crear un rol de IAM asumible](integrating-api-with-aws-services-lambda.md#api-as-lambda-proxy-setup-iam-role-policies). 1. En **Carga de evento de Lambda**, seleccione **Solicitud**. 1. En **Tipo de origen de identidades**, seleccione un tipo de parámetro. Los tipos de parámetro admitidos son `Header`, `Query string`, `Stage variable` y `Context`. Para agregar más orígenes de identidades, elija **Agregar parámetro**. 1. Para almacenar en caché la política de autorización generada por el autorizador, mantenga activado **Almacenamiento en caché de la autorización**. Cuando se activa el almacenamiento en caché de políticas, puede modificar el valor **TTL**. Si establece **TTL** en cero se desactivará el almacenamiento en caché de políticas. Si habilita el almacenamiento en caché, su autorizador debe devolver una política que se aplique a todos los métodos a través de una API. Para aplicar una política específica de un método, utilice las variables de contexto `$context.path` y `$context.httpMethod`. 1. Elija **Crear autorizador**. ------ #### [ TOKEN authorizer ] **Configuración de un autorizador de Lambda `TOKEN`** 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Seleccione una API y, a continuación, elija **Autorizadores**. 1. Elija **Crear autorizador**. 1. En **Nombre del autorizador**, ingrese un nombre para el autorizador. 1. En **Tipo de autorizador**, seleccione **Lambda**. 1. En **Función de Lambda**, seleccione la Región de AWS en la que creó la función de autorizador de Lambda y, a continuación, ingrese el nombre de la función. 1. Deje en blanco **Rol de invocación de Lambda** para permitir que la consola de la API de REST de API Gateway defina una política basada en recursos. La política concede permisos a API Gateway para invocar la función del autorizador de Lambda. También puede escribir el nombre de un rol de IAM para permitir que API Gateway invoque la función del autorizador de Lambda. Para ver un rol de ejemplo, consulte [Crear un rol de IAM asumible](integrating-api-with-aws-services-lambda.md#api-as-lambda-proxy-setup-iam-role-policies). 1. En **Carga de evento de Lambda**, seleccione **Token**. 1. En **Origen del token**, ingrese el nombre del encabezado que contiene el token de autorización. El intermediario debe incluir un encabezado con este nombre para enviar el token de autorización al autorizador de Lambda. 1. (Opcional) Si lo desea, en **Validación del token**, introduzca una instrucción RegEx. API Gateway realiza la validación inicial del token de entrada contra esta expresión e invoca el autorizador tras una validación correcta. 1. Para almacenar en caché la política de autorización generada por el autorizador, mantenga activado **Almacenamiento en caché de la autorización**. Cuando el almacenamiento en caché de las políticas esté habilitado, el nombre del encabezado especificado en **Origen del token** pasará a ser la clave de caché. Cuando se activa el almacenamiento en caché de políticas, puede modificar el valor **TTL**. Si establece **TTL** en cero se desactivará el almacenamiento en caché de políticas. Si habilita el almacenamiento en caché, su autorizador debe devolver una política que se aplique a todos los métodos a través de una API. Para aplicar una política específica de un método, puede desactivar **Almacenamiento en caché de autorización**. 1. Elija **Crear autorizador**. ------ Después de crear el autorizador de Lambda, puede probarlo. El siguiente procedimiento muestra cómo probar el autorizador de Lambda. ------ #### [ REQUEST authorizer ] **Prueba de un autorizador de Lambda `REQUEST`** 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Seleccione el nombre del autorizador. 1. En **Probar autorizador**, introduzca un valor para su origen de identidad. Si utiliza la [Ejemplo de función de Lambda con un autorizador `REQUEST`](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-request-lambda-function-create), haga lo siguiente: 1. Seleccione **Encabezado** e ingrese **headerValue1** y, a continuación, elija **Agregar parámetro**. 1. En **Tipo de origen de identidades**, seleccione **Cadena de consulta** e ingrese **queryValue1** y, a continuación, elija **Agregar parámetro**. 1. En **Tipo de origen de identidades**, seleccione **Variable de etapa** e ingrese **stageValue1**. No puede modificar las variables de contexto para la invocación de la prueba, pero sí puede modificar la plantilla de eventos de prueba del **Autorizador de API Gateway** para la función de Lambda. A continuación, puede probar la función del autorizador de Lambda con variables de contexto modificadas. Para obtener más información, consulte [Prueba de funciones de Lambda en la consola](https://docs.aws.amazon.com/lambda/latest/dg/testing-functions.html) en la *Guía para desarrolladores de AWS Lambda*. 1. Elija **Probar el autorizador**. ------ #### [ TOKEN authorizer ] **Prueba de un autorizador de Lambda `TOKEN`** 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Seleccione el nombre del autorizador. 1. En **Probar autorizador**, introduzca un valor para su token. Si utiliza la [Ejemplo de función de Lambda con un autorizador `TOKEN`](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-token-lambda-function-create), haga lo siguiente: 1. En **authorizationToken**, especifique **allow**. 1. Elija **Probar el autorizador**. Si el autorizador de Lambda rechaza correctamente una solicitud en el entorno de prueba, la prueba produce una respuesta HTTP `200 OK`. Sin embargo, fuera del entorno de prueba, API Gateway devuelve una respuesta HTTP `403 Forbidden` y la solicitud del método produce un error. ------ ## Configuración de un autorizador de Lambda (AWS CLI) El siguiente comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) muestra cómo crear un autorizador de Lambda mediante la AWS CLI. ------ #### [ REQUEST authorizer ] El siguiente comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) permite crear un autorizador de `REQUEST`, y utiliza el encabezado `Authorizer` y la variable de contexto `accountId` como orígenes de identidad: ``` aws apigateway create-authorizer \ --rest-api-id 1234123412 \ --name 'First_Request_Custom_Authorizer' \ --type REQUEST \ --authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \ --identity-source 'method.request.header.Authorization,context.accountId' \ --authorizer-result-ttl-in-seconds 300 ``` ------ #### [ TOKEN authorizer ] El siguiente comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) permite crear un autorizados de `TOKEN`, y utiliza el encabezado `Authorization` como origen de identidad: ``` aws apigateway create-authorizer \ --rest-api-id 1234123412 \ --name 'First_Token_Custom_Authorizer' \ --type TOKEN \ --authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \ --identity-source 'method.request.header.Authorization' \ --authorizer-result-ttl-in-seconds 300 ``` ------ Después de crear el autorizador de Lambda, puede probarlo. El siguiente comando [test-invoke-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-authorizer.html) permite probar un autorizador de Lambda: ``` aws apigateway test-invoke-authorizer --rest-api-id 1234123412 \ --authorizer-id efg1234 \ --headers Authorization='Value' ``` ## Configuración de un método para utilizar un autorizador de Lambda (consola) Después de configurar el autorizador de Lambda, debe asociarlo a un método para la API. Si el autorizador utiliza el almacenamiento en caché de la autorización, asegúrese de actualizar la política para controlar el acceso del método adicional. **Para configurar un método de API para que use un autorizador de Lambda** 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Seleccione una API. 1. Elija **Recursos** y seleccione un método nuevo o elija un método existente. 1. En la pestaña **Solicitud de método**, en **Configuración de solicitud de método**, elija **Editar**. 1. En **Autorizador**, en el menú desplegable, seleccione el autorizador de Lambda que acaba de crear. 1. (Opcional) Si quiere pasar el token de autorización al backend, elija los **encabezados de solicitud HTTP**. Elija **Agregar encabezado** y, a continuación, agregue el nombre del encabezado de autorización. En **Nombre**, escriba el nombre de encabezado que coincida con el nombre de **Origen del token** que especificó al crear el autorizador de Lambda para la API. Este paso no se aplica a los autorizadores `REQUEST`. 1. Seleccione **Save**. 1. Elija **Deploy API (Implementar API)** para implementar la API en una etapa. Para un autorizador `REQUEST` que utiliza variables de etapa, también debe definir las variables de etapa necesarias y especificar los valores en la página **Etapas**. ## Configuración de un método para utilizar un autorizador de Lambda (AWS CLI) Después de configurar el autorizador de Lambda, debe asociarlo a un método para la API. Puede crear un método nuevo o utilizar una operación de parche para asociar un autorizador a un método existente. Si el autorizador utiliza el almacenamiento en caché de la autorización, asegúrese de actualizar la política para controlar el acceso del método adicional. El siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) permite crear un método nuevo que utilice un autorizador de Lambda: ``` aws apigateway put-method --rest-api-id 1234123412 \ --resource-id a1b2c3 \ --http-method PUT \ --authorization-type CUSTOM \ --authorizer-id efg1234 ``` El siguiente comando [update-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-method.html) permite actualizar un método existente para que utilice un autorizador de Lambda: ``` aws apigateway update-method \ --rest-api-id 1234123412 \ --resource-id a1b2c3 \ --http-method PUT \ --patch-operations op="replace",path="/authorizationType",value="CUSTOM" op="replace",path="/authorizerId",value="efg1234" ``` # Entrada de un autorizador de Lambda de API Gateway En la siguiente sección se explica el formato de la entrada de API Gateway para un autorizador de Lambda. ## Formato de entrada de `TOKEN` Para un autorizador de Lambda (que anteriormente se denominaba autorizador personalizado) del tipo `TOKEN`, debe especificar un encabezado personalizado como **Token Source (Origen del token)** al configurar el autorizador para una API. El cliente de la API debe transmitir el token de autorización necesario en ese encabezamiento en la solicitud de entrada. Tras recibir la solicitud del método de entrada, API Gateway extrae el token del encabezado personalizado. A continuación, transmite el token como propiedad `authorizationToken` del objeto `event` de la función de Lambda, además del ARN del método como propiedad `methodArn`: ``` { "type":"TOKEN", "authorizationToken":"{caller-supplied-token}",     "methodArn":"arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]" } ``` En este ejemplo, la propiedad `type` especifica el tipo de autorizador, que es un autorizador `TOKEN`. `{caller-supplied-token}` procede del encabezado de autorización de una solicitud del cliente y puede ser cualquier valor de cadena. `methodArn` es el ARN de la solicitud del método de entrada y lo rellena API Gateway de acuerdo con la configuración del autorizador de Lambda. ## Formato de entrada de `REQUEST` Para un autorizador de Lambda del tipo `REQUEST`, API Gateway transmite los parámetros de solicitud a la función de Lambda del autorizador como parte del objeto `event`. Los parámetros de solicitud incluyen encabezados, parámetros de ruta, parámetros de cadenas de consulta, variables de etapa y algunas variables de contexto de solicitud. El intermediario de la API puede definir parámetros de ruta, encabezados y parámetros de cadenas de consulta. El desarrollador de la API debe establecer las variables de etapa durante la implementación de la API y API Gateway proporciona el contexto de la solicitud en tiempo de ejecución. **nota** Los parámetros de la ruta se pueden pasar como parámetros de solicitud a la función del autorizador de Lambda pero no se pueden usar como fuentes de identidad. El siguiente ejemplo muestra una entrada de un autorizador `REQUEST` para un método de la API (`GET /request`) con una integración de proxy: ``` { "type": "REQUEST", "methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request", "resource": "/request", "path": "/request", "httpMethod": "GET", "headers": { "X-AMZ-Date": "20170718T062915Z", "Accept": "*/*", "HeaderAuth1": "headerValue1", "CloudFront-Viewer-Country": "US", "CloudFront-Forwarded-Proto": "https", "CloudFront-Is-Tablet-Viewer": "false", "CloudFront-Is-Mobile-Viewer": "false", "User-Agent": "..." }, "queryStringParameters": { "QueryString1": "queryValue1" }, "pathParameters": {}, "stageVariables": { "StageVar1": "stageValue1" }, "requestContext": { "path": "/request", "accountId": "123456789012", "resourceId": "05c7jb", "stage": "test", "requestId": "...", "identity": { "apiKey": "...", "sourceIp": "...", "clientCert": { "clientCertPem": "CERT_CONTENT", "subjectDN": "www.example.com", "issuerDN": "Example issuer", "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", "validity": { "notBefore": "May 28 12:30:02 2019 GMT", "notAfter": "Aug 5 09:36:04 2021 GMT" } } }, "resourcePath": "/request", "httpMethod": "GET", "apiId": "abcdef123" } } ``` `requestContext` es un mapa de pares de clave-valor y se corresponde con la variable [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference). Su resultado depende de la API. API Gateway podría agregar nuevas claves al mapa. Para obtener más información sobre la entrada de la función de Lambda en una integración de proxy, consulte [Formato de entrada de una función de Lambda para la integración de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). # Salida de un autorizador de Lambda de API Gateway La salida de una función de autorizador de Lambda es un objeto similar a un diccionario que debe incluir el identificador de la entidad principal (`principalId`) y un documento de política (`policyDocument`) que contenga una lista de instrucciones de política. La salida también puede incluir un mapa `context` que contenga pares de clave-valor. Si la API utiliza un plan de uso ([https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apiKeySource](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apiKeySource) se ha establecido en `AUTHORIZER`), la función de autorizador de Lambda debe devolver una de las claves de API del plan de uso como valor de la propiedad `usageIdentifierKey`. A continuación se muestra un ejemplo de esta salida. ------ #### [ JSON ] **** ``` {   "principalId": "yyyyyyyy", "policyDocument": { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow|Deny", "Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]" } ] }, "context": { "stringKey": "value", "numberKey": "1", "booleanKey": "true" }, "usageIdentifierKey": "{api-key}" } ``` ------ Aquí, una instrucción de política especifica si se permite o deniega (`Effect`) al servicio de ejecución de API Gateway invocar (`Action`) el método de API especificado (`Resource`). Es posible que tenga que controlar el acceso a varios recursos en función del autorizador. Puede utilizar un carácter comodín (`*`) para especificar un tipo de recurso (método). Para obtener información sobre la configuración de políticas válidas para llamar a una API, consulte [Referencia de instrucciones de políticas de IAM para ejecutar la API en API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-calling-api-permissions). En el caso de los ARN del método con autorización habilitada (por ejemplo, `arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]`), la longitud máxima es de 1600 bytes. Los valores de parámetros de ruta, cuyo tamaño se determina en tiempo de ejecución, pueden provocar que la longitud del ARN supere el límite. Cuando esto ocurra, el cliente de la API recibirá una respuesta `414 Request URI too long`. Además, el ARN de recurso, tal y como se muestra en la instrucción de política de salida que ha realizado el autorizador, está limitado actualmente a 512 caracteres. Por este motivo, no debe utilizar la URI con un token JWT que tenga una longitud considerable en una URI de la solicitud. Puede transferir de manera segura el token JWT en un encabezado de solicitud. Puede tener acceso al valor `principalId` de una plantilla de asignación utilizando la variable `$context.authorizer.principalId`. Esto resulta útil si desea transmitir el valor al backend. Para obtener más información, consulte [Variables de contexto para transformaciones de datos](api-gateway-mapping-template-reference.md#context-variable-reference). Puede obtener acceso al valor de `stringKey`, `numberKey` o `booleanKey` (por ejemplo, `"value"`, `"1"` o `"true"`) del mapa `context` en una plantilla de mapeo llamando a `$context.authorizer.stringKey`, `$context.authorizer.numberKey` o `$context.authorizer.booleanKey`, respectivamente. Los valores devueltos se representan en forma de cadena. Observe que no puede establecer un objeto o matriz JSON como un valor válido de ninguna clave en el mapa `context`. Puede utilizar el mapa `context` para devolver las credenciales almacenadas en caché del autorizador al backend utilizando una plantilla de mapeo de una solicitud de integración. Esto permite que el backend proporcione una mejor experiencia de usuario mediante la utilización de las credenciales almacenadas en caché para reducir la necesidad de obtener acceso a las claves secretas y abrir los tokens de autorización para cada solicitud. En el caso de la integración de proxy de Lambda, API Gateway transmite el objeto `context` de un autorizador de Lambda directamente a la función de Lambda del backend como parte de la entrada `event`. Puede recuperar los pares de clave-valor de `context` en la función de Lambda llamando a `$event.requestContext.authorizer.key`. `{api-key}` representa una clave de API en el plan de uso de la etapa de API. Para obtener más información, consulte [Planes de uso y clave de API para las API de REST en API Gateway](api-gateway-api-usage-plans.md). El siguiente ejemplo muestra la salida del ejemplo de autorizador de Lambda. El resultado de ejemplo contiene una instrucción de política para bloquear (`Deny`) las llamadas al método `GET` para la etapa `dev` de una API (`ymy8tbxw7b`) de una cuenta de AWS (`123456789012`). ------ #### [ JSON ] **** ``` { "principalId": "user", "policyDocument": { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Deny", "Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/dev/GET/" } ] } } ``` ------ # Llamada a una API con un autorizador de Lambda de API Gateway Después de configurar el autorizador de Lambda (que anteriormente se denominaba autorizador personalizado); e implementar la API, debe probar la API con el autorizador de Lambda habilitado. Para ello, necesita un cliente REST, como cURL o [Postman](https://www.postman.com/). En los siguientes ejemplos, usamos Postman. **nota** Al llamar a un método habilitado para un autorizador, API Gateway no registra la llamada a CloudWatch si el token necesario para el autorizador `TOKEN` no se establece, es nulo o no es válido para la expresión **Token validation expression (Expresión de validación de token)** especificada. Del mismo modo, API Gateway no registra la llamada a CloudWatch si alguno de los orígenes de identidad necesarios para el autorizador `REQUEST` no está establecido, es nulo o está vacío. A continuación, mostramos cómo utilizar Postman para llamar a la API o probarla con un autorizador de Lambda `TOKEN`. El método puede usarse para llamar a una API con un autorizador de Lambda `REQUEST` si se especifican los parámetros de ruta, encabezado o cadena de consulta necesarios de forma explícita. **Llamar a una API con el autorizador personalizado `TOKEN`** 1. Abra **Postman**, elija el método **GET** y pegue el valor de **Invoke URL (Invocar URL)** de la API en el campo URL contiguo. Agregue el encabezado de token de autorización de Lambda y establezca el valor en `allow`. Seleccione **Send (enviar)**. ![\[Cómo llamar a la API con el token Allow de autorización de Lambda\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/custom-auth-call-api-with-allow-token.png) La respuesta muestra que el autorizador de Lambda de API Gateway devuelve una respuesta **200 OK** y autoriza correctamente a la llamada para que tenga acceso al punto de conexión HTTP (http://httpbin.org/get) integrado en el método. 1. Sin salir de Postman, cambie el valor del encabezado de token de autorización de Lambda a `deny`. Seleccione **Send (enviar)**. ![\[Cómo llamar a la API con el token Deny de autorización de Lambda\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/custom-auth-call-api-with-deny-token.png) La respuesta muestra que el autorizador de Lambda de API Gateway devuelve una respuesta **403 Forbidden** que no autoriza a la llamada para que tenga acceso al punto de conexión HTTP. 1. En Postman, cambie el valor del encabezado de token de autorización de Lambda a `unauthorized` y elija **Send (Enviar)**. ![\[Cómo llamar a la API con un token Unauthorized de autorización de Lambda\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/custom-auth-call-api-with-unauthorized-token.png) La respuesta muestra que API Gateway devuelve una respuesta **401 Unauthorized** sin autorizar la llamada para tener acceso al punto de conexión HTTP. 1. Ahora, cambie el valor del encabezado de token de autorización de Lambda a `fail`. Seleccione **Send (enviar)**. ![\[Cómo llamar a la API con el token Fail de autorización de Lambda\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/custom-auth-call-api-with-fail-token.png) La respuesta muestra que API Gateway devuelve una respuesta **500 Internal Server Error** sin autorizar la llamada para tener acceso al punto de conexión HTTP. # Configuración de un autorizador de Lambda de API Gateway entre cuentas Ahora también se puede utilizar una función de AWS Lambda de otra cuenta de AWS como función de autorizador de API. Cada cuenta puede estar en cualquier región en la que Amazon API Gateway esté disponible. La función de autorizador de Lambda puede utilizar estrategias de autenticación de token al portador como OAuth o SAML. Esto permite administrar y compartir fácilmente de forma centralizada la función de autorizador de Lambda en distintas API de API Gateway. En esta sección, mostramos cómo configurar una función de autorización de Lambda entre cuentas mediante la consola de Amazon API Gateway. En estas instrucciones, se presupone que usted ya dispone de una API de API Gateway en una cuenta de AWS y de una función de autorizador de Lambda en otra cuenta. ## Configurar un autorizador de Lambda entre cuentas mediante la consola de API Gateway Inicie sesión en la consola de Amazon API Gateway en la cuenta que tiene la API y, a continuación, haga lo siguiente: 1. Elija la API y, a continuación, en el panel de navegación principal, elija **Autorizadores**. 1. Elija **Crear autorizador**. 1. En **Nombre del autorizador**, ingrese un nombre para el autorizador. 1. En **Tipo de autorizador**, seleccione **Lambda**. 1. En **Función de Lambda**, copie y pegue el ARN completo de la función del autorizador de Lambda que tiene en la segunda cuenta. **nota** En la consola de Lambda, puede encontrar el ARN de la función en la esquina superior derecha de la ventana de la consola. 1. Aparecerá una advertencia con una cadena de comandos `aws lambda add-permission`. La política concede permiso de API Gateway para invocar la función de Lambda del autorizador. Copie el comando y guárdelo para más adelante. Ejecute el comando después de crear el autorizador. 1. En **Carga útil del evento de Lambda**, seleccione **Token** para un autorizador `TOKEN` o **Solicitud** para un autorizador `REQUEST`. 1. Dependiendo de la elección del paso anterior, lleve a cabo alguna de las siguientes operaciones: 1. Para la opción **Token**, haga lo siguiente: + En **Origen del token**, ingrese el nombre del encabezado que contiene el token de autorización. El cliente de la API debe incluir un encabezado con este nombre para enviar el token de autorización al autorizador de Lambda. + Si lo desea, en **Validación del token**, ingrese una instrucción RegEx. API Gateway realiza la validación inicial del token de entrada contra esta expresión e invoca el autorizador tras una validación correcta. Esto ayuda a reducir las llamadas a la API. + Para almacenar en caché la política de autorización generada por el autorizador, mantenga activado **Almacenamiento en caché de la autorización**. Cuando se activa el almacenamiento en caché de políticas, puede modificar el valor **TTL**. Si establece **TTL** en cero se desactivará el almacenamiento en caché de políticas. Cuando el almacenamiento en caché de las políticas esté habilitado, el nombre del encabezado especificado en **Origen del token** pasará a ser la clave de caché. Si se pasan varios valores a este encabezado de la solicitud, todos los valores se convertirán en la clave de caché y se conservará el orden. **nota** El valor de **TTL** predeterminado es de 300 segundos. El valor máximo es de 3600 segundos, este límite no se puede aumentar. 1. Para la opción **Request (Solicitud)**, haga lo siguiente: + En **Tipo de origen de identidades**, seleccione un tipo de parámetro. Los tipos de parámetro admitidos son `Header`, `Query string`, `Stage variable` y `Context`. Para agregar más orígenes de identidades, elija **Agregar parámetro**. + Para almacenar en caché la política de autorización generada por el autorizador, mantenga activado **Almacenamiento en caché de la autorización**. Cuando se activa el almacenamiento en caché de políticas, puede modificar el valor **TTL**. Si establece **TTL** en cero se desactivará el almacenamiento en caché de políticas. API Gateway utiliza las fuentes de identidad especificadas como la clave de caché del autorizador de la solicitud. Cuando está habilitado el almacenamiento en caché, API Gateway llama a la función de Lambda del autorizador solo después de verificar correctamente que todas las fuentes de identidad especificadas estén presentes en tiempo de ejecución. Si falta un origen de identidad especificado, es nulo o está vacío, API Gateway devuelve una respuesta `401 Unauthorized` sin llamar a la función de Lambda del autorizador. Cuando se definen varias fuentes de identidad, se utilizan todas ellas para obtener la clave de caché del autorizador. Cambiar cualquiera de las partes de la clave de caché hace que el autorizador descarte el documento de políticas almacenado en caché y genere otro nuevo. Si se pasa un encabezado con varios valores en la solicitud, todos los valores se convertirán en la clave de caché y se conservará el orden. + ‎Cuando está desactivado el almacenamiento en caché, no es necesario especificar ningún origen de identidades. **nota** Para habilitar el almacenamiento en caché, su autorizador debe devolver una política que se aplique a todos los métodos a través de una API. Para aplicar una política específica de método, puede desactivar **Almacenamiento en caché de la autorización**. 1. Elija **Crear autorizador**. 1. Pegue la cadena de comandos `aws lambda add-permission` que copió durante un paso anterior en una ventana de la AWS CLI, que está configurada para la segunda cuenta. Reemplace `AUTHORIZER_ID` por el ID de su autorizador. Este concederá a la primera cuenta acceso a la función de autorizador de Lambda de la segunda cuenta. # Control del acceso en función de los atributos de una identidad con Verified Permissions Utilice Amazon Verified Permissions para controlar el acceso a su API de API Gateway. Cuando utiliza API Gateway con Verified Permissions, Verified Permissions crea un autorizador de Lambda que utiliza decisiones de autorización detalladas para controlar el acceso a la API. Verified Permissions autoriza a los intermediarios según el esquema y las políticas del almacenamiento de políticas mediante el lenguaje de políticas de Cedar para definir permisos detallados para los usuarios de las aplicaciones. Para obtener más información, consulte [Create a policy store with a connected API and identity provider](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/getting-started-api-policy-store.html) en la *Guía del usuario de Amazon Verified Permissions*. Verified Permissions admite grupos de usuarios de Amazon Cognito o proveedores de identidad OpenID Connect (OIDC) como orígenes de identidad. Verified Permissions presupone que la entidad principal se ha identificado y autenticado previamente. Verified Permissions solo es compatible con las API de REST regionales y optimizadas para la periferia. ## Creación de un autorizador de Lambda mediante Verified Permissions Verified Permissions crea un autorizador de Lambda para determinar si una entidad principal está autorizada a realizar una acción en la API. Cree la política de Cedar que Verified Permissions utiliza para realizar sus tareas de autorización. En el siguiente ejemplo se muestra una política de Cedar que permite el acceso para invocar una API basada en el grupo de usuarios de Amazon Cognito, `us-east-1_ABC1234` para el grupo `developer` en el recurso `GET /users` de una API. Verified Permissions determina la pertenencia al grupo mediante el análisis del token portador para la identidad del intermediario. ``` permit( principal in MyAPI::UserGroup::"us-east-1_ABC1234|developer", action in [ MyAPI::Action::"get /users" ], resource ); ``` De forma opcional, Verified Permissions puede asociar el autorizador a los métodos de la API. En las etapas de producción de la API, le recomendamos que no permita que Verified Permissions asocie el autorizador por usted. En la siguiente lista se muestra cómo configurar Verified Permissions para asociar o no el autorizador de Lambda a la solicitud de los métodos de la API. **Asociación del autorizador por usted (Consola de administración de AWS)** Cuando elija **Crear almacén de políticas** en la consola de Verified Permissions, en la página **Implementar integración de aplicaciones**, elija **Ahora**. **Sin asociación del autorizador por usted (Consola de administración de AWS)** Cuando elija **Crear almacén de políticas** en la consola de Verified Permissions, en la página **Implementar integración de aplicaciones**, elija **Más tarde**. Verified Permissions sigue creando un autorizador de Lambda por usted. El autorizador de Lambda comienza por `AVPAuthorizerLambda-`. Para obtener más instrucciones sobre cómo adjuntar el autorizador en un método, consulte [Configuración de un método para utilizar un autorizador de Lambda (consola)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-method-console). **Asociación del autorizador por usted (CloudFormation)** En la plantilla CloudFormation generada por Verified Permissions, en la sección `Conditions`, establezca `"Ref": "shouldAttachAuthorizer"` a `true`. **Sin asociación del autorizador por usted (CloudFormation)** En la plantilla CloudFormation generada por Verified Permissions, en la sección `Conditions`, establezca `"Ref": "shouldAttachAuthorizer"` a `false`. Verified Permissions sigue creando un autorizador de Lambda por usted. El autorizador de Lambda comienza por `AVPAuthorizerLambda-`. Para obtener más instrucciones sobre cómo adjuntar el autorizador en un método, consulte [Configuración de un método para utilizar un autorizador de Lambda (AWS CLI)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-method-cli). ## Llamada a un autorizador de Lambda mediante Verified Permissions Puede llamar a al autorizador de Lambda si proporciona una identidad o un token de acceso en el encabezado `Authorization`. Para obtener más información, consulte [Llamada a una API con un autorizador de Lambda de API Gateway](call-api-with-api-gateway-lambda-authorization.md). API Gateway almacena en caché la política que devuelve el autorizador de Lambda durante 120 segundos. Puede modificar el TTL en la consola de API Gateway o mediante la AWS CLI. # Control del acceso a las API de REST con grupos de usuarios de Amazon Cognito como autorizador Además de utilizar [roles y políticas de IAM](permissions.md) o [autorizadores de Lambda](apigateway-use-lambda-authorizer.md) (que anteriormente se denominaban autorizadores personalizados), también puede utilizar un [grupo de usuarios de Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) para controlar quién puede tener acceso a la API en Amazon API Gateway. Para utilizar un grupo de usuarios de Amazon Cognito con la API, primero debe crear un autorizador del tipo `COGNITO_USER_POOLS` y configurar después un método de API para que utilice ese autorizador. Una vez implementada la API, lo primero que debe hacer el cliente es registrar al usuario en el grupo de usuarios, obtener un [token de acceso o identidad](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) para el usuario y llamar al método de API con uno de los tokens, que normalmente están establecidos en el encabezado `Authorization` de la solicitud. La llamada a la API solo tendrá éxito si se suministra el token solicitado y este es válido; de lo contrario, el cliente no tendrá autorización para hacer la llamada, ya que carecerá de las credenciales que permitirían autorizarlo. El token de identidad se utiliza para autorizar las llamadas a la API en función de las solicitudes de identidad del usuario conectado. El token de acceso se utiliza para autorizar las llamadas a la API en función de los ámbitos personalizados de los recursos con protección de acceso especificados. Para obtener más información, consulte [Uso de tokens con grupos de usuarios](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) y [Servidor de recursos y ámbitos personalizados](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). Si desea crear y configurar un grupo de usuarios de Amazon Cognito para la API, debe realizar las siguientes tareas: + Utilice la API, la CLI, el SDK o la consola de Amazon Cognito para crear un grupo de usuarios; también puede utilizar un grupo de usuarios que pertenezca a otra cuenta de AWS. + Utilice la API, la CLI, el SDK o la consola de API Gateway para crear un autorizador de API Gateway con el grupo de usuarios elegido. + Utilice la API, la CLI, el SDK o la consola de API Gateway para habilitar el autorizador de los métodos de API seleccionados. Para llamar a los métodos de API con un grupo de usuarios habilitado, los clientes de la API tienen que realizar las siguientes tareas: + Utilice la API, la CLI o el SDK de Amazon Cognito para registrar el usuario en el grupo de usuarios elegido y obtener un token de identidad o acceso. Para obtener más información sobre el uso de los SDK, consulte [Ejemplos de código de Amazon Cognito con AWS SDK](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html). + Utilice una plataforma específica del cliente para llamar a la API de API Gateway implementada y proporcione el token apropiado en el encabezado `Authorization`. Como desarrollador de la API, debe proporcionar a los desarrolladores del cliente el ID del grupo de usuarios, el ID del cliente y, probablemente, los secretos del cliente asociados que se hayan definido con el grupo de usuarios. **nota** Si desea permitir que un usuario inicie sesión con las credenciales de Amazon Cognito y pueda obtener también unas credenciales temporales para utilizarlas con los permisos de un rol de IAM, utilice las [identidades federadas de Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html). Para cada método HTTP de punto de enlace de recurso de API, establezca el tipo de autorización, categoría `Method Execution`, en `AWS_IAM`. En esta sección, se explica cómo crear un grupo de usuarios, cómo integrar una API de API Gateway con el grupo de usuarios y cómo invocar una API que está integrada con el grupo de usuarios. **Topics** + [ # Creación de un grupo de usuarios de Amazon Cognito para una API REST ](apigateway-create-cognito-user-pool.md) + [ # Integración de una API REST con un grupo de usuarios de Amazon Cognito ](apigateway-enable-cognito-user-pool.md) + [ # Llamar a una API REST integrada con un grupo de usuarios de Amazon Cognito ](apigateway-invoke-api-integrated-with-cognito-user-pool.md) + [ # Configuración de un autorizador de Amazon Cognito entre cuentas para una API REST mediante la consola de API Gateway ](apigateway-cross-account-cognito-authorizer.md) + [ # Cree un autorizador de Amazon Cognito para una API de REST con CloudFormation ](apigateway-cognito-authorizer-cfn.md) # Creación de un grupo de usuarios de Amazon Cognito para una API REST Antes de integrar la API con un grupo de usuarios, debe crear el grupo de usuarios en Amazon Cognito. La configuración del grupo de usuarios debe cumplir con todas las [cuotas de recursos de Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/limits.html). Todas las variables de Amazon Cognito definidas por el usuario, como grupos, usuarios y roles, deben usar solo caracteres alfanuméricos. Para obtener instrucciones sobre cómo crear un grupo de usuarios, consulte [Tutorial: Creación de un grupo de usuarios](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) en la *Guía para desarrolladores de Amazon Cognito*. Apunte el ID del grupo de usuarios, el ID del cliente y la clave secreta del cliente. El cliente debe proporcionarlos a Amazon Cognito para que el usuario pueda registrarse en el grupo de usuarios, para iniciar sesión en el grupo de usuarios y para obtener un token de identidad o acceso, que debe incluirse en las solicitudes para llamar a los métodos de la API configurados con el grupo de usuarios. Además, se debe especificar el nombre del grupo de usuarios al configurar el grupo de usuarios como autorizador de API Gateway, tal y como se describe a continuación. Si utiliza tokens de acceso para autorizar las llamadas a los métodos de la API, asegúrese de configurar la integración de aplicaciones con el grupo de usuarios para establecer los ámbitos que desee en un determinado servidor de recursos. Para obtener más información sobre el uso de tokens con grupos de usuarios de Amazon Cognito, consulte [Uso de tokens con grupos de usuarios](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Para obtener más información acerca de los servidores de recursos, consulte [Definir servidores de recursos para su grupo de usuarios](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). Anote los identificadores del servidor de recursos configurados y los nombres de ámbito personalizados. Los necesita para generar los nombres completos de los ámbitos de acceso de **OAuth Scopes (Ámbitos de OAuth)** que el autorizador de `COGNITO_USER_POOLS` utiliza. ![\[Ámbitos y servidores de recursos de un grupo de usuarios de Amazon Cognito\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/cognito-user-pool-custom-scopes-new-console.png) # Integración de una API REST con un grupo de usuarios de Amazon Cognito Después de crear un grupo de usuarios de Amazon Cognito, en API Gateway, debe crear un autorizador `COGNITO_USER_POOLS` que utilice el grupo de usuarios. El siguiente procedimiento muestra cómo hacer esto con la consola de API Gateway. **nota** Puede utilizar la acción [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html) para crear un autorizador de `COGNITO_USER_POOLS` que utilice varios grupos de usuarios. Puede usar hasta 1000 grupos de usuarios para un autorizador de `COGNITO_USER_POOLS`. Este límite no se puede aumentar. **importante** Después de realizar cualquiera de los procedimientos que aparecen a continuación, deberá implementar o volver a implementar la API para propagar los cambios. Para obtener más información acerca cómo implementar una API, consulte [Implementación de las API de REST en API Gateway](how-to-deploy-api.md). **Para crear un autorizador `COGNITO_USER_POOLS` mediante la consola de API Gateway** 1. Cree una nueva API o seleccione una existente en API Gateway. 1. En el panel de navegación principal, elija **Autorizadores**. 1. Elija **Crear autorizador**. 1. Si desea configurar el nuevo autorizador para que utilice un grupo de usuarios, realice lo siguiente: 1. En **Nombre del autorizador**, ingrese un nombre. 1. En **Tipo de autorizador**, seleccione **Cognito**. 1. En **Grupo de usuarios de Cognito**, elija la Región de AWS donde creó Amazon Cognito y seleccione un grupo de usuarios disponible. Puede utilizar una variable de etapa para definir su grupo de usuarios. Utilice el formato siguiente para su grupo de usuarios: `arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}`. 1. En **Origen del token**, escriba **Authorization** como nombre del encabezado al que se va a pasar el token de identidad o acceso devuelto por Amazon Cognito cuando el usuario inicie sesión correctamente. 1. (Opcional) Ingrese una expresión regular en el campo **Validación de token** para validar el campo `aud` (audiencia) del token de identidad antes de autorizar la solicitud con Amazon Cognito. Tenga en cuenta que cuando se utiliza un token de acceso, esta validación rechaza la solicitud debido al token de acceso que no contiene el campo `aud`. 1. Elija **Crear autorizador**. 1. Después de crear el autorizador de `COGNITO_USER_POOLS`, puede realizar una prueba e invocarlo proporcionando un token de identidad aprovisionado desde el grupo de usuarios. No puede usar un token de acceso para realizar una prueba e invocar el autorizador. Puede obtener este token de identidad llamando al [SDK de identidad de Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) para realizar el inicio de sesión del usuario. También puede usar la acción [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html). Si no configura ningún **Ámbito de autorización**, API Gateway trata el token suministrado como un token de identidad. El procedimiento anterior crea un autorizador `COGNITO_USER_POOLS` que utiliza el grupo de usuarios de Amazon Cognito que acaba de crearse. En función del modo en que se habilite el autorizador en un método de la API, puede utilizar un token de identidad o un token de acceso aprovisionado desde el grupo de usuarios integrados. **Para configurar un autorizador de `COGNITO_USER_POOLS` en los métodos** 1. Seleccione **Recursos**. Elija un nuevo método o elija un método existente. Si es necesario, cree un recurso. 1. En la pestaña **Solicitud de método**, en **Configuración de solicitud de método**, elija **Editar**. 1. En **Autorizador**, en el menú desplegable, seleccione los **autorizadores del grupo de usuarios de Amazon Cognito** que acaba de crear. 1. Para utilizar un token de identidad, haga lo siguiente: 1. Mantenga los **ámbitos de autorización** vacíos. 1. Si fuera necesario, en la **Solicitud de integración**, agregue las expresiones `$context.authorizer.claims['property-name']` o `$context.authorizer.claims.property-name` a una plantilla de asignación de cuerpo para pasar la propiedad especificada de las reclamaciones de identidad desde el grupo de usuarios al backend. En el caso de los nombres de propiedades sencillos, como `sub` o `custom-sub`, las dos notaciones son idénticas. En el caso de los nombres de propiedades complejos, como `custom:role`, no se puede usar la notación de puntos. Por ejemplo, las siguientes expresiones de asignación pasan los [campos estándar](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) `sub` y `email` de la reclamación al backend: ``` { "context" : { "sub" : "$context.authorizer.claims.sub", "email" : "$context.authorizer.claims.email" } } ``` Si declaró un campo de reclamación personalizado al configurar un grupo de usuarios, puede seguir el mismo patrón para obtener acceso a los campos personalizados. El siguiente ejemplo obtiene un campo `role` personalizado de una reclamación: ``` { "context" : { "role" : "$context.authorizer.claims.role" } } ``` Si el campo personalizado de la reclamación está declarado como `custom:role`, utilice el siguiente ejemplo para obtener la propiedad de la reclamación: ``` { "context" : { "role" : "$context.authorizer.claims['custom:role']" } } ``` 1. Para utilizar un token de acceso, haga lo siguiente: 1. En **Ámbitos de autorización**, escriba uno o varios nombres completos de un ámbito que se haya configurado cuando se creó el grupo de usuarios de Amazon Cognito. Por ejemplo, siguiendo el ejemplo de [Creación de un grupo de usuarios de Amazon Cognito para una API REST](apigateway-create-cognito-user-pool.md), uno de los ámbitos es `https://my-petstore-api.example.com/cats.read`. En tiempo de ejecución, la llamada al método se realiza correctamente si el ámbito especificado en el método durante este paso coincide con el ámbito solicitado en el token de entrada. De lo contrario, la solicitud envía una respuesta de error `401 Unauthorized`. 1. Seleccione **Save**. 1. Repita estos pasos con otros métodos que elija. Con el autorizador `COGNITO_USER_POOLS`, si la opción **OAuth Scopes** no está especificada, API Gateway trata el token proporcionado como un token de identidad y comprueba si la identidad solicitada se corresponde con alguna del grupo de usuarios. De lo contrario, API Gateway trata el token suministrado como un token de acceso y comprueba si los ámbitos de acceso solicitados en el token tienen coincidencias con los ámbitos de autorización declarados en el método. En lugar de utilizar la consola de API Gateway, también puede habilitar un grupo de usuarios de Amazon Cognito en un método especificando un archivo de definición de OpenAPI e importando la definición de la API en API Gateway. **Para importar un autorizador COGNITO\$1USER\$1POOLS con un archivo de definición de OpenAPI** 1. Cree (o exporte) un archivo de definición de OpenAPI para la API. 1. Especifique la definición JSON del autorizador `COGNITO_USER_POOLS` (`MyUserPool`) en la sección `securitySchemes` de OpenAPI 3.0 o en la sección `securityDefinitions` de Open API 2.0, tal como se indica a continuación: ------ #### [ OpenAPI 3.0 ] ``` "securitySchemes": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ #### [ OpenAPI 2.0 ] ``` "securityDefinitions": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ 1. Para utilizar el token de identidad en la autorización del método, agregue `{ "MyUserPool": [] }` a la definición `security` del método, tal y como se muestra en el siguiente método GET del recurso raíz. ``` "paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": [] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... } ``` 1. Si desea utilizar el token de acceso para la autorización del método, cambie la definición de seguridad anterior a `{ "MyUserPool": [resource-server/scope, ...] }`: ``` "paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... } ``` 1. Si es necesario, puede establecer otra configuración de la API utilizando las definiciones o extensiones de OpenAPI correspondientes. Para obtener más información, consulte [Extensiones de OpenAPI para API Gateway](api-gateway-swagger-extensions.md). # Llamar a una API REST integrada con un grupo de usuarios de Amazon Cognito Para llamar a un método con un autorizador de grupo de usuarios configurado, el cliente debe hacer lo siguiente: + Permitir al usuario inscribirse en el grupo de usuarios. + Permitir al usuario iniciar sesión en el grupo de usuarios. + Obtenga un [token de identidad o acceso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) del usuario conectado del grupo de usuarios. + Incluya el token en el encabezado `Authorization` (u otro encabezado que haya especificado al crear el autorizador). Puede utilizar [AWS Amplify]() para realizar estas tareas. Consulte [Integrating Amazon Cognito With Web and Mobile Apps](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) para obtener más información. + Para Android, consulte [Getting Started with Amplify for Android](https://docs.amplify.aws/android/build-a-backend/auth/). + Para utilizar iOS, consulte [Getting started with Amplify for iOS](https://docs.amplify.aws/swift/build-a-backend/auth/). + Para utilizar JavaScript, consulte [Getting Started with Amplify for Javascript](https://docs.amplify.aws/javascript/build-a-backend/auth/). # Configuración de un autorizador de Amazon Cognito entre cuentas para una API REST mediante la consola de API Gateway Ahora también se puede utilizar un grupo de usuarios de Amazon Cognito perteneciente a otra cuenta de AWS como el autorizador de la API. El grupo de usuarios de Amazon Cognito puede utilizar estrategias de autenticación de token al portador como OAuth o SAML. Esto permite administrar y compartir fácilmente de forma centralizada un autorizador de grupo de usuarios de Amazon Cognito en distintas API de API Gateway. En esta sección, mostramos cómo configurar un grupo de usuarios de Amazon Cognito entre cuentas mediante la consola de Amazon API Gateway. En estas instrucciones, se presupone que usted ya dispone de una API de API Gateway en una cuenta de AWS y de un grupo de usuarios de Amazon Cognito en otra cuenta. ## Creación de un autorizador de Amazon Cognito entre cuentas para una API de REST Inicie sesión en la consola de Amazon API Gateway en la cuenta que tiene la API y, a continuación, haga lo siguiente: 1. Cree una nueva API o seleccione una existente en API Gateway. 1. En el panel de navegación principal, elija **Autorizadores**. 1. Elija **Crear autorizador**. 1. Si desea configurar el nuevo autorizador para que utilice un grupo de usuarios, realice lo siguiente: 1. En **Nombre del autorizador**, ingrese un nombre. 1. En **Tipo de autorizador**, seleccione **Cognito**. 1. En **Grupo de usuarios de Cognito**, ingrese el ARN completo del grupo de usuarios que tiene en la segunda cuenta. **nota** En la consola de Amazon Cognito, puede encontrar el ARN de su grupo de usuarios en el campo **Pool ARN (ARN de grupo)** del panel **General Settings (Configuración general)**. 1. En **Origen del token**, escriba **Authorization** como nombre del encabezado al que se va a pasar el token de identidad o acceso devuelto por Amazon Cognito cuando el usuario inicie sesión correctamente. 1. (Opcional) Ingrese una expresión regular en el campo **Validación de token** para validar el campo `aud` (audiencia) del token de identidad antes de autorizar la solicitud con Amazon Cognito. Tenga en cuenta que cuando se utiliza un token de acceso, esta validación rechaza la solicitud debido al token de acceso que no contiene el campo `aud`. 1. Elija **Crear autorizador**. # Cree un autorizador de Amazon Cognito para una API de REST con CloudFormation Puede utilizar CloudFormation para crear un grupo de usuarios de Amazon Cognito y un autorizador de Amazon Cognito. En la plantilla de CloudFormation de ejemplo se realiza lo siguiente: + Cree un grupo de usuarios de Amazon Cognito. El cliente primero registrar al usuario en el grupo de usuarios y obtener una [identidad o un token de acceso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Si utiliza tokens de acceso para autorizar las llamadas a los métodos de la API, asegúrese de configurar la integración de aplicaciones con el grupo de usuarios para establecer los ámbitos que desee en un determinado servidor de recursos. + Crea una API de API Gateway con un método `GET`. + Crea un autorizador de Amazon Cognito que utiliza el encabezado `Authorization` como origen del token. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: UserPool: Type: AWS::Cognito::UserPool Properties: AccountRecoverySetting: RecoveryMechanisms: - Name: verified_phone_number Priority: 1 - Name: verified_email Priority: 2 AdminCreateUserConfig: AllowAdminCreateUserOnly: true EmailVerificationMessage: The verification code to your new account is {####} EmailVerificationSubject: Verify your new account SmsVerificationMessage: The verification code to your new account is {####} VerificationMessageTemplate: DefaultEmailOption: CONFIRM_WITH_CODE EmailMessage: The verification code to your new account is {####} EmailSubject: Verify your new account SmsMessage: The verification code to your new account is {####} UpdateReplacePolicy: Retain DeletionPolicy: Retain CogAuthorizer: Type: AWS::ApiGateway::Authorizer Properties: Name: CognitoAuthorizer RestApiId: Ref: Api Type: COGNITO_USER_POOLS IdentitySource: method.request.header.Authorization ProviderARNs: - Fn::GetAtt: - UserPool - Arn Api: Type: AWS::ApiGateway::RestApi Properties: Name: MyCogAuthApi ApiDeployment: Type: AWS::ApiGateway::Deployment Properties: RestApiId: Ref: Api DependsOn: - CogAuthorizer - ApiGET ApiDeploymentStageprod: Type: AWS::ApiGateway::Stage Properties: RestApiId: Ref: Api DeploymentId: Ref: ApiDeployment StageName: prod ApiGET: Type: AWS::ApiGateway::Method Properties: HttpMethod: GET ResourceId: Fn::GetAtt: - Api - RootResourceId RestApiId: Ref: Api AuthorizationType: COGNITO_USER_POOLS AuthorizerId: Ref: CogAuthorizer Integration: IntegrationHttpMethod: GET Type: HTTP_PROXY Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets Outputs: ApiEndpoint: Value: Fn::Join: - "" - - https:// - Ref: Api - .execute-api. - Ref: AWS::Region - "." - Ref: AWS::URLSuffix - / - Ref: ApiDeploymentStageprod - / ``` # Integraciones para las API de REST en API Gateway Una vez configurado un método de API, debe integrarlo con un punto de enlace en el backend. El punto de enlace del backend también se conoce como punto de enlace de integración y puede ser una función de Lambda, una página web HTTP o una acción de servicio de AWS. Al igual que con el método de API, la integración de la API tiene una solicitud de integración y una respuesta de integración. La solicitud de integración incluye la solicitud HTTP que recibe el backend. Podría ser distinta o no de la solicitud de método enviada por el cliente. La respuesta de integración es la respuesta HTTP que encapsula la salida que devuelve el backend. Configurar una solicitud de integración implica lo siguiente: configurar cómo transferir las solicitudes de método enviadas por el cliente al backend; configurar cómo transformar los datos de la solicitud, si fuese necesario, a los datos de la solicitud de integración; y especificar qué función de Lambda se debe llamar, especificando a qué servidor HTTP se debe reenviar la solicitud entrante o especificando la acción del servicio de AWS que se debe invocar. Configurar una respuesta de integración (aplicable únicamente a integraciones que no sean de proxy) implica lo siguiente: configurar cómo transferir el resultado devuelto por el backend a una respuesta de método de un determinado código de estado; configurar cómo transformar los parámetros de respuesta de integración especificados en los parámetros de respuesta de método preconfigurados y configurar cómo asignar el cuerpo de la respuesta de integración al cuerpo de la respuesta de método con arreglo a las plantillas de mapeo de cuerpo especificadas. Mediante programación, el recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) encapsula la solicitud de integración y el recurso de API Gateway [https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html), la respuesta de integración. Para configurar una solicitud de integración, debe crear un recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) y utilizarlo para configurar la URL del punto de enlace de integración. A continuación, defina los permisos de IAM para acceder al backend y especifique los mapeos para transformar los datos de la solicitud entrante antes de transmitirlos al backend. Para configurar una respuesta de integración para una integración que no sea de proxy, debe crear un recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) y utilizarlo para establecer su respuesta de método de destino. A continuación, configure cómo asignar la salida del backend a la respuesta de método. **Topics** + [ # Configuración de una solicitud de integración en API Gateway ](api-gateway-integration-settings-integration-request.md) + [ # Configuración de una respuesta de integración en API Gateway ](api-gateway-integration-settings-integration-response.md) + [ # Integraciones de Lambda para las API de REST en API Gateway ](set-up-lambda-integrations.md) + [ # Integraciones de HTTP para las API de REST en API Gateway ](setup-http-integrations.md) + [ # Transmisión de la respuesta de integración para las integraciones de proxy en API Gateway ](response-transfer-mode.md) + [ # Integraciones privadas para las API de REST en API Gateway ](private-integration.md) + [ # Simulación de integraciones para las API de REST en API Gateway ](how-to-mock-integration.md) # Configuración de una solicitud de integración en API Gateway Para configurar una solicitud de integración, debe llevar a cabo las siguientes tareas obligatorias y opcionales: 1. Elija un tipo de integración que determine cómo se transfieren los datos de la solicitud de método al backend. 1. Para las integraciones no simuladas, especifique un método HTTP y la URI del punto de enlace de integración específico, excepto para la integración `MOCK`. 1. Para las integraciones con funciones de Lambda y otras acciones de servicio de AWS, establezca un rol de IAM con los permisos necesarios para que API Gateway llame al backend en su nombre. 1. Para las integraciones que no sean de proxy, establezca el mapeo de parámetros necesario para asignar los parámetros de la solicitud de método predefinidos a los parámetros de la solicitud de integración adecuados. 1. Para las integraciones que no sean de proxy, establezca el mapeo de cuerpo necesario para asignar el cuerpo de la solicitud de método entrante de un determinado tipo de contenido con arreglo a la plantilla de mapeo especificada. 1. Para integraciones que no sean de proxy, especifique la condición bajo la cual los datos de la solicitud de método entrante se transfieren al backend tal y como están. 1. También puede especificar cómo administrar la conversión de tipo para una carga binaria. 1. También puede indicar un nombre del espacio de nombres de la caché y los parámetros de caché clave para habilitar el almacenamiento en caché de la API. Estas tareas conllevan la creación de un recurso [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) de API Gateway y la definición de los valores adecuados para las propiedades. Puede hacerlo con la consola de API Gateway, los comandos de la AWS CLI, un AWS SDK o la API REST de API Gateway. **Topics** + [ # Tareas básicas de una solicitud de integración de la API ](integration-request-basic-setup.md) + [ # Elegir un tipo de integración de API de API Gateway ](api-gateway-api-integration-types.md) + [ # Configuración de una integración de proxy con un recurso de proxy ](api-gateway-set-up-simple-proxy.md) + [ # Configuración de una solicitud de integración de la API mediante la consola de API Gateway ](how-to-method-settings-console.md) # Tareas básicas de una solicitud de integración de la API Una solicitud de integración es una solicitud HTTP que envía API Gateway al backend, por la que se transfieren los datos de solicitud enviados por el cliente y se transforman los datos, si fuese necesario. El método HTTP (o verbo) y la URI de la solicitud de integración los dicta el backend (es decir, el punto de enlace de la integración). Pueden ser iguales o distintos al método HTTP y la URI de la solicitud de método, respectivamente. Por ejemplo, cuando una función de Lambda devuelve un archivo que se recupera de Amazon S3, puede exponer esta operación de forma intuitiva como una solicitud de método `GET` al cliente, aunque la correspondiente solicitud de integración requiere que se utilice una solicitud `POST` para invocar la función de Lambda. En el caso de los puntos de enlace HTTP, es probable que tanto la solicitud del método como la correspondiente solicitud de integración utilicen el mismo verbo HTTP. Sin embargo, no es necesario. Puede integrar la siguiente solicitud de método: ``` GET /{var}?query=value Host: api.domain.net ``` Con la siguiente solicitud de integración: ``` POST / Host: service.domain.com Content-Type: application/json Content-Length: ... { path: "{var}'s value", type: "value" } ``` Como desarrollador de la API, puede utilizar el verbo HTTP y la URI para la solicitud de método que mejor se adapte a sus necesidades. Sin embargo, debe cumplir los requisitos del punto de enlace de integración. Cuando los datos de la solicitud de método son distintos de los datos de la solicitud de integración, puede solucionar esta diferencia asignando los datos de la solicitud de método a los datos de la solicitud de integración. En los ejemplos anteriores, el mapeo traduce los valores de la variable de ruta (`{var}`) y el parámetro de consulta (`query`) de la solicitud de método `GET` en los valores de las propiedades de carga de la solicitud de integración para `path` y `type`. Podrían asignarse otros datos de la solicitud, como los encabezados y el cuerpo. Esto se describe en [Asignación de parámetros para las API de REST en API Gateway](rest-api-parameter-mapping.md). Al configurar la solicitud HTTP o de integración de proxy HTTP, asigne la URL del punto de enlace HTTP del backend como el valor de la URI de la solicitud de integración. Por ejemplo, en la API de PetStore, la solicitud de método para obtener una página de mascotas tiene la siguiente URI de la solicitud de integración: ``` http://petstore-demo-endpoint.execute-api.com/petstore/pets ``` Al configurar la integración de Lambda o de proxy de Lambda asigne el nombre de recurso de Amazon (ARN) para invocar la función de Lambda como el valor de la URI de la solicitud de integración. El ARN tiene el siguiente formato: ``` arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations ``` La parte que aparece después de `arn:aws:apigateway:api-region:lambda:path/`, es decir, `/2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations`, corresponde a la ruta de URI de la API REST de la acción de Lambda [Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html). Si utiliza la consola de API Gateway para configurar la integración de Lambda, API Gateway crea el ARN y lo asigna a la URI de integración después de que se le solicite que elija el `lambda-function-name` de una región. Cuando se configura la solicitud de integración con otra acción de servicio de AWS, la URI de la solicitud de integración también es un ARN, de modo similar a la integración con la acción `Invoke` de Lambda. Por ejemplo, en el caso de la integración con la acción [GetBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) de Amazon S3, la URI de la solicitud de integración es un ARN con el siguiente formato: ``` arn:aws:apigateway:api-region:s3:path/{bucket} ``` La URI de la solicitud de integración utiliza la convención de ruta para especificar la acción, donde `{bucket}` es el marcador de posición de un nombre de bucket. También se puede hacer referencia a una acción del servicio de AWS por su nombre. Si se utiliza el nombre de la acción, la URI de la solicitud de integración para la acción `GetBucket` de Amazon S3 se convierte en lo siguiente: ``` arn:aws:apigateway:api-region:s3:action/GetBucket ``` Con la URI de la solicitud de integración basada en la acción, el nombre del bucket (`{bucket}`) se debe especificar en el cuerpo de la solicitud de integración (`{ Bucket: "{bucket}" }`), siguiendo el formato de entrada de la acción `GetBucket`. Para las integraciones de AWS, también debe configurar las [credenciales](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#credentials) para permitir que API Gateway llame a las acciones integradas. Puede crear uno nuevo o bien elegir un rol de IAM existente para que API Gateway llame a la acción y, a continuación, especificar el rol mediante su ARN. A continuación se muestra un ejemplo de este ARN: ``` arn:aws:iam::account-id:role/iam-role-name ``` Este rol de IAM debe contener una política para permitir que se ejecute la acción. También se debe haber declarado API Gateway (en la relación de confianza del rol) como una entidad de confianza para asumir el rol. Estos permisos se pueden conceder en la propia acción. Se conocen como permisos basados en recursos. Para la integración de Lambda, puede llamar a la acción [addPermission](https://docs.aws.amazon.com/lambda/latest/dg/API_AddPermission.html) de Lambda para definir los permisos basados en recursos y, a continuación, establecer `credentials` en null en la solicitud de integración de API Gateway. Hemos analizado los aspectos básicos de la configuración de la integración. La configuración avanzada implica la asignación de los datos de la solicitud de método a los datos de la solicitud de integración. Para obtener más información, consulte [Transformaciones de datos para las API de REST en API Gateway](rest-api-data-transformations.md). # Elegir un tipo de integración de API de API Gateway El tipo de integración de la API se selecciona con arreglo a los tipos de punto de enlace de integración con los que trabaje y al modo en que desea transferir los datos hacia y desde el punto de enlace de integración. Para una función de Lambda, puede tener la integración de proxy de Lambda o la integración personalizada de Lambda. Para un punto de enlace HTTP, puede elegir entre la integración de proxy HTTP o una integración HTTP personalizada. Para una acción del servicio de AWS, dispone de la integración de AWS solo para el tipo que no sea proxy. API Gateway también admite la integración simulada, donde API Gateway actúa como punto de enlace de integración para responder a una solicitud de método. La integración personalizada de Lambda es un caso especial de la integración de AWS, donde el punto de enlace de integración se corresponde con la [acción que invoca las funciones](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) del servicio de Lambda. Mediante programación, puede seleccionar un tipo de integración configurando la propiedad [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type) en el recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). Para la integración de proxy de Lambda, el valor es `AWS_PROXY`. Para la integración personalizada de Lambda y el resto de las integraciones de AWS, el valor es `AWS`. Para la integración de proxy HTTP y la integración HTTP, el valor es `HTTP_PROXY` y `HTTP`, respectivamente. Para la integración simulada, el valor `type` es `MOCK`. La integración de proxy de Lambda admite una configuración de integración simplificada con una única función de Lambda. La configuración es sencilla y puede evolucionar con el backend sin tener que eliminar la configuración existente. Por estas razones, es muy recomendable para la integración con una función de Lambda. En cambio, la integración de Lambda personalizada permite la reutilización de las plantillas de mapeo configuradas para varios puntos de enlace de integración con requisitos similares sobre el formato de los datos de entrada y salida. Esta configuración es más compleja y se recomienda para situaciones de aplicación más avanzadas. Del mismo modo, la integración de proxy HTTP tiene una configuración de integración simplificada y puede evolucionar con el backend sin tener que eliminar la configuración existente. La integración HTTP personalizada resulta más compleja de configurar, pero permite la reutilización de las plantillas de mapeo configuradas para otros puntos de enlace de integración. En la siguiente lista se resumen los tipos de integración admitidos: + `AWS`: este tipo de integración permite a una API exponer acciones del servicio de AWS. En la integración de `AWS`, debe configurar tanto la solicitud de integración como la respuesta de integración y también configurar el mapeo necesario de los datos entre la solicitud de método y la solicitud de integración, y entre la respuesta de integración y la respuesta de método. + `AWS_PROXY`: este tipo de integración permite que se integre un método de la API con la acción de invocación de la función de Lambda a través de una configuración de integración flexible, versátil y simplificada. Esta integración se basa en las interacciones directas entre el cliente y la función de Lambda integrada. Con este tipo de integración, que también se conoce como integración de proxy de Lambda, no tiene que establecer la solicitud de integración ni la respuesta de integración. API Gateway transmite la solicitud entrante del cliente, como entrada, a la función de Lambda del backend. La función de Lambda integrada toma la [entrada de este formato](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format) y analiza la entrada de todos los orígenes disponibles, incluidos los encabezados de solicitudes, las variables de ruta de la URL, los parámetros de cadena de consulta y el cuerpo aplicable. Esta función devuelve un resultado con el siguiente [formato de salida](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format). Este es el tipo de integración recomendable para llamar a la función de Lambda a través de API Gateway y no es aplicable a ninguna otra acción de servicio de AWS, incluidas las acciones de Lambda que no sean la acción que invoca las funciones. + `HTTP`: este tipo de integración permite que una API exponga puntos de enlace de HTTP en el backend. Con la integración `HTTP`, que también se conoce como integración HTTP personalizada, debe configurar tanto la solicitud de integración como la respuesta de integración. Debe establecer la asignación necesaria de los datos entre la solicitud de método y la solicitud de integración, y entre la respuesta de integración y la respuesta de método. + `HTTP_PROXY`: La integración de proxy HTTP permite que un cliente tenga acceso a puntos de enlace HTTP de backend con una configuración de la integración simplificada en un único método de API. No tiene que establecer la solicitud de integración ni la respuesta de integración. API Gateway pasa la solicitud entrante del cliente al punto de enlace HTTP y pasa la respuesta saliente del punto de enlace HTTP al cliente. + `MOCK`: este tipo de integración permite que API Gateway devuelva una respuesta sin enviar la solicitud al backend. Esto es útil en las pruebas de la API, ya que se puede utilizar para probar la configuración de la integración sin incurrir en cargos por utilizar el backend y para permitir el desarrollo colaborativo de una API. En el desarrollo colaborativo, un equipo puede aislar sus esfuerzos de desarrollo configurando simulaciones de los componentes de la API que son propiedad de otros equipos mediante el uso de integraciones `MOCK`. También se utiliza para devolver encabezados relacionados con CORS y garantizar que el método de API permita el acceso a CORS. De hecho, la consola de API Gateway integra el método `OPTIONS` para admitir CORS con una integración simulada. Las [respuestas de gateway](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) son otros ejemplos de integraciones simuladas. # Configuración de una integración de proxy con un recurso de proxy Para configurar una integración de proxy en una API de API Gateway con un [recurso de proxy](api-gateway-method-settings-method-request.md#api-gateway-proxy-resource), realice las tareas siguientes: + Crear un recurso de proxy con la variable de ruta expansiv `{proxy+}`. + Establecer el método `ANY` en el recurso de proxy + Integrar el recurso y el método con un backend mediante el tipo de integración HTTP o Lambda. **nota** Las variables de ruta expansiva, los métodos `ANY` y los tipos de integración de proxy son características independientes, aunque se utilizan normalmente juntas. Puede configurar un método HTTP específico en un recurso expansivo o aplicar tipos de integración distintos de proxy en un recurso de proxy. API Gateway establece determinadas restricciones y limitaciones al manipular métodos con una integración de proxy de Lambda o una integración de proxy HTTP. Para obtener información, consulte [Notas importantes de Amazon API Gateway](api-gateway-known-issues.md). **nota** Cuando se utiliza la integración de proxy con acceso directo, API Gateway devuelve el encabezado predeterminado `Content-Type:application/json` si no se especifica el tipo de contenido de una carga. Un recurso de proxy es más eficaz cuando se integra con un backend que usa la integración de proxy HTTP o la [integración](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) de proxy de Lambda. ## Integración de proxy HTTP con un recurso de proxy La integración de proxy HTTP, designada por `HTTP_PROXY` en la API REST de API Gateway, es para la integración de una solicitud de método con un punto de enlace HTTP del backend. Con este tipo de integración, API Gateway simplemente transmite toda la solicitud y la respuesta entre el frontend y el backend, aunque esto está sujeto a determinadas [restricciones y limitaciones](api-gateway-known-issues.md). **nota** La integración de proxy HTTP admite encabezados y cadenas de consulta con varios valores. Cuando aplica la integración de proxy HTTP a un recurso de proxy, puede configurar la API para que exponga una parte o la totalidad de la jerarquía del punto de enlace del backend HTTP con una sola integración configurada. Supongamos, por ejemplo, que el backend del sitio web está organizado en varias ramas de nodos de árbol desde el nodo raíz (`/site`) como: `/site/a0/a1/.../aN`, `/site/b0/b1/.../bM`, etc. Si integra el método `ANY` en un recurso de proxy de `/api/{proxy+}` con los puntos de enlace del backend con rutas URL de `/site/{proxy}`, una sola solicitud de integración puede admitir todas las operaciones HTTP (GET, POST, etc.) en cualquiera de `[a0, a1, ..., aN, b0, b1, ...bM, ...]`. Si aplica una integración de proxy a un método HTTP específico (por ejemplo, `GET`), en su lugar, la solicitud de integración resultante funcionará con las operaciones especificadas (es decir, `GET`) en cualquiera de los nodos del backend. ## Integración de proxy de Lambda con un recurso de proxy La integración de proxy de Lambda, designada por `AWS_PROXY` en la API REST de API Gateway, es para la integración de una solicitud de método con una función de Lambda en el backend. Con este tipo de integración, API Gateway aplica una plantilla de mapeo predeterminada para enviar toda la solicitud a la función de Lambda y transforma la salida de la función de Lambda en respuestas HTTP. Del mismo modo, puede aplicar la integración de proxy de Lambda a un recurso proxy de `/api/{proxy+}` para configurar una sola integración, si desea que la función de Lambda del backend reaccione individualmente a los cambios que se produzcan en cualquiera de los recursos de la API bajo `/api`. # Configuración de una solicitud de integración de la API mediante la consola de API Gateway La configuración de un método de API define el método y describe sus comportamientos. Para configurar un método, debe especificar un recurso, incluida la raíz ("/"), en el que se expone el método, un método HTTP (`GET`, `POST`, etc.) y la forma en que se integrará con el backend de destino. La solicitud y la respuesta del método especifican el contrato con la aplicación que realiza la llamada, que estipula los parámetros que puede recibir la API y el aspecto que tendrá la respuesta. Los siguientes procedimientos describen cómo utilizar la consola de API Gateway para crear una solicitud de integración. **Topics** + [ ## Configuración de una integración de Lambda ](#how-to-method-settings-console-lambda) + [ ## Configuración de integración de HTTP ](#how-to-method-settings-console-http) + [ ## Configuración de una integración servicios de AWS ](#how-to-method-settings-console-aws) + [ ## Configuración de una integración simulada ](#how-to-method-settings-console-mock) ## Configuración de una integración de Lambda Utilice una integración de función de Lambda para integrar la API con una función de Lambda. A nivel de API, es un tipo de integración de `AWS` si se crea una integración sin proxy o un tipo de integración de `AWS_PROXY` si se crea una integración de proxy. **Configuración de una integración de Lambda** 1. En el panel **Recursos**, elija **Crear método**. 1. En **Tipo de método**, seleccione un método HTTP. 1. En **Tipo de integración**, seleccione **Función Lambda**. 1. Para usar una integración de proxy de Lambda, active la **Integración de proxy de Lambda**. Para obtener más información sobre las integraciones de proxy de Lambda, consulte [Descripción de la integración de proxy de Lambda en API Gateway](set-up-lambda-proxy-integrations.md#api-gateway-create-api-as-simple-proxy). 1. En **Función de Lambda**, ingrese el nombre de la función de Lambda. Si utiliza una función de Lambda en una región diferente a la de su API, seleccione la región en el menú desplegable e ingrese el nombre de la función de Lambda. Si utiliza una función de Lambda entre cuentas, ingrese el ARN de la función. 1. Si desea utilizar el valor predeterminado del tiempo de espera, que es de 29 segundos, mantenga activado el **Tiempo de espera predeterminado**. Para establecer un tiempo de espera personalizado, elija **Tiempo de espera predeterminado** e ingrese un valor de tiempo de espera comprendido entre `50` y `29000` milisegundos. 1. (Opcional) Puede configurar los ajustes de solicitud de método mediante los siguientes menús desplegables. Elija los **Ajustes de solicitud de método** y configure la solicitud de método. Para obtener más información, consulte el paso 3 de [Edición de una solicitud de método de API Gateway en la consola de API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console). También puede configurar los ajustes de solicitud de método después de crear el método. 1. Elija **Crear método**. ## Configuración de integración de HTTP Utilice una integración de HTTP para integrar la API con un punto de conexión HTTP. En el nivel de API, este es el tipo de integración `HTTP`. **Configuración de integración de HTTP** 1. En el panel **Recursos**, elija **Crear método**. 1. En **Tipo de método**, seleccione un método HTTP. 1. Para **Tipo de integración**, elija **HTTP**. 1. Para usar una integración de proxy HTTP, active la **Integración de proxy HTTP**. Para obtener más información acerca de las integraciones de proxy HTTP, consulte [Configurar integraciones de proxy HTTP en API Gateway](setup-http-integrations.md#api-gateway-set-up-http-proxy-integration-on-proxy-resource). 1. En **HTTP method (Método HTTP)**, elija el tipo de método HTTP que más se parezca al método del backend HTTP. 1. En **URL del punto de conexión**, ingrese la dirección URL del backend HTTP que desea que utilice este método. 1. En **Tratamiento de contenido**, seleccione un comportamiento de tratamiento del contenido. 1. Si desea utilizar el valor predeterminado del tiempo de espera, que es de 29 segundos, mantenga activado el **Tiempo de espera predeterminado**. Para establecer un tiempo de espera personalizado, elija **Tiempo de espera predeterminado** e ingrese un valor de tiempo de espera comprendido entre `50` y `29000` milisegundos. 1. (Opcional) Puede configurar los ajustes de solicitud de método mediante los siguientes menús desplegables. Elija los **Ajustes de solicitud de método** y configure la solicitud de método. Para obtener más información, consulte el paso 3 de [Edición de una solicitud de método de API Gateway en la consola de API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console). También puede configurar los ajustes de solicitud de método después de crear el método. 1. Elija **Crear método**. ## Configuración de una integración servicios de AWS Utilice una integración de servicios de AWS para integrar la API directamente con un servicio de AWS. En el nivel de API, este es el tipo de integración `AWS`. Para configura una API de API Gateway, puede hacer lo siguiente: + Crear una nueva función de Lambda. + Configurar un permiso de recurso en la función de Lambda. + Realizar cualquier otra acción del servicio Lambda. Debe elegir el **Servicio de AWS**. **Configuración de una integración de servicios de AWS** 1. En el panel **Recursos**, elija **Crear método**. 1. En **Tipo de método**, seleccione un método HTTP. 1. En **Tipo de integración**, seleccione **Servicio de AWS**. 1. En **AWS Region**, elija la región de AWS que desea que utilice este método para llamar a la acción. 1. En **Servicio de AWS**, elija el servicio de AWS al que desea que llame este método. 1. En **Subdominio de AWS**, ingrese el subdominio que utiliza el servicio de AWS. Normalmente, puede dejarlo en blanco. Algunos servicios de AWS admiten subdominios como parte de los hosts. En la documentación del servicio encontrará la disponibilidad y los detalles, si están disponibles. 1. En **HTTP method (Método HTTP)**, seleccione el tipo de método HTTP correspondiente a la acción. Para el tipo de método HTTP, consulte la documentación de referencia de la API correspondiente al servicio de AWS que eligió en **Servicio de AWS**. 1. En **Tipo de acción**, seleccione **Usar nombre de acción** para usar una acción de la API o **Usar sustitución de ruta** para usar una ruta de recursos personalizada. Para conocer las acciones disponibles y las rutas de recurso personalizadas, consulte la documentación de referencia de la API correspondiente al servicio de AWS que eligió en **Servicio de AWS**. 1. Ingrese un **Nombre de acción** o una **Sustitución de ruta**. 1. En **Rol de ejecución**, ingrese el ARN del rol de IAM que usará el método para llamar a la acción. Para crear un rol de IAM, puede adaptar las instrucciones de [Paso 1: Crear el rol de ejecución del proxy de servicio de AWS](getting-started-aws-proxy.md#getting-started-aws-proxy-add-roles). Especifique una política de acceso con el número de acciones e instrucciones de recursos que desee. Para obtener más información, consulte [Cómo funciona Amazon API Gateway con IAM](security_iam_service-with-iam.md). Para ver la sintaxis de las acciones e instrucciones de recursos, consulte la documentación del servicio de AWS que eligió en **Servicio de AWS**. Para la relación de confianza del rol de IAM, especifique lo siguiente, que permite a API Gateway realizar acciones en nombre de su cuenta de AWS: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ 1. Si desea utilizar el valor predeterminado del tiempo de espera, que es de 29 segundos, mantenga activado el **Tiempo de espera predeterminado**. Para establecer un tiempo de espera personalizado, elija **Tiempo de espera predeterminado** e ingrese un valor de tiempo de espera comprendido entre `50` y `29000` milisegundos. 1. (Opcional) Puede configurar los ajustes de solicitud de método mediante los siguientes menús desplegables. Elija los **Ajustes de solicitud de método** y configure la solicitud de método. Para obtener más información, consulte el paso 3 de [Edición de una solicitud de método de API Gateway en la consola de API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console). También puede configurar los ajustes de solicitud de método después de crear el método. 1. Elija **Crear método**. ## Configuración de una integración simulada Use una integración simulada si desea que API Gateway actúe como backend y devuelva respuestas estáticas. En el nivel de API, este es el tipo de integración `MOCK`. Normalmente, puede usar la integración `MOCK` si la API aún no es definitiva, pero desea generar respuestas de API para permitir que los equipos dependientes realicen pruebas. En el método `OPTION`, API Gateway establece la integración `MOCK` como predeterminada para devolver encabezados que habilitan CORS para el recurso de la API que se aplicó. **Configuración de una integración simulada** 1. En el panel **Recursos**, elija **Crear método**. 1. En **Tipo de método**, seleccione un método HTTP. 1. Para **Tipo de integración**, elija **Simulación**. 1. (Opcional) Puede configurar los ajustes de solicitud de método mediante los siguientes menús desplegables. Elija los **Ajustes de solicitud de método** y configure la solicitud de método. Para obtener más información, consulte el paso 3 de [Edición de una solicitud de método de API Gateway en la consola de API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console). También puede configurar los ajustes de solicitud de método después de crear el método. 1. Elija **Crear método**. # Configuración de una respuesta de integración en API Gateway Para una integración que no sea de proxy, debe configurar al menos una respuesta de integración, y convertirla en la respuesta predeterminada, para pasar el resultado que devuelve el backend al cliente. Puede optar por pasar el resultado como está o transformar los datos de la respuesta de integración en los datos de la respuesta de método si ambos tienen formatos diferentes. Para una integración de proxy, API Gateway pasa automáticamente la salida del backend al cliente como una respuesta HTTP. No debe configurar la respuesta de integración ni la respuesta del método. Para configurar una respuesta de integración, debe llevar a cabo las siguientes tareas obligatorias y opcionales: 1. Especifique el código de estado HTTP de la respuesta del método a la que se asignan los datos de la respuesta de integración. Esto es necesario. 1. Defina una expresión regular para seleccionar que la salida del backend esté representada por esta respuesta de integración. Si lo deja vacío, la respuesta será la respuesta predeterminada que se utiliza para detectar las respuestas que no se hayan configurado aún. 1. Si es necesario, declare mapeos compuestos de pares de clave-valor para asignar los parámetros de la respuesta de integración especificados a los parámetros de una respuesta de método determinada. 1. Si es necesario, añada plantillas de mapeo de cuerpo para transformar las cargas de una respuesta de integración determinada en las cargas de la respuesta de método especificada. 1. Si es necesario, especifique cómo administrar la conversión de tipo para una carga binaria. Una respuesta de integración es una respuesta HTTP que encapsula la respuesta del backend. Para un punto de enlace HTTP, la respuesta del backend es una respuesta HTTP. El código de estado de la respuesta de integración puede tomar el código de estado que devuelve el backend, y el cuerpo de la respuesta de integración es la carga que devuelve el backend. Para un punto de enlace Lambda, la respuesta del backend es la salida que devuelve la función de Lambda. Con la integración de Lambda, la salida de la función de Lambda se devuelve como una respuesta `200 OK`. La carga puede contener el resultado como datos JSON, incluida una cadena JSON o un objeto JSON, o un mensaje de error como un objeto JSON. Puede asignar una expresión regular a la propiedad [selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern) para asignar una respuesta de error a la respuesta de error HTTP adecuada. Para obtener más información acerca de la respuesta de error de una función de Lambda, consulte [Gestionar los errores de Lambda en API Gateway](handle-errors-in-lambda-integration.md). Con la integración de proxy de Lambda, la función de Lambda debe devolver una salida con el siguiente formato: ``` { statusCode: "...", // a valid HTTP status code headers: { custom-header: "..." // any API-specific custom header }, body: "...", // a JSON string. isBase64Encoded: true|false // for binary support } ``` No es necesario asignar la respuesta de la función de Lambda a su respuesta HTTP adecuada. Para devolver el resultado al cliente, configure la respuesta de integración para pasar la respuesta del punto de enlace como está a la correspondiente respuesta de método. También puede asignar los datos de la respuesta del punto de enlace a los datos de la respuesta de método. Entre los datos de respuesta que se pueden asignar se incluyen el código de estado de la respuesta, los parámetros de encabezado de la respuesta y el cuerpo de la respuesta. Si no se define ninguna respuesta de método para el código de estado devuelto, API Gateway devuelve un error 500. Para obtener más información, consulte [Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway](apigateway-override-request-response-parameters.md). # Integraciones de Lambda para las API de REST en API Gateway Puede integrar un método de API con una función de Lambda mediante la integración de proxy de Lambda o la integración de Lambda que no sea de proxy (personalizada). En la integración de proxy de Lambda, la configuración requerida es sencilla. Establezca el método HTTP de la integración en POST, la URI del punto de conexión de la integración en el ARN de la acción de invocación de una función de Lambda específica y otorgue permisos a API Gateway para llamar a la función de Lambda en su nombre. En la integración de Lambda que no sea de proxy, además de los pasos de configuración de integración de proxy, también debe especificar cómo se asignan los datos entrantes a la solicitud de integración y cómo se asignan los datos resultantes de respuesta de la integración a la respuesta de método. **Topics** + [ # Integraciones de proxy de Lambda en API Gateway ](set-up-lambda-proxy-integrations.md) + [ # Configuración de integraciones de Lambda personalizadas en API Gateway ](set-up-lambda-custom-integrations.md) + [ # Configurar la invocación asíncrona de la función de Lambda de backend ](set-up-lambda-integration-async.md) + [ # Gestionar los errores de Lambda en API Gateway ](handle-errors-in-lambda-integration.md) # Integraciones de proxy de Lambda en API Gateway En la siguiente sección se muestra cómo utilizar una integración de proxy de Lambda. **Topics** + [ ## Descripción de la integración de proxy de Lambda en API Gateway ](#api-gateway-create-api-as-simple-proxy) + [ ## Compatibilidad con encabezados de varios valores y parámetros de cadenas de consulta ](#apigateway-multivalue-headers-and-parameters) + [ ## Formato de entrada de una función de Lambda para la integración de proxy ](#api-gateway-simple-proxy-for-lambda-input-format) + [ ## Formato de salida de una función de Lambda para la integración de proxy ](#api-gateway-simple-proxy-for-lambda-output-format) + [ # Configuración de una integración de proxy de Lambda para API Gateway mediante la AWS CLI ](set-up-lambda-proxy-integration-using-cli.md) + [ # Configuración de un recurso de proxy con la integración de proxy de Lambda con una definición OpenAPI ](api-gateway-set-up-lambda-proxy-integration-on-proxy-resource.md) ## Descripción de la integración de proxy de Lambda en API Gateway La integración de proxy de Lambda de Amazon API Gateway es un mecanismo sencillo, potente y ágil para desarrollar una API con la configuración de un solo método de API. La integración de proxy de Lambda permite al cliente llamar a una única función de Lambda en el backend. La función obtiene acceso a muchos recursos o características de otros servicios de AWS, incluidas las llamadas a otras funciones de Lambda. En la integración de proxy de Lambda, cuando un cliente envía una solicitud de API, API Gateway pasa a la función de Lambda integrada un [evento de objeto](#api-gateway-simple-proxy-for-lambda-input-format), salvo que no se conserve el orden de los parámetros de la solicitud. Estos [datos de la solicitud](#api-gateway-simple-proxy-for-lambda-input-format) incluyen los encabezados de solicitud, los parámetros de cadena de consulta, las variables de ruta de la URL, la carga y los datos de configuración de la API. Los datos de configuración pueden incluir el nombre de la etapa de implementación actual, las variables de la etapa, la identidad del usuario o el contexto de autorización (si lo hubiera). La función de Lambda del backend analiza los datos de la solicitud entrante para determinar la respuesta que devuelve. Para que API Gateway transmita la salida de Lambda como la respuesta de la API al cliente, la función de Lambda debe devolver el resultado en [este formato](#api-gateway-simple-proxy-for-lambda-output-format). Dado que API Gateway no interviene mucho entre el cliente y la función de Lambda del backend para la integración de proxy de Lambda, el cliente y la función de Lambda integrada pueden adaptarse a los cambios de cada uno sin interrumpir la configuración de integración existente de la API. Para habilitar esto, el cliente debe seguir los protocolos de aplicación promulgados por la función de Lambda del backend. Puede configurar una integración de proxy de Lambda para cualquier método de API. Sin embargo, una integración de proxy de Lambda es más potente cuando se configura para un método de API que implica un recurso de proxy genérico. El recurso de proxy genérico se puede indicar mediante una variable especial de ruta basada en plantilla de `{proxy+}`, el marcador de posición del método catch-all `ANY` o ambos. El cliente puede transmitir la entrada a la función de Lambda del backend en la solicitud entrante según lo soliciten los parámetros o la carga aplicable. Los parámetros de solicitud incluyen encabezados, variables de ruta de la URL, parámetros de cadenas de consulta y la carga aplicable. La función de Lambda integrada verifica todas las fuentes de entrada antes de procesar la solicitud y de responder al cliente con mensajes de error importantes si falta alguna de las entradas requeridas. Al llamar a un método de API integrado con el método HTTP genérico de `ANY` y el recurso genérico de `{proxy+}`, el cliente envía una solicitud con un método HTTP específico en lugar de `ANY`. El cliente también especifica una ruta de URL específica en lugar de `{proxy+}` e incluye cualquier encabezado, parámetro de cadena de consulta o una carga aplicable. En la siguiente lista se resumen los comportamientos de tiempo de ejecución de los diferentes métodos de API con la integración de proxy de Lambda: + `ANY /{proxy+}`: el cliente debe elegir un método HTTP específico, debe establecer una jerarquía de ruta de recursos específica y puede establecer cualquier encabezado, parámetro de cadena de consulta y carga aplicable para transmitir los datos como entrada a la función de Lambda integrada. + `ANY /res`: el cliente debe elegir un método HTTP específico y puede establecer cualquier encabezado, parámetro de cadena de consulta y carga aplicable para transmitir los datos como entrada a la función de Lambda integrada. + `GET|POST|PUT|... /{proxy+}`: el cliente puede establecer una jerarquía de ruta de recursos específica, cualquier encabezado, parámetro de cadena de consulta y carga aplicable para transmitir los datos como entrada a la función de Lambda integrada. + `GET|POST|PUT|... /res/{path}/...`: el cliente debe elegir un segmento de ruta específico (para la variable `{path}`) y puede establecer cualquier encabezado de solicitud, parámetro de cadena de consulta y carga aplicable para transmitir los datos de entrada a la función de Lambda integrada. + `GET|POST|PUT|... /res`: el cliente puede elegir cualquier encabezado de solicitud, parámetro de cadena de consulta y carga aplicable para transmitir los datos de entrada a la función de Lambda integrada. Tanto el recurso de proxy de `{proxy+}` como el recurso personalizado de `{custom}` se expresan como variables de ruta basada en plantilla. Sin embargo, `{proxy+}` puede hacer referencia a cualquier recurso en una jerarquía de ruta, mientras que `{custom}` se refiere únicamente a un segmento de ruta específico. Por ejemplo, una tienda de comestibles podría organizar un inventario de productos en línea por nombres de departamento, categorías de productos y tipos de productos. El sitio web de la tienda de comestibles puede entonces representar los productos disponibles con las siguientes variables de ruta basada en plantilla para los recursos personalizados: `/{department}/{produce-category}/{product-type}`. Por ejemplo, las manzanas están representadas con `/produce/fruit/apple` y las zanahorias con `/produce/vegetables/carrot`. También puede utilizar `/{proxy+}` para representar a cualquier departamento, cualquier categoría de producto o cualquier tipo de producto que un cliente puede buscar mientras realiza sus compras en la tienda en línea. Por ejemplo, `/{proxy+}` puede hacer referencia a cualquiera de los siguientes elementos: + `/produce` + `/produce/fruit` + `/produce/vegetables/carrot` Para que los clientes puedan buscar cualquier producto disponible, su categoría de producto y el departamento asociado en la tienda, puede exponer un único método de `GET /{proxy+}` con permisos de solo lectura. Del mismo modo, para permitir que un supervisor actualice el inventario del departamento `produce`, puede configurar otro método único de `PUT /produce/{proxy+}` con permisos de lectura y escritura. Para permitir que un cajero actualice el total de unidades de una verdura, puede configurar un método `POST /produce/vegetables/{proxy+}` con permisos de lectura y escritura. Para que el gerente de una tienda pueda realizar cualquier acción posible en cualquier producto disponible, el desarrollador de la tienda en línea puede exponer el método `ANY /{proxy+}` con permisos de lectura y escritura. En cualquier caso, en el tiempo de ejecución, el cliente o el empleado debe seleccionar un producto específico de un tipo determinado en un departamento elegido o en un departamento específico. Para obtener más información acerca de la configuración de las integraciones del proxy de API Gateway, consulte [Configuración de una integración de proxy con un recurso de proxy](api-gateway-set-up-simple-proxy.md). La integración del proxy requiere que el cliente tenga un conocimiento más detallado de los requisitos del backend. Por lo tanto, para garantizar un óptimo rendimiento de la aplicación y experiencia del usuario, el desarrollador del backend debe comunicar con claridad al desarrollador del cliente los requisitos del backend y proporcionar un mecanismo de comentarios de errores sólido cuando los requisitos no se cumplan. ## Compatibilidad con encabezados de varios valores y parámetros de cadenas de consulta API Gateway ahora es compatible con varios encabezados y parámetros de cadena de consulta que tengan el mismo nombre. Los encabezados de varios valores y los encabezados y parámetros de un solo valor se pueden combinar en las mismas solicitudes y respuestas. Para obtener más información, consulte [Formato de entrada de una función de Lambda para la integración de proxy](#api-gateway-simple-proxy-for-lambda-input-format) y [Formato de salida de una función de Lambda para la integración de proxy](#api-gateway-simple-proxy-for-lambda-output-format). ## Formato de entrada de una función de Lambda para la integración de proxy Con la integración de proxy de Lambda, API Gateway asigna toda la solicitud de cliente al parámetro de entrada `event` de la función de Lambda del backend. En el siguiente ejemplo, se muestra la estructura de un evento que API Gateway envía a una integración de proxy de Lambda. En este ejemplo, suponemos que la invocación a API Gateway fue la siguiente: ``` curl 'https://a1b2c3.execute-api.us-east-1.amazonaws.com/my/path?parameter1=value1¶meter2=value1¶meter2=value2¶meter3=value1,value2' -H 'header1: value1' -H 'header2: value1' -H 'header2: value2' -H 'header3: value1,value2' ``` El resultado es similar al siguiente: ``` { "resource": "/my/path", "path": "/my/path", "httpMethod": "GET", "headers": { "header1": "value1", "header2": "value2", "header3": "value1,value2" }, "multiValueHeaders": { "header1": ["value1"], "header2": ["value1","value2"], "header3": ["value1,value2"] }, "queryStringParameters": { "parameter1": "value1", "parameter2": "value2", "parameter3": "value1,value2" }, "multiValueQueryStringParameters": { "parameter1": ["value1"], "parameter2": ["value1","value2"], "parameter3": ["value1,value2"] }, "requestContext": { "accountId": "123456789012", "apiId": "id", "authorizer": { "claims": null, "scopes": null }, "domainName": "id.execute-api.us-east-1.amazonaws.com", "domainPrefix": "id", "extendedRequestId": "request-id", "httpMethod": "GET", "identity": { "accessKey": null, "accountId": null, "caller": null, "cognitoAuthenticationProvider": null, "cognitoAuthenticationType": null, "cognitoIdentityId": null, "cognitoIdentityPoolId": null, "principalOrgId": null, "sourceIp": "IP", "user": null, "userAgent": "user-agent", "userArn": null, "clientCert": { "clientCertPem": "CERT_CONTENT", "subjectDN": "www.example.com", "issuerDN": "Example issuer", "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", "validity": { "notBefore": "May 28 12:30:02 2019 GMT", "notAfter": "Aug 5 09:36:04 2021 GMT" } } }, "path": "/my/path", "protocol": "HTTP/1.1", "requestId": "id=", "requestTime": "04/Mar/2020:19:15:17 +0000", "requestTimeEpoch": 1583349317135, "resourceId": null, "resourcePath": "/my/path", "stage": "$default" }, "pathParameters": null, "stageVariables": null, "body": "Hello from Lambda!", "isBase64Encoded": false } ``` **nota** En la entrada: La clave `headers` solo puede contener encabezados de un solo valor. La clave `multiValueHeaders` puede contener encabezados de varios valores y encabezados de un solo valor. Si especifica valores para `headers` y `multiValueHeaders`, API Gateway los combina en una sola lista. Si se especifica el mismo par de clave-valor en ambos, solo los valores de `multiValueHeaders` aparecerán en la lista combinada. En la entrada a la función de Lambda de backend, el objeto `requestContext` es un mapa de pares de clave-valor. En cada par, la clave es el nombre de una propiedad de la variable [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference) y el valor es el valor de esa propiedad. API Gateway podría agregar nuevas claves al mapa. En función de las características habilitadas, el mapa `requestContext` puede variar de API en API. Por ejemplo, en el ejemplo anterior, no se especifica ningún tipo de autorización, por lo que no hay propiedades `$context.authorizer.*` o `$context.identity.*` presentes. Cuando se especifica un tipo de autorización, esto hace que API Gateway transfiera información del usuario autorizado al punto de conexión de integración en un objeto `requestContext.identity` tal y como se indica a continuación: + Cuando el tipo de autorización es `AWS_IAM`, la información del usuario autorizado incluye propiedades `$context.identity.*`. + Cuando el tipo de autorización es `COGNITO_USER_POOLS` (autorizador de Amazon Cognito), la información del usuario autorizado incluye las propiedades `$context.identity.cognito*` y `$context.authorizer.claims.*`. + Cuando el tipo de autorización es `CUSTOM` (autorizador de Lambda), la información del usuario autorizado incluye las propiedades `$context.authorizer.principalId` y otras propiedades `$context.authorizer.*` aplicables. ## Formato de salida de una función de Lambda para la integración de proxy Con la integración de proxy de Lambda, API Gateway requiere que la función de Lambda del backend devuelva la salida de acuerdo con el siguiente formato JSON: ``` { "isBase64Encoded": true|false, "statusCode": httpStatusCode, "headers": { "headerName": "headerValue", ... }, "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... }, "body": "..." } ``` En la salida: + Las claves `headers` y `multiValueHeaders` pueden no estar especificadas si no se van a devolver más encabezados de respuesta. + La clave `headers` solo puede contener encabezados de un solo valor. + La clave `multiValueHeaders` puede contener encabezados de varios valores y encabezados de un solo valor. Puede utilizar la clave `multiValueHeaders` para especificar todos los encabezados adicionales, incluidos los que solo contienen un valor. + Si especifica valores para `headers` y `multiValueHeaders`, API Gateway los combina en una sola lista. Si se especifica el mismo par de clave-valor en ambos, solo los valores de `multiValueHeaders` aparecerán en la lista combinada. Para habilitar CORS para la integración de proxy de Lambda, debe agregar `Access-Control-Allow-Origin:domain-name` a la salida `headers`. `domain-name` puede ser `*` para cualquier nombre de dominio. La salida `body` se serializa en el frontend como la carga de respuesta del método. Si `body` es un blob binario, puede codificarlo como una cadena codificada en Base64 estableciendo `isBase64Encoded` en `true` y configurando `*/*` como **Binary Media Type (Tipo de medio binario)**. De lo contrario, puede establecerlo en `false` o dejarlo sin especificar. **nota** Para obtener más información acerca de cómo habilitar la compatibilidad con datos binarios, consulte [Habilitar la compatibilidad con datos binarios mediante la consola de API Gateway](api-gateway-payload-encodings-configure-with-console.md). Para ver una función de Lambda de ejemplo, consulte [Devolución de medios binarios desde una integración de proxy de Lambda en API Gateway](lambda-proxy-binary-media.md). Si la salida de la función tiene un formato diferente, API Gateway devuelve una respuesta de error `502 Bad Gateway`. Para devolver una respuesta en una función de Lambda de Node.js, puede utilizar comandos como los siguientes: + Para devolver un resultado correcto, llame a `callback(null, {"statusCode": 200, "body": "results"})`. + Para producir una excepción, llame a `callback(new Error('internal server error'))`. + En caso de que se produzca un error del lado del cliente (por ejemplo, si falta un parámetro necesario), puede llamar a `callback(null, {"statusCode": 400, "body": "Missing parameters of ..."})` para devolver el error sin iniciar una excepción. En una función de Lambda de `async` de Node.js, la sintaxis correspondiente sería: + Para devolver un resultado correcto, llame a `return {"statusCode": 200, "body": "results"}`. + Para producir una excepción, llame a `throw new Error("internal server error")`. + En caso de que se produzca un error del lado del cliente (por ejemplo, si falta un parámetro necesario), puede llamar a `return {"statusCode": 400, "body": "Missing parameters of ..."}` para devolver el error sin iniciar una excepción. # Configuración de una integración de proxy de Lambda para API Gateway mediante la AWS CLI En esta sección mostramos cómo configurar una API con la integración de proxy de Lambda mediante la AWS CLI. Para obtener instrucciones detalladas acerca de cómo utilizar la consola de API Gateway para configurar un recurso de proxy con la integración de proxy de Lambda, consulte [Tutorial: Creación de una API de REST con una integración de proxy de Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md). Como ejemplo, utilizaremos la siguiente función de Lambda de muestra como el backend de la API: ``` export const handler = async(event, context) => { console.log('Received event:', JSON.stringify(event, null, 2)); var res ={ "statusCode": 200, "headers": { "Content-Type": "*/*" } }; var greeter = 'World'; if (event.greeter && event.greeter!=="") { greeter = event.greeter; } else if (event.body && event.body !== "") { var body = JSON.parse(event.body); if (body.greeter && body.greeter !== "") { greeter = body.greeter; } } else if (event.queryStringParameters && event.queryStringParameters.greeter && event.queryStringParameters.greeter !== "") { greeter = event.queryStringParameters.greeter; } else if (event.multiValueHeaders && event.multiValueHeaders.greeter && event.multiValueHeaders.greeter != "") { greeter = event.multiValueHeaders.greeter.join(" and "); } else if (event.headers && event.headers.greeter && event.headers.greeter != "") { greeter = event.headers.greeter; } res.body = "Hello, " + greeter + "!"; return res }; ``` Si se compara con la configuración de la integración personalizada de Lambda en [Configuración de integraciones de Lambda personalizadas en API Gateway](set-up-lambda-custom-integrations.md), la entrada de esta función de Lambda se puede expresar en los parámetros de la solicitud y en el cuerpo. Tiene más libertad para permitir al cliente transferir los mismos datos de entrada. En este caso el cliente puede transferir el nombre de greeter como un parámetro de cadena de consulta, un encabezado o una propiedad del cuerpo. La función también puede admitir la integración de Lambda personalizada. La configuración de la API es más sencilla. No se configura ninguna respuesta de método ni de integración. **Para configurar una integración de proxy de Lambda mediante la AWS CLI** 1. Utilice el siguiente comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) para crear una API privada: ``` aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)' ``` El resultado será similar al siguiente: ``` { "name": "HelloWorldProxy (AWS CLI)", "id": "te6si5ach7", "rootResourceId" : "krznpq9xpg", "createdDate": 1508461860 } ``` En este ejemplo, se utiliza el `id` de API (`te6si5ach7`) y el `rootResourceId` (`krznpq9xpg`). 1. Utilice el siguiente comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) para crear un [recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) de `/greeting` de API Gateway: ``` aws apigateway create-resource \ --rest-api-id te6si5ach7 \ --parent-id krznpq9xpg \ --path-part {proxy+} ``` El resultado será similar al siguiente: ``` { "path": "/{proxy+}", "pathPart": "{proxy+}", "id": "2jf6xt", "parentId": "krznpq9xpg" } ``` Debe usar el valor `id` del recurso `{proxy+}` (`2jf6xt`) para crear un método en el recurso `/{proxy+}` en el siguiente paso. 1. Utilice el siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) para crear una solicitud de método `ANY` de `ANY /{proxy+}`: ``` aws apigateway put-method --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method ANY \ --authorization-type "NONE" ``` El resultado será similar al siguiente: ``` { "apiKeyRequired": false, "httpMethod": "ANY", "authorizationType": "NONE" } ``` Este método de API permite al cliente recibir o enviar saludos de la función de Lambda al backend. 1. Utilice el siguiente comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) para configurar la integración del método `ANY /{proxy+}` con una función de Lambda denominada `HelloWorld`. Esta función responde a la solicitud con un mensaje de `"Hello, {name}!"`, si se proporciona el parámetro `greeter`, o bien `"Hello, World!"`, si no se ha establecido el parámetro de cadena de consulta. ``` aws apigateway put-integration \ --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method ANY \ --type AWS_PROXY \ --integration-http-method POST \ --uri arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:HelloWorld/invocations \ --credentials arn:aws:iam::123456789012:role/apigAwsProxyRole ``` **importante** Para las integraciones Lambda, debe utilizar el método HTTP de `POST` para la solicitud de integración, según la [especificación de la acción del servicio de Lambda para las invocaciones de funciones](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). El rol de IAM de `apigAwsProxyRole` debe tener políticas que permitan al servicio `apigateway` invocar funciones Lambda. Para obtener más información sobre los permisos de IAM, consulte [Modelo de permisos de API Gateway para invocar una API](permissions.md#api-gateway-control-access-iam-permissions-model-for-calling-api). El resultado será similar al siguiente: ``` { "passthroughBehavior": "WHEN_NO_MATCH", "cacheKeyParameters": [], "uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:1234567890:function:HelloWorld/invocations", "httpMethod": "POST", "cacheNamespace": "vvom7n", "credentials": "arn:aws:iam::1234567890:role/apigAwsProxyRole", "type": "AWS_PROXY" } ``` En lugar de proporcionar un rol de IAM para `credentials`, puede utilizar el comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) para agregar permisos basados en recursos. Esto es lo que hace la consola de API Gateway. 1. Utilice el siguiente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) para implementar la API en una etapa `test`: ``` aws apigateway create-deployment \ --rest-api-id te6si5ach7 \ --stage-name test ``` 1. Pruebe la API mediante los siguientes comandos cURL en un terminal. Llame a la API con el parámetro de cadena de consulta de `?greeter=jane`: ``` curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=jane' ``` Llame a la API con un parámetro de encabezado de `greeter:jane`: ``` curl -X GET https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \ -H 'content-type: application/json' \ -H 'greeter: jane' ``` Llame a la API con un cuerpo de `{"greeter":"jane"}`: ``` curl -X POST https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \ -H 'content-type: application/json' \ -d '{ "greeter": "jane" }' ``` En todos estos casos, la salida es una respuesta 200 con el siguiente cuerpo de respuesta: ``` Hello, jane! ``` # Configuración de un recurso de proxy con la integración de proxy de Lambda con una definición OpenAPI Para configurar un recurso de proxy con el tipo de integración de proxy de Lambda, cree un recurso de API con un parámetro de ruta expansiva (por ejemplo, `/parent/{proxy+}`) e integre este recurso con un backend de funciones Lambda (por ejemplo, `arn:aws:lambda:us-west-2:123456789012:function:SimpleLambda4ProxyResource`) en el método `ANY`. El parámetro de ruta expansiva debe estar al final de la ruta del recurso de la API. Al igual que con un recurso que no es de proxy, puede configurar el recurso de proxy mediante la consola de API Gateway importando un archivo de definición de OpenAPI o llamando directamente a la API REST de API Gateway. El siguiente archivo de definición de API de OpenAPI muestra un ejemplo de una API con un recurso de proxy que se integra con la función de Lambda denominada `SimpleLambda4ProxyResource`. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-09-12T17:50:37Z", "title": "ProxyIntegrationWithLambda" }, "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" } }, "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations", "passthroughBehavior": "when_no_match", "httpMethod": "POST", "cacheNamespace": "roq9wj", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "aws_proxy" } } } }, "servers": [ { "url": "https://gy415nuibc.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/testStage" } } } ] } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-09-12T17:50:37Z", "title": "ProxyIntegrationWithLambda" }, "host": "gy415nuibc.execute-api.us-east-1.amazonaws.com", "basePath": "/testStage", "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" } }, "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations", "passthroughBehavior": "when_no_match", "httpMethod": "POST", "cacheNamespace": "roq9wj", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "aws_proxy" } } } } } ``` ------ Con la integración de proxy de Lambda, API Gateway asigna en tiempo de ejecución una solicitud entrante en el parámetro de entrada `event` de la función de Lambda. La entrada incluye el método de solicitud, la ruta, los encabezados, todos los parámetros de cadena de consulta, todas las cargas, el contexto asociado y todas las variables de etapa definidas. El formato de entrada se explica en [Formato de entrada de una función de Lambda para la integración de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). Para que API Gateway asigne la salida de Lambda a respuestas HTTP correctamente, la función de Lambda debe producir el resultado en el formato que se describe en [Formato de salida de una función de Lambda para la integración de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format). Con la integración de proxy de Lambda de un recurso de proxy a través del método `ANY`, la función de Lambda del backend actúa como el controlador de eventos de todas las solicitudes a través del recurso de proxy. Por ejemplo, para registrar patrones de tráfico, puede hacer que el dispositivo móvil envíe la información de ubicación del país, la ciudad, la calle y el edificio enviando una solicitud con `/state/city/street/house` en la ruta URL del recurso de proxy. La función de Lambda del backend puede analizar la ruta URL e insertar tuplas de ubicación en una tabla de DynamoDB. # Configuración de integraciones de Lambda personalizadas en API Gateway Para mostrar cómo configurar la integración personalizada de Lambda, o sin proxy, creamos una API de API Gateway para exponer el método `GET /greeting?greeter={name}` para invocar una función de Lambda. Utilice uno de los siguientes ejemplos de funciones de Lambda para su API. Utilice uno de los siguientes ejemplos de funciones de Lambda: ------ #### [ Node.js ] ``` 'use strict'; var days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']; var times = ['morning', 'afternoon', 'evening', 'night', 'day']; export const handler = async(event) => { console.log(event); // Parse the input for the name, city, time and day property values let name = event.name === null || event.name === undefined || event.name === "" ? 'you' : event.name; let city = event.city === undefined ? 'World' : event.city; let time = times.indexOf(event.time)<0 ? 'day' : event.time; let day = days.indexOf(event.day)<0 ? null : event.day; // Generate a greeting let greeting = 'Good ' + time + ', ' + name + ' of ' + city + '. '; if (day) greeting += 'Happy ' + day + '!'; // Log the greeting to CloudWatch console.log('Hello: ', greeting); // Return a greeting to the caller return greeting; }; ``` ------ #### [ Python ] ``` import json def lambda_handler(event, context): print(event) res = { "statusCode": 200, "headers": { "Content-Type": "*/*" } } if event['greeter'] == "": res['body'] = "Hello, World" elif (event['greeter']): res['body'] = "Hello, " + event['greeter'] + "!" else: raise Exception('Missing the required greeter parameter.') return res ``` ------ La función responde con un mensaje de `"Hello, {name}!"` si el valor del parámetro `greeter` es una cadena no vacía. Si el valor `"Hello, World!"` es una cadena vacía, devuelve un mensaje de `greeter`. La función devuelve un mensaje de error de `"Missing the required greeter parameter."` si el parámetro greeter no se ha establecido en la solicitud entrante. Asignamos un nombre a la función `HelloWorld`. Puede crearla en la consola de Lambda o mediante la AWS CLI. En esta sección, hacemos referencia a esta función mediante los siguientes ARN: ``` arn:aws:lambda:us-east-1:123456789012:function:HelloWorld ``` Una vez establecida la función de Lambda en el backend, proceda a configurar la API. **Para configurar la integración personalizada de Lambda mediante la AWS CLI.** 1. Utilice el siguiente comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) para crear una API privada: ``` aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)' ``` El resultado será similar al siguiente: ``` { "name": "HelloWorld (AWS CLI)", "id": "te6si5ach7", "rootResourceId" : "krznpq9xpg", "createdDate": 1508461860 } ``` En este ejemplo, se utiliza el `id` de API ( `te6si5ach7`) y el `rootResourceId` (`krznpq9xpg`). 1. Utilice el siguiente comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) para crear un [recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) de `/greeting` de API Gateway: ``` aws apigateway create-resource \ --rest-api-id te6si5ach7 \ --parent-id krznpq9xpg \ --path-part greeting ``` El resultado será similar al siguiente: ``` { "path": "/greeting", "pathPart": "greeting", "id": "2jf6xt", "parentId": "krznpq9xpg" } ``` Debe usar el valor `id` del recurso `greeting` (`2jf6xt`) para crear un método en el recurso `/greeting` en el siguiente paso. 1. Utilice el siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) para crear una solicitud de método de API de `GET /greeting?greeter={name}`: ``` aws apigateway put-method --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method GET \ --authorization-type "NONE" \ --request-parameters method.request.querystring.greeter=false ``` El resultado será similar al siguiente: ``` { "apiKeyRequired": false, "httpMethod": "GET", "authorizationType": "NONE", "requestParameters": { "method.request.querystring.greeter": false } } ``` Este método de API permite al cliente recibir saludos de la función de Lambda al backend. El parámetro `greeter` es opcional, ya que el backend debería administrar un intermediario anónimo o bien un intermediario identificado. 1. Utilice el siguiente comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) para configurar la respuesta `200 OK` a la solicitud de método de `GET /greeting?greeter={name}`: ``` aws apigateway put-method-response \ --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method GET \ --status-code 200 ``` 1. Utilice el siguiente comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) para configurar la integración del método `GET /greeting?greeter={name}` con una función de Lambda denominada `HelloWorld`. Esta función responde a la solicitud con un mensaje de `"Hello, {name}!"`, si se proporciona el parámetro `greeter`, o bien `"Hello, World!"`, si no se ha establecido el parámetro de cadena de consulta. ``` aws apigateway put-integration \ --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method GET \ --type AWS \ --integration-http-method POST \ --uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations \ --request-templates '{"application/json":"{\"greeter\":\"$input.params('greeter')\"}"}' \ --credentials arn:aws:iam::123456789012:role/apigAwsProxyRole ``` La plantilla de mapeo proporcionada aquí traslada el parámetro de cadena de consulta `greeter` a la propiedad `greeter` de la carga de JSON. Esto es necesario porque la entrada a una función de Lambda se debe expresar en el cuerpo. **importante** Para las integraciones Lambda, debe utilizar el método HTTP de `POST` para la solicitud de integración, según la [especificación de la acción del servicio de Lambda para las invocaciones de funciones](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). El parámetro `uri` es el ARN de la acción que invoca las funciones. El resultado será similar al siguiente: ``` { "passthroughBehavior": "WHEN_NO_MATCH", "cacheKeyParameters": [], "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations", "httpMethod": "POST", "requestTemplates": { "application/json": "{\"greeter\":\"$input.params('greeter')\"}" }, "cacheNamespace": "krznpq9xpg", "credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole", "type": "AWS" } ``` El rol de IAM de `apigAwsProxyRole` debe tener políticas que permiten al servicio `apigateway` invocar funciones de Lambda. En lugar de proporcionar un rol de IAM para `credentials`, puede llamar al comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) para agregar permisos basados en recursos. De este modo es como la consola de API Gateway agrega estos permisos. 1. Utilice el siguiente comando [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html) para configurar la respuesta de integración y pasar el resultado de la función de Lambda al cliente como respuesta del método `200 OK`: ``` aws apigateway put-integration-response \ --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method GET \ --status-code 200 \ --selection-pattern "" ``` Si se establece el patrón de selección en una cadena vacía, la respuesta `200 OK` es la opción predeterminada. El resultado será similar al siguiente: ``` { "selectionPattern": "", "statusCode": "200" } ``` 1. Utilice el siguiente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) para implementar la API en una etapa `test`: ``` aws apigateway create-deployment \ --rest-api-id te6si5ach7 \ --stage-name test ``` 1. Pruebe la API mediante el siguiente comando cURL en un terminal: ``` curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=me' \ -H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751' ``` # Configurar la invocación asíncrona de la función de Lambda de backend En la integración de Lambda no de proxy (personalizada), se invoca la función de Lambda de backend, de forma síncrona y de forma predeterminada. Este es el comportamiento deseado para la mayoría de operaciones de API de REST. Algunas aplicaciones, sin embargo, requieren que el trabajo se realice de forma asíncrona (como una operación por lotes o una operación de latencia), normalmente por un componente backend independiente. En este caso, la función de Lambda del backend se invoca de forma asíncrona y el método de la API REST de front-end no devuelve el resultado. Puede configurar la función de Lambda para una integración de Lambda que no sea proxy para invocarla de forma asíncrona especificando `'Event'` como el [tipo de invocación de Lambda](https://docs.aws.amazon.com/lambda/latest/dg/lambda-invocation.html). Esto se realiza de la siguiente manera: ## Configurar la invocación asíncrona de Lambda en la consola de API Gateway Para que todas las invocaciones sean asincrónicas: + En **Solicitud de integración**, añada un encabezado `X-Amz-Invocation-Type` con un valor estático de `'Event'`. Para que los clientes decidan si las invocaciones son asincrónicas o sincrónicas: 1. En **Solicitud de método**, añada un encabezado `InvocationType`. 1. En **Solicitud de integración**, añada un encabezado `X-Amz-Invocation-Type` con una expresión de mapeo de `method.request.header.InvocationType`. 1. Los clientes pueden incluir el encabezado `InvocationType: Event` en solicitudes de API para invocaciones asincrónicas o `InvocationType: RequestResponse` para invocaciones sincrónicas. ## Configurar la invocación asíncrona de Lambda mediante OpenAPI Para que todas las invocaciones sean asincrónicas: + Agregue el encabezado `X-Amz-Invocation-Type` a la sección **x-amazon-apigateway-integration**. ``` "x-amazon-apigateway-integration" : { "type" : "aws", "httpMethod" : "POST", "uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.X-Amz-Invocation-Type" : "'Event'" }, "passthroughBehavior" : "when_no_match", "contentHandling" : "CONVERT_TO_TEXT" } ``` Para que los clientes decidan si las invocaciones son asincrónicas o sincrónicas: 1. Agregue el siguiente encabezado en cualquier [objeto Path Item de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). ``` "parameters" : [ { "name" : "InvocationType", "in" : "header", "schema" : { "type" : "string" } } ] ``` 1. Agregue el encabezado `X-Amz-Invocation-Type` a la sección **x-amazon-apigateway-integration**. ``` "x-amazon-apigateway-integration" : { "type" : "aws", "httpMethod" : "POST", "uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.X-Amz-Invocation-Type" : "method.request.header.InvocationType" }, "passthroughBehavior" : "when_no_match", "contentHandling" : "CONVERT_TO_TEXT" } ``` 1. Los clientes pueden incluir el encabezado `InvocationType: Event` en solicitudes de API para invocaciones asincrónicas o `InvocationType: RequestResponse` para invocaciones sincrónicas. ## Configuración de la invocación asíncrona de Lambda mediante CloudFormation Las siguientes plantillas de CloudFormation muestran cómo configurar `AWS::ApiGateway::Method` para las invocaciones asíncronas. Para que todas las invocaciones sean asincrónicas: ``` AsyncMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref AsyncResource HttpMethod: GET ApiKeyRequired: false AuthorizationType: NONE Integration: Type: AWS RequestParameters: integration.request.header.X-Amz-Invocation-Type: "'Event'" IntegrationResponses: - StatusCode: '200' IntegrationHttpMethod: POST Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations MethodResponses: - StatusCode: '200' ``` Para que los clientes decidan si las invocaciones son asincrónicas o sincrónicas: ``` AsyncMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref AsyncResource HttpMethod: GET ApiKeyRequired: false AuthorizationType: NONE RequestParameters: method.request.header.InvocationType: false Integration: Type: AWS RequestParameters: integration.request.header.X-Amz-Invocation-Type: method.request.header.InvocationType IntegrationResponses: - StatusCode: '200' IntegrationHttpMethod: POST Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations MethodResponses: - StatusCode: '200' ``` Los clientes pueden incluir el encabezado `InvocationType: Event` en solicitudes de API para invocaciones asincrónicas o `InvocationType: RequestResponse` para invocaciones sincrónicas. # Gestionar los errores de Lambda en API Gateway Para las integraciones de Lambda personalizadas, debe asignar los errores devueltos por Lambda en la respuesta de integración a las respuestas de error de HTTP estándar para sus clientes. De lo contrario, los errores de Lambda se devuelven como respuestas `200 OK` de forma predeterminada y el resultado no es intuitivo para los usuarios de la API. Hay dos tipos de errores que Lambda puede devolver: errores estándar y errores personalizados. En la API, debe tratarlos de forma diferente. Con la integración de proxy de Lambda, Lambda debe devolver una salida con el siguiente formato: ``` { "isBase64Encoded" : "boolean", "statusCode": "number", "headers": { ... }, "body": "JSON string" } ``` En esta salida, `statusCode` es normalmente `4XX` para un error del cliente y `5XX` para un error del servidor. API Gateway trata estos errores asignando el error de Lambda a una respuesta de error HTTP, de acuerdo con el especificad `statusCode`. Para que API Gateway transmita el tipo de error (por ejemplo, `InvalidParameterException`), como parte de la respuesta al cliente, la función de Lambda debe incluir un encabezado (por ejemplo, `"X-Amzn-ErrorType":"InvalidParameterException"`) en la propiedad `headers`. **Topics** + [ ## Gestionar los errores de Lambda estándares en API Gateway. ](#handle-standard-errors-in-lambda-integration) + [ ## Gestionar los errores de Lambda personalizados en API Gateway ](#handle-custom-errors-in-lambda-integration) ## Gestionar los errores de Lambda estándares en API Gateway. Un error estándar de AWS Lambda tiene el siguiente formato: ``` { "errorMessage": "string", "errorType": "string", "stackTrace": [ "string", ... ] } ``` Aquí, `errorMessage` es una expresión de cadena del error. `errorType` es un tipo de error o excepción dependiente del lenguaje. `stackTrace` es una lista de expresiones de cadena que indican la pila de rastreo que conduce a la aparición del error. Por ejemplo, observe la siguiente función de Lambda en JavaScript (Node.js). ``` export const handler = function(event, context, callback) { callback(new Error("Malformed input ...")); }; ``` Esta función devuelve el siguiente error de Lambda estándar, que contiene `Malformed input ...` como el mensaje de error: ``` { "errorMessage": "Malformed input ...", "errorType": "Error", "stackTrace": [ "export const handler (/var/task/index.js:3:14)" ] } ``` Asimismo, considere la siguiente función de Lambda de Python, que produce una `Exception` con el mismo mensaje de error `Malformed input ...`. ``` def lambda_handler(event, context): raise Exception('Malformed input ...') ``` Esta función devuelve el siguiente error de Lambda estándar: ``` { "stackTrace": [ [ "/var/task/lambda_function.py", 3, "lambda_handler", "raise Exception('Malformed input ...')" ] ], "errorType": "Exception", "errorMessage": "Malformed input ..." } ``` Tenga en cuenta que los valores de las propiedades `errorType` y `stackTrace` dependen del lenguaje. El error estándar también se aplica a cualquier objeto de error que sea una extensión del objeto `Error` o una subclase de la clase `Exception`. Para asignar el error de Lambda estándar a una respuesta del método, primero debe decidir cuál es el código de estado HTTP para un error de Lambda determinado. Seguidamente, debe establecer un patrón de expresiones regulares en la propiedad `[selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern)` del recurso [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) asociado con el código de estado HTTP especificado. En la consola de API Gateway, este `selectionPattern` se denomina **Expresión regular de error de Lambda** en la sección **Respuesta de integración**, debajo de cada respuesta de integración. **nota** API Gateway utiliza expresiones regulares de estilo de patrón de Java para el mapeo de respuesta. Para obtener más información, consulte [Pattern (Patrón)](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) en la documentación de Oracle. Por ejemplo, use el siguiente comando [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html) para configurar una nueva expresión `selectionPattern`: ``` aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --http-method GET --status-code 400 --selection-pattern "Malformed.*" --region us-west-2 ``` Asegúrese de configurar también el código de error correspondiente (`400`) en la [respuesta del método](api-gateway-method-settings-method-response.md#setup-method-response-status-code). De lo contrario, API Gateway produce una respuesta de error de configuración no válida en tiempo de ejecución. **nota** En el tiempo de ejecución, API Gateway coteja el `errorMessage` de error de Lambda con el patrón de la expresión regular en la propiedad `selectionPattern`. Si hay una coincidencia, API Gateway devuelve el error de Lambda como una respuesta HTTP del código de estado HTTP correspondiente. Si no hay ninguna coincidencia, API Gateway devuelve el error como una respuesta predeterminada o produce una excepción de configuración no válida si no se ha configurado una respuesta predeterminada. Configurar el valor `selectionPattern` a `.*` para una determinada respuesta equivale a restablecer esta respuesta como la predeterminada. Esto se debe a que un patrón de solicitud de este tipo coincidirá con todos los mensajes de error, incluidos los nulos, es decir, cualquier mensaje de error no especificado. El mapeo resultante anula al predeterminado. Si utiliza `.+` como patrón de selección para filtrar respuestas, tenga en cuenta que puede que no coincida con una respuesta que contenga un carácter de nueva línea ('`\n`). Para actualizar un valor de `selectionPattern` existente mediante la API REST de la AWS CLI, llame a la operación [update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html) para reemplazar el valor de ruta de `/selectionPattern` por la expresión regular especificada con el patrón `Malformed*`. Para establecer la expresión `selectionPattern` con la consola de API Gateway, escriba la expresión en el cuadro de texto **Expresión regular de error de Lambda** cuando configure o actualice una respuesta de integración de un código de estado HTTP especificado. ## Gestionar los errores de Lambda personalizados en API Gateway En lugar del error estándar descrito en la sección anterior, AWS Lambda le permite devolver un objeto de error personalizado como una cadena JSON. El error puede ser cualquier objeto JSON válido. Por ejemplo, la siguiente función de Lambda en JavaScript (Node.js) devuelve un error personalizado: ``` export const handler = (event, context, callback) => { ... // Error caught here: var myErrorObj = { errorType : "InternalServerError", httpStatus : 500, requestId : context.awsRequestId, trace : { "function": "abc()", "line": 123, "file": "abc.js" } } callback(JSON.stringify(myErrorObj)); }; ``` Debe activar el objeto `myErrorObj` en una cadena JSON antes de llamar a `callback` para salir de la función. De lo contrario, `myErrorObj` se devuelve como una cadena de `"[object Object]"`. Cuando un método de la API está integrado con la función API Gateway anterior, Lambda recibe una respuesta de integración con la siguiente carga: ``` { "errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}" } ``` Al igual que con cualquier respuesta de integración, puede transferir esta respuesta de error tal como está a la respuesta del método. O puede usar una plantilla de mapeo para transformar la carga en un formato diferente. Considere, por ejemplo, la siguiente plantilla de asignación de cuerpo para una respuesta de método del código de estado `500`: ``` { errorMessage: $input.path('$.errorMessage'); } ``` Esta plantilla traduce el cuerpo de respuesta de la integración que contiene la cadena JSON del error personalizado en el siguiente cuerpo de respuesta del método. Este cuerpo de respuesta del método contiene el objeto JSON del error personalizado: ``` { "errorMessage" : { errorType : "InternalServerError", httpStatus : 500, requestId : context.awsRequestId, trace : { "function": "abc()", "line": 123, "file": "abc.js" } } }; ``` En función de los requisitos de la API, es posible que tenga que pasar algunas o todas las propiedades de errores personalizados como parámetros de encabezado de la respuesta del método. Para ello, puede aplicar asignaciones de errores personalizados desde el cuerpo de respuesta de integración a los encabezados de respuesta del método. Por ejemplo, la siguiente extensión de OpenAPI define una asignación desde las propiedades `errorMessage.errorType`, `errorMessage.httpStatus`, `errorMessage.trace.function` y `errorMessage.trace` a `error_type`, `error_status`, `error_trace_function` y `error_trace`, respectivamente. ``` "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.error_trace_function": "integration.response.body.errorMessage.trace.function", "method.response.header.error_status": "integration.response.body.errorMessage.httpStatus", "method.response.header.error_type": "integration.response.body.errorMessage.errorType", "method.response.header.error_trace": "integration.response.body.errorMessage.trace" }, ... } } } ``` En tiempo de ejecución, API Gateway deserializa el parámetro `integration.response.body` cuando realiza mapeos de encabezado. Sin embargo, esta deserialización se aplica únicamente a los mapeos de cuerpo a encabezado para respuestas de errores personalizados de Lambda y no se aplica a los mapeos de cuerpo a cuerpo que utilizan `$input.body`. Con estas asignaciones de cuerpo a encabezado de errores personalizados, el cliente recibe los siguientes encabezados como parte de la respuesta del método, siempre que los encabezados `error_status`, `error_trace`, `error_trace_function` y `error_type` estén declarados en la solicitud del método. ``` "error_status":"500", "error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}", "error_trace_function":"abc()", "error_type":"InternalServerError" ``` La propiedad `errorMessage.trace` del cuerpo de respuesta de integración es una propiedad compleja. Se asigna al encabezado `error_trace` como una cadena JSON. # 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. **Topics** + [ ## Configurar integraciones de proxy HTTP en API Gateway ](#api-gateway-set-up-http-proxy-integration-on-proxy-resource) + [ ## Configurar integraciones HTTP personalizadas en API Gateway ](#set-up-http-custom-integrations) ## 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](api-gateway-create-api-as-simple-proxy-for-http.md). 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](http://petstore-demo-endpoint.execute-api.com/petstore/pets). ------ #### [ 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, también conocida como la integración sin proxy, obtiene más control sobre qué datos se transfieren entre 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](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#requestParameters) en un recurso [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html). 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](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestParameters) en el recurso correspondiente de [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) para especificar los mapeos entre parámetros. También debe establecer la propiedad [requestTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#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](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) en el recurso [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). 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, configure [selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern) para elegir una respuesta de integración basada en la respuesta del backend. Para una integración HTTP sin proxy, esto es una expresión regular. Por ejemplo, para asignar todos los códigos de estado HTTP 2xx desde un punto de conexión HTTP proxy a esta asignación de salida, utilice `2\d{2}`. **nota** API Gateway utiliza expresiones regulares de estilo de patrón de Java para el mapeo de respuesta. Para obtener más información, consulte [Pattern (Patrón)](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) en la documentación de Oracle. A continuación, como parte de la configuración de respuesta de integración, debe establecer la propiedad [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseParameters) en el recurso [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) correspondiente para especificar los mapeos entre parámetros. También debe establecer el mapa [responseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#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](rest-api-data-transformations.md). # Transmisión de la respuesta de integración para las integraciones de proxy en API Gateway Puede configurar la integración de proxy para controlar cómo API Gateway devuelve la respuesta de integración. De forma predeterminada, API Gateway espera a recibir la respuesta completa antes de iniciar la transmisión. Sin embargo, si configura el modo de transferencia de respuestas de la integración en `STREAM`, API Gateway no espera a que se calcule completamente la respuesta para enviarla al cliente. La transmisión de respuestas funciona para todos los tipos de puntos de conexión de la API de REST. Utilice la transmisión de respuestas para los siguientes casos de uso: + Reduzca el tiempo para el primer byte (TTFB) para aplicaciones de IA generativa como los chatbots. + Transmita archivos de imágenes, vídeos o música de gran tamaño sin utilizar una URL prefirmada de S3. + Realice operaciones de larga duración y, al mismo tiempo, informe sobre el progreso incremental, como los eventos enviados por el servidor (SSE). + Supere el límite de carga útil de respuesta de 10 MB de API Gateway. + Supera el límite de 29 segundos de API Gateway sin solicitar un aumento del tiempo de espera de la integración. + Reciba una carga útil binaria sin configurar los tipos de medios binarios. ## Consideraciones sobre la transmisión de la carga útil de respuesta Es posible que las siguientes consideraciones afecten al uso de la transmisión de la carga útil de respuesta: + Solo puede utilizar la transmisión de carga útil de respuesta para tipos de integración `HTTP_PROXY` o `AWS_PROXY`. Esto incluye las integraciones de proxy de Lambda y las integraciones privadas que utilizan integraciones de `HTTP_PROXY`. + La configuración predeterminada del modo de transferencia es `BUFFERED`. Para utilizar la transmisión de respuestas, debe cambiar el modo de transferencia de respuesta a `STREAM`. + La transmisión de respuestas solo es compatible con las API de REST. + La transmisión de solicitudes es incompatible. + Puede transmitir su respuesta durante 15 minutos como máximo. + Las transmisiones están sujetas a tiempos de espera por inactividad. Para puntos de conexión regionales o privados, el tiempo de espera es de 5 minutos. Para puntos de conexión optimizados para bordes, el tiempo de espera es de 30 segundos. + Si utiliza la transmisión de respuesta para una API de REST regional con su propia distribución de CloudFront, puede lograr un tiempo de espera por inactividad de más de 30 segundos lo que aumenta el tiempo de espera de respuesta de la distribución de CloudFront. Para obtener más información, consulte [Tiempo de espera de respuesta](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/DownloadDistValuesOrigin.html#DownloadDistValuesOriginResponseTimeout). + Cuando el modo de transferencia de respuestas está configurado en `STREAM`, API Gateway no admite características que requieran almacenar en búfer toda la respuesta de integración. Por este motivo, las siguientes características no son compatibles con la transmisión de respuestas: + Almacenamiento en caché de puntos de conexión + Codificación de contenido. Si desea comprimir su respuesta de integración, hágalo en su integración. + Transformación de la respuesta con VTL + Dentro de cada respuesta de transmisión, los primeros 10 MB de carga útil de respuesta no están sujetos a ninguna restricción de ancho de banda. Los datos de carga útil de respuesta que superen los 10 MB están restringidos a 2 MB/s. + Cuando la conexión entre el cliente y API Gateway o entre API Gateway y Lambda se cierra debido al tiempo de espera, es posible que la función de Lambda continúe ejecutándose. Para obtener más información, consulte [Configuración del tiempo de espera de la función de Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html). + La transmisión de respuestas tiene un costo. Para obtener más información, consulte [Precio de API Gateway](https://aws.amazon.com/api-gateway/pricing/). # Configuración de una integración de proxy HTTP con transmisión de respuesta de carga útil en API Gateway Cuando configura la transmisión de la carga útil de respuesta, especifica el modo de transferencia de respuesta en la solicitud de integración del método. Estos ajustes se configuran en la solicitud de integración para controlar el comportamiento de API Gateway antes y durante la respuesta de integración. Cuando utiliza la transmisión de respuestas, puede configurar el tiempo de espera de la integración en un máximo de 15 minutos. Cuando utiliza la transmisión de respuestas de carga útil con una integración de `HTTP_PROXY`, API Gateway no enviará el código de estado de respuesta HTTP ni ningún encabezado de respuesta HTTP hasta que reciba todos los encabezados por completo. ## Creación de una integración de proxy HTTP con transmisión de respuesta de carga útil El siguiente procedimiento muestra cómo importar una nueva API con el valor `responseTransferMode` establecido en `STREAM`. Si tiene una API de integración existente y desea modificar `responseTransferMode`, consulte [Actualización del modo de transferencia de respuestas para una integración de proxy HTTP](#response-streaming-http-update). ------ #### [ Consola de administración de AWS ] **Creación de una integración de proxy HTTP con transmisión de respuesta de carga útil** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. Elija **Crear recurso**. 1. En **Nombre del recurso**, escriba **streaming**. 1. Elija **Crear recurso**. 1. Con el recurso **/streaming** seleccionado, elija **Crear método**. 1. En **Tipo de método**, elija **CUALQUIERA**. 1. Para **Tipo de integración**, elija **HTTP**. 1. Elija **Integración de proxy HTTP**. 1. Para el **modo de transferencia de respuesta**, elija **Flujo**. 1. Para el **método HTTP**, elige un método. 1. Para **URL del punto de conexión**, ingrese un punto de conexión de integración. Asegúrese de elegir un punto de conexión que genere una gran carga útil para que se la transmita. 1. Elija **Crear método**. Después de crear el método, implemente la API. **Para implementar su API** 1. Elija **Implementar API**. 1. En **Etapa**, seleccione **Nueva etapa**. 1. En **Stage name (Nombre de etapa)**, escriba **prod**. 1. (Opcional) En **Description (Descripción)**, introduzca una descripción. 1. Elija **Implementar**. ------ #### [ AWS CLI ] **Creación de una nueva API con transmisión de respuesta de carga útil** 1. Copie el siguiente archivo de API abierto y guárdelo como `ResponseStreamDemoSwagger.yaml`. En este archivo, `responseTransferMode` se establece en `STREAM`. El punto de conexión de integración está configurado en `https://example.com`, pero le recomendamos que lo modifique por un punto de conexión que genere una gran carga útil para que se la transmita. ``` openapi: "3.0.1" info: title: "ResponseStreamingDemo" version: "2025-04-28T17:28:25Z" servers: - url: "{basePath}" variables: basePath: default: "prod" paths: /streaming: get: x-amazon-apigateway-integration: httpMethod: "GET" uri: "https://example.com" type: "http_proxy" timeoutInMillis: 900000 responseTransferMode: "STREAM" ``` 1. Use el comando `import-rest-api` siguiente para importar la definición de OpenAPI: ``` aws apigateway import-rest-api \ --body 'fileb://~/ResponseStreamDemoSwagger.yaml' \ --parameters endpointConfigurationTypes=REGIONAL \ --region us-west-1 ``` 1. Use el comando `create-deployment` siguiente para implementar la nueva API en una etapa: ``` aws apigateway create-deployment \ --rest-api-id a1b2c3 \ --stage-name prod \ --region us-west-1 ``` ------ ## Actualización del modo de transferencia de respuestas para una integración de proxy HTTP El procedimiento siguiente muestra cómo actualizar el modo de transferencia de respuestas para una integración de proxy HTTP. ------ #### [ Consola de administración de AWS ] **Actualización del modo de transferencia de respuestas para una integración de proxy HTTP** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. Elija un método. 1. En la pestaña **Solicitud de integración**, en **Configuración de la solicitud de integración**, seleccione **Editar**. 1. Para el **modo de transferencia de respuesta**, elija **Flujo**. 1. Seleccione **Save**. Después de actualizar el método, implemente la API. **Para implementar su API** 1. Elija **Implementar API**. 1. En **Etapa**, seleccione **Nueva etapa**. 1. En **Stage name (Nombre de etapa)**, escriba **prod**. 1. (Opcional) En **Description (Descripción)**, introduzca una descripción. 1. Elija **Implementar**. ------ #### [ AWS CLI ] El comando `update-integration` siguiente actualiza el modo de transferencia de una integración de `BUFFERED` a `STREAM`. Para cualquier API existente, el modo de transferencia de respuesta para todas las integraciones se establece en `BUFFERED`. ``` aws apigateway update-integration \ --rest-api-id a1b2c3 \ --resource-id aaa111 \ --http-method GET \ --patch-operations "op='replace',path='/responseTransferMode',value=STREAM" \ --region us-west-1 ``` Tiene que volver a implementar la API para que los cambios surtan efecto. Si personalizó el tiempo de espera de la integración, este valor de tiempo de espera se elimina, ya que API Gateway transmite la respuesta durante un máximo de 5 minutos. El comando `update-integration` siguiente actualiza el modo de transferencia de una integración de `STREAM` a `BUFFERED`: ``` aws apigateway update-integration \ --rest-api-id a1b2c3 \ --resource-id aaa111 \ --http-method GET \ --patch-operations "op='replace',path='/responseTransferMode',value=BUFFERED" \ --region us-west-1 ``` Tiene que volver a implementar la API para que los cambios surtan efecto. ------ # Configuración de una integración de proxy de Lambda con transmisión de respuesta de carga útil en API Gateway Puede transmitir la respuesta de una función de Lambda para mejorar el rendimiento del tiempo hasta el primer byte (TTFB) y devolver respuestas parciales al cliente a medida que estén disponibles. API Gateway requiere que utilice la API de Lambda [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) para invocar la función de Lambda. API Gateway pasa un objeto de evento a la función de Lambda. La función de Lambda del backend analiza los datos de la solicitud entrante para determinar la respuesta que devuelve. Para que API Gateway transmita la salida de Lambda, la función de Lambda debe producir el [formato](#response-transfer-mode-lambda-format) que requiere API Gateway. ## Diferencias en las integraciones de proxy de Lambda entre el modo de transferencia de respuesta en flujo y en búfer La siguiente lista describe las diferencias entre una integración de proxy de Lambda y una integración de proxy de Lambda para la transmisión de respuestas: + API Gateway usa la API [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) para invocar la integración del proxy de Lambda para la transmisión de respuestas. Esto da como resultado un URI diferente, que es el siguiente: ``` arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations ``` Este ARN utiliza una fecha diferente para la versión de la API y una acción de servicio diferente en comparación con la integración del proxy de Lambda. Si utiliza la consola de API Gateway para la transmisión de respuestas, la consola utilizará el URI correcto para usted. + En una integración de proxy de Lambda, API Gateway envía la respuesta al cliente solo después de recibir la respuesta completa de Lambda. En una integración de proxy de Lambda para la transmisión de respuestas, API Gateway inicia la transmisión de carga útil después de recibir los metadatos y el delimitador válidos de Lambda. + La integración de proxy de Lambda para la transmisión de respuestas utiliza el mismo formato de entrada que la integración de proxy, pero requiere un formato de salida diferente. ## Formato de integración de proxy de Lambda para transmisión de respuestas Cuando API Gateway invoca una función de Lambda con transmisión de respuestas, el formato de entrada es el mismo que el formato de entrada de una función de Lambda para la integración de proxy. Para obtener más información, consulte [Formato de entrada de una función de Lambda para la integración de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). Cuando Lambda transmite una respuesta a API Gateway, la respuesta debe seguir el siguiente formato. Este formato utiliza un delimitador para separar el JSON de los metadatos y la carga útil sin procesar. En este caso, los datos de carga útil se transmiten tal como los transmite la función de Lambda de transmisión: ``` { "headers": {"headerName": "headerValue", ...}, "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... }, "cookies" : ["cookie1", "cookie2"], "statusCode": httpStatusCode }PAYLOAD1 | PAYLOAD2 | PAYLOAD3 ``` En la salida: + Las claves `headers`, `multiValueHeaders`, `cookies` y `statusCode` pueden no estar especificadas si no se van a devolver más encabezados de respuesta. + La clave `headers` solo puede contener encabezados de un solo valor. + La salida espera que los encabezados contengan `Transfer-Encoding: chunked` o `Content-length: number`. Si la función no devuelve ninguno de estos encabezados, API Gateway agrega `Transfer-Encoding: chunked` al encabezado de respuesta. + La clave `multiValueHeaders` puede contener encabezados de varios valores y encabezados de un solo valor. Puede utilizar la clave `multiValueHeaders` para especificar todos los encabezados adicionales, incluidos los que solo contienen un valor. + Si especifica valores para `headers` y `multiValueHeaders`, API Gateway los combina en una sola lista. Si se especifica el mismo par de clave-valor en ambos, solo los valores de `multiValueHeaders` aparecerán en la lista combinada. + Los metadatos deben ser un JSON válido. Solo se admiten las claves de `headers`, `multiValueHeaders`, `cookies` y `statusCode`. + Debe proporcionar un delimitador después del JSON de metadatos. El delimitador debe tener 8 bytes nulos y debe aparecer dentro de los primeros 16 KB de datos de transmisión. + API Gateway no requiere un formato específico para la carga útil de respuesta de método. Si utiliza una URL de función para transmitir la función de Lambda, debe modificar la entrada y la salida de la función de Lambda para cumplir estos requisitos. Si el resultado de la función de Lambda no cumple con los requisitos de este formato, es posible que API Gateway siga invocando la función de Lambda. En la siguiente tabla se muestran las combinaciones de la configuración de las solicitudes de integración de API y el código de función de Lambda que admite API Gateway. Esto incluye las combinaciones compatibles con el modo de transferencia de respuestas en búfer. | Modo de transferencia de respuesta | El código de función se ajusta al formato requerido | API de invocación de Lambda | Compatible con API Gateway | | --- | --- | --- | --- | | De streaming | Sí | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Sí. API Gateway transmite la respuesta. | | De streaming | No | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | No. API Gateway invoca la función de Lambda y devuelve una respuesta de error 500. | | De streaming | Sí | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | No. API Gateway no admite esta configuración de integración. | | De streaming | No | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | No. API Gateway no admite esta configuración de integración. | | Almacenado en búfer | Sí | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | No. API Gateway no admite esta configuración de integración. | | Almacenado en búfer | No | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | No. API Gateway no admite esta configuración de integración. | | Almacenado en búfer | Sí | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | API Gateway devuelve los encabezados HTTP y el código de estado, pero no el cuerpo de la respuesta. | | Almacenado en búfer | No | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | Sí. Esta es una integración de proxy de Lambda. Para obtener más información, consulte [Integración de proxy de Lambda](set-up-lambda-proxy-integrations.md). | # Configuración de una integración de proxy de Lambda con transmisión de respuesta de carga útil en API Gateway Cuando configura la transmisión de la carga útil de respuesta, especifica el modo de transferencia en la solicitud de integración del recurso. Estos ajustes se configuran en la solicitud de integración para controlar el comportamiento de API Gateway antes y durante la respuesta de integración. ## Ejemplos de funciones de Lambda para la transmisión de respuestas La función de Lambda debe cumplir el [Formato de integración de proxy de Lambda para transmisión de respuestas](response-transfer-mode-lambda.md#response-transfer-mode-lambda-format). Le recomendamos que utilice una de las tres funciones de Lambda de ejemplo para probar la transmisión de respuestas. Cuando cree la función de Lambda, asegúrese de hacer lo siguiente: + Proporcione un tiempo de espera adecuado para la función. Le recomendamos configurar un tiempo de espera de al menos 1 minuto para obtener información sobre la transmisión de respuestas. Al crear los recursos de producción, asegúrese de que el tiempo de espera de la función de Lambda abarque todo el ciclo de solicitud. Para obtener más información, consulte [Configuración del tiempo de espera de la función de Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html). + Utilice el último tiempo de ejecución de Node.js. + Utilice una región en la que esté disponible la transmisión de respuestas de Lambda. ------ #### [ Using HttpResponseStream.from ] El siguiente ejemplo de código transmite los objetos de metadatos y las cargas útiles de JSON de vuelta al cliente mediante el método `awslambda.HttpResponseStream()` sin utilizar el método de canalización. No es necesario crear el delimitador. Para obtener más información, consulte [Escritura de funciones de Lambda habilitadas para la transmisión de respuestas](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html). ``` export const handler = awslambda.streamifyResponse( async (event, responseStream, context) => { const httpResponseMetadata = { "statusCode": 200, "headers": { "x-foo": "bar" }, "multiValueHeaders": { "x-mv1": ["hello", "world"], "Set-Cookie": ["c1=blue", "c2=red"] } }; responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata); await new Promise(r => setTimeout(r, 1000)); // synthetic delay responseStream.write("First payload "); await new Promise(r => setTimeout(r, 1000)); // synthetic delay responseStream.write("Final payload"); responseStream.end(); }); ``` ------ #### [ Using the pipeline method ] Lambda recomienda que, al escribir funciones habilitadas para la transmisión de respuestas, utilice el decorador `awslambda.streamifyResponse()` que proporcionan los tiempos de ejecución nativos de Node.js y el método de `pipeline()`. Cuando utiliza el método de canalización, no necesita crear el delimitador; Lambda lo hace automáticamente. Para obtener más información, consulte [Escritura de funciones de Lambda habilitadas para la transmisión de respuestas](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html). El ejemplo de código siguiente transmite los objetos de metadatos y tres cargas útiles de JSON de vuelta al cliente. ``` import { pipeline } from 'node:stream/promises'; import { Readable } from 'node:stream'; export const handler = awslambda.streamifyResponse( async (event, responseStream, context) => { const httpResponseMetadata = { statusCode: 200, headers: { "Content-Type": "text/plain", "X-Custom-Header": "Example-Custom-Header" } }; responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata); const dataStream = Readable.from(async function* () { yield "FIRST payload\n"; await new Promise(r => setTimeout(r, 1000)); yield "SECOND payload\n"; await new Promise(r => setTimeout(r, 1000)); yield "THIRD payload\n"; await new Promise(r => setTimeout(r, 1000)); }()); await pipeline(dataStream, responseStream); } ); ``` ------ #### [ Without using the pipeline method ] El ejemplo de código siguiente transmite los objetos de metadatos y tres cargas útiles de JSON de vuelta al cliente sin usar el método `awslambda.HttpResponseStream()`. Sin el método `awslambda.HttpResponseStream()`, debe incluir un delimitador de 8 bytes nulos entre los metadatos y la carga útil. ``` export const handler = awslambda.streamifyResponse(async (event, response, ctx) => { response.write('{"statusCode": 200, "headers": {"hdr-x": "val-x"}}'); response.write("\x00".repeat(8)); // DELIMITER await new Promise(r => setTimeout(r, 1000)); response.write("FIRST payload"); await new Promise(r => setTimeout(r, 1000)); response.write("SECOND payload"); await new Promise(r => setTimeout(r, 1000)); response.write("FINAL payload"); response.end(); }); ``` ------ ## Creación de una integración de proxy de Lambda con transmisión de respuesta de carga útil En el siguiente procedimiento se muestra cómo crear una integración de proxy de Lambda con la transmisión de respuesta de carga útil. Utilice la función de Lambda de ejemplo o cree la suya propia. ------ #### [ Consola de administración de AWS ] **Creación de una integración de proxy de Lambda con transmisión de respuesta de carga útil** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. Elija **Crear recurso**. 1. En **Nombre del recurso**, escriba **streaming**. 1. Elija **Crear recurso**. 1. Con el recurso **/streaming** seleccionado, elija **Crear método**. 1. En **Tipo de método**, elija **CUALQUIERA**. 1. Para **Tipo de integración**, elija **Lambda**. 1. Elija **Integración de proxy de Lambda**. 1. Para el **modo de transferencia de respuesta**, elija **Flujo**. 1. Para la **función de Lambda**, elija el nombre de la función de Lambda. La consola de API Gateway utiliza automáticamente la API [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) para invocar la función de Lambda. Es responsable de escribir una función de Lambda habilitada para la transmisión de respuestas. Para ver un ejemplo, consulta [Ejemplos de funciones de Lambda para la transmisión de respuestas](#response-streaming-lambda-example). 1. Elija **Crear método**. Después de crear el método, implemente la API. **Para implementar su API** 1. Elija **Implementar API**. 1. En **Etapa**, seleccione **Nueva etapa**. 1. En **Stage name (Nombre de etapa)**, escriba **prod**. 1. (Opcional) En **Description (Descripción)**, introduzca una descripción. 1. Elija **Implementar**. ------ #### [ AWS CLI ] El siguiente procedimiento muestra cómo importar una nueva API con el valor `responseTransferMode` establecido en `STREAM`. Si tiene una API de integración existente y desea modificar `responseTransferMode`, consulte [Actualización del modo de transferencia de respuestas para una integración de proxy de Lambda](#response-streaming-lambda-update). **Creación de una nueva API con transmisión de respuesta de carga útil** 1. Copie el siguiente archivo de API abierto y guárdelo como `ResponseStreamDemoSwagger.yaml`. En este archivo, `responseTransferMode` se establece en `STREAM` y el URI de integración se establece en `arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations`. Sustituya el nombre de la función de `my-function` por una función habilitada para transmisión y sustituya las credenciales por un rol de IAM que tenga políticas que permitan al servicio de `apigateway` invocar funciones de Lambda. ``` openapi: "3.0.1" info: title: "ResponseStreamingDemo" version: "2025-04-28T17:28:25Z" servers: - url: "{basePath}" variables: basePath: default: "prod" paths: /lambda: get: x-amazon-apigateway-integration: httpMethod: "POST" uri: "arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations" type: "aws_proxy" timeoutInMillis: 90000 responseTransferMode: "STREAM" credentials: "arn:aws:iam::111122223333:role/apigateway-lambda-role" ``` En lugar de proporcionar un rol de IAM para credenciales, puede utilizar el comando `add-permission` para Lambda para agregar permisos basados en recursos. 1. Use el comando `import-rest-api` siguiente para importar la definición de OpenAPI: ``` aws apigateway import-rest-api \ --body 'fileb://~/ResponseStreamDemoSwagger.yaml' \ --parameters endpointConfigurationTypes=REGIONAL \ --region us-west-1 ``` 1. Use el comando `create-deployment` siguiente para implementar la nueva API en una etapa: ``` aws apigateway create-deployment \ --rest-api-id a1b2c2 \ --stage-name prod \ --region us-west-1 ``` ------ ### Actualización del modo de transferencia de respuestas para una integración de proxy de Lambda El procedimiento siguiente muestra cómo actualizar el modo de transferencia de respuestas para una integración de proxy de Lambda. Cuando cambie el modo de transferencia de respuesta a transmisión, actualice la función de Lambda para que cumpla con los requisitos de la transmisión de respuesta. Utilice la función de Lambda de ejemplo o cree la suya propia. ------ #### [ Consola de administración de AWS ] **Actualización del modo de transferencia de respuestas para una integración de proxy de Lambda** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. Elija un método. 1. En la pestaña **Solicitud de integración**, en **Configuración de la solicitud de integración**, seleccione **Editar**. 1. Para el **modo de transferencia de respuesta**, elija **Flujo**. 1. Para la **función de Lambda**, elija el nombre de la función de Lambda. 1. Seleccione **Save**. Después de actualizar el método, implemente la API. **Para implementar su API** 1. Elija **Implementar API**. 1. En **Etapa**, seleccione **Nueva etapa**. 1. En **Stage name (Nombre de etapa)**, escriba **prod**. 1. (Opcional) En **Description (Descripción)**, introduzca una descripción. 1. Elija **Implementar**. ------ #### [ AWS CLI ] 1. Actualización de la función de Lambda para que esté habilitada para la transmisión. 1. Utilice el comando AWS CLI siguiente para actualizar el URI de integración y el modo de transferencia de respuestas de la integración: ``` aws apigateway update-integration \ --rest-api-id a1b2c3 \ --resource-id aaa111 \ --http-method ANY \ --patch-operations "[{\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations\"}, {\"op\":\"replace\",\"path\":\"/responseTransferMode\",\"value\":\"STREAM\"}]" \ --region us-west-1 ``` 1. Vuelva a implementar la API para que los cambios se apliquen. ------ # Solución de problemas relacionados con la transmisión de respuestas en API Gateway La siguiente guía de solución de problemas puede ayudar a resolver los problemas relacionados con las API que usan transmisión de respuestas. ## Solución de problemas generales Puede usar el [TestInvokeMethod](https://docs.aws.amazon.com/apigateway/latest/api/API_TestInvokeMethod.html) o la pestaña de prueba de la consola para probar la respuesta de la transmisión. Es posible que las siguientes consideraciones afecten al uso de la invocación de prueba para la transmisión de respuesta: + Cuando prueba el método, API Gateway almacena en búfer la carga útil de respuesta transmitida. Una vez que se cumple alguna de las siguientes condiciones, API Gateway devuelve una respuesta única que contiene la carga útil almacenada en búfer: + La solicitud está completa + Han transcurrido 35 segundos + Se ha almacenado en búfer más de 1 MB de carga útil de respuesta + Si transcurren más de 35 segundos antes de que el método devuelva un estado de respuesta HTTP y todos los encabezados, el estado de respuesta devuelto en TestInvokeMethod es 0. + API Gateway no produce ningún registro de ejecución. Una vez implementada la API, puede probar la respuesta de la transmisión mediante un comando curl. Le recomendamos que utilice la opción `-i` para incluir los encabezados de respuesta de protocolo en la salida. Visualización de los datos de respuesta según llegan, uso de la opción de curl `--no-buffer` ## Errores de cURL de solución de problemas Si está probando una integración y recibe el error `curl: (18) transfer closed with outstanding read data remaining`, asegúrese de que el tiempo de espera de la integración sea lo suficientemente largo. Si utiliza una función de Lambda, debe actualizar el tiempo de espera de respuesta de la función de Lambda. Para obtener más información, consulte [Configuración del tiempo de espera de la función de Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html). ## Solución de problemas mediante el registro de acceso Puede utilizar los registros de acceso de la etapa de API de REST para registrar y solucionar problemas de la transmisión de respuestas. Además de las variables existentes, puede utilizar las variables del registro de acceso siguientes: `$context.integration.responseTransferMode` El modo de transferencia de respuesta de la integración. Puede ser `BUFFERED` o `STREAMED`. `$context.integration.timeToAllHeaders` El tiempo entre que API Gateway establece la conexión de integración y se reciben del cliente todos los encabezados de respuesta de integración. `$context.integration.timeToFirstContent` El tiempo transcurrido entre el momento en que API Gateway establece la conexión de integración y el momento en que recibe los primeros bytes de contenido. `$context.integration.latency` o `$context.integrationLatency` El tiempo entre que API Gateway establece la conexión de integración y se completa la transmisión de respuesta de integración. La siguiente figura muestra cómo estas variables del registro de acceso representan los diferentes componentes de un flujo de respuesta. ![\[Variables de registro de acceso para la transmisión de respuestas en API Gateway\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/response-streaming-figure.png) Para obtener más información acerca de los registros de acceso, consulte [Configuración del registro de CloudWatch para las API de REST en API Gateway](set-up-logging.md). También puede usar X-Ray para supervisar su flujo de respuesta. Para obtener más información, consulte [Rastreo de las solicitudes de usuario a las API de REST mediante X-Ray en API Gateway](apigateway-xray.md). # Integraciones privadas para las API de REST en API Gateway Use una integración privada para exponer los recursos HTTP/HTTPS dentro de una Amazon VPC para que puedan acceder los clientes que están fuera de la VPC. Esto amplía el acceso a los recursos de la VPC privada más allá de los límites de esta. Puede controlar el acceso a la API mediante cualquiera de los [ métodos de autorización](apigateway-control-access-to-api.md) admitidos por API Gateway. Para crear una integración privada, primero debe crear un enlace de la VPC. API Gateway admite enlaces de VPC V2 para las API de REST. Los enlaces de VPC V2 le permiten crear integraciones privadas que conectan la API de REST a los equilibradores de carga de aplicación sin usar un equilibrador de carga de red. El uso de un equilibrador de carga de aplicación le permite conectarse a las aplicaciones basadas en contenedores de Amazon ECS y a muchos otros backend. Los enlaces de VPC V1 se consideran un tipo de integración heredado. Aunque API Gateway los admite, le recomendamos que no cree nuevos enlaces de VPC V1. ## Consideraciones Las siguientes consideraciones pueden afectar al uso de las integraciones privadas: + Todos los recursos deben pertenecer a la misma Cuenta de AWS. Esto incluye el equilibrador de carga, el enlace de la VPC y la API de REST. + De forma predeterminada, el tráfico de integración privada utiliza el protocolo HTTP. Para usar HTTPS, especifique un [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri) que contenga un nombre de servidor seguro, como `https://example.com:443/test`. + En una integración privada, API Gateway incluye la parte de [etapa](set-up-stages.md) del punto de conexión de la API en la solicitud a los recursos de backend. Por ejemplo, si solicita la etapa `test` de una API, API Gateway incluye `test/path` en la solicitud a la integración privada. Para eliminar el nombre de etapa de la solicitud a los recursos de backend, utilice [Asignación de parámetros](rest-api-parameter-mapping.md) para crear una invalidación para la variable `$context.requestOverride.path`. + No se admiten las integraciones privadas con AWS Cloud Map. **Topics** + [ ## Consideraciones ](#private-integrations-considerations) + [ # Configuración de enlaces de VPC V2 en API Gateway ](apigateway-vpc-links-v2.md) + [ # Configuración de una integración privada ](set-up-private-integration.md) + [ # Integración privada mediante enlaces de VPC V1 (heredado) ](vpc-links-v1.md) # Configuración de enlaces de VPC V2 en API Gateway Los enlaces de la VPC le permiten crear integraciones privadas que conectan las rutas de la API a los recursos privados de una VPC, como equilibradores de carga de aplicaciones o aplicaciones basadas en contenedores de Amazon ECS. Una integración privada utiliza un enlace de VPC V2 para encapsular las conexiones entre API Gateway y los recursos de la VPC de destino. Puede reutilizar enlaces de VPC a través de diferentes recursos y API. Cuando crea un enlace de la VPC, API Gateway crea y administra [interfaces de red elástica](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) para el enlace de VPC V2 en la cuenta. Este proceso puede tardar unos minutos. Cuando un enlace de VPC V2 está listo para usar, su estado cambia de `PENDING` a `AVAILABLE`. **nota** Si no se envía tráfico a través del enlace de la VPC durante 60 días, se convierte en `INACTIVE`. Cuando un enlace de la VPC tiene el estado `INACTIVE`, API Gateway elimina todas las interfaces de red del enlace de la VPC. Esto hace que las solicitudes de API que dependen del enlace de la VPC fallen. Si las solicitudes de la API se reanudan, API Gateway reaprovisiona las interfaces de red. Puede tardar unos minutos en crear las interfaces de red y reactivar el enlace de la VPC. Puede utilizar el estado del enlace de la VPC para supervisar el estado del enlace de la VPC. ## Creación de un enlace de VPC V2 mediante la AWS CLI Para crear un enlace de VPC V2, todos los recursos involucrados deben ser propiedad de la misma cuenta de AWS. El siguiente comando [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-vpc-link.html) permite crear un enlace de la VPC: ``` aws apigatewayv2 create-vpc-link --name MyVpcLink \ --subnet-ids subnet-aaaa subnet-bbbb \ --security-group-ids sg1234 sg5678 ``` **nota** Los enlaces de VPC V2 son inmutables. Después de crear un enlace de VPC V2, no puede cambiar sus subredes o grupos de seguridad. ## Eliminación de un enlace de VPC V2 mediante la AWS CLI El siguiente comando [delete-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-vpc-link.html) permite eliminar un enlace de la VPC. ``` aws apigatewayv2 delete-vpc-link --vpc-link-id abcd123 ``` ## Disponibilidad por región Los enlaces de VPC V2 se admiten en las siguientes regiones y zonas de disponibilidad: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/apigateway-vpc-links-v2.html) # Configuración de una integración privada Para crear una integración privada con un equilibrador de carga de aplicación o un equilibrador de carga de red, cree una integración de proxy HTTP, especifique el [enlace de VPC V2](apigateway-vpc-links-v2.md) que se va a utilizar y proporcione el ARN de un equilibrador de carga de red o un equilibrador de carga de aplicación. De forma predeterminada, el tráfico de integración privada utiliza el protocolo HTTP. Para usar HTTPS, especifique un [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri) que contenga un nombre de servidor seguro, como `https://example.com:443/test`. Para ver un tutorial completo sobre cómo crear una API de REST con una integración privada, consulte [Tutorial: Creación de una API de REST con una integración privada](getting-started-with-private-integration.md). ## Creación de una integración privada El procedimiento siguiente muestra cómo crear una integración privada que se conecte a un equilibrador de carga mediante un enlace de VPC V2. ------ #### [ Consola de administración de AWS ] Para ver un tutorial sobre cómo crear una integración privada, consulte [Tutorial: Creación de una API de REST con una integración privada](getting-started-with-private-integration.md). ------ #### [ AWS CLI ] El siguiente comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) permite crear una integración privada que se conecta a un equilibrador de carga mediante un enlace de VPC V2: ``` aws apigateway put-integration \ --rest-api-id abcdef123 \ --resource-id aaa000 \ --integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \ --uri 'https://example.com:443/path' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id bbb111 ``` En lugar de proporcionar directamente el ID de conexión, puede utilizar una variable de etapa. Cuando implementa la API en una etapa, se establece el ID de enlace de VPC V2. El siguiente comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) crea una integración privada mediante una variable de etapa para el ID de enlace de VPC V2: ``` aws apigateway put-integration \ --rest-api-id abcdef123 \ --resource-id aaa000 \ --integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \ --uri 'https://example.com:443/path' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id "\${stageVariables.vpcLinkV2Id}" ``` No olvide utilizar comillas dobles en la expresión de la variable de etapa (\$1\$1stageVariables.vpcLinkV2Id\$1) y utilizar caracteres de escape con \$1. ------ #### [ OpenAPI ] Puede configurar una API con la integración privada importando el archivo de OpenAPI de la API. La configuración es similar a las definiciones de OpenAPI de una API con integraciones HTTP, con las siguientes excepciones: + Debe establecer `connectionType` explícitamente en `VPC_LINK`. + Debe establecer `connectionId` explícitamente en el ID de un enlace `VpcLinkV2` o en una variable de etapa que haga referencia al ID de un enlace `VpcLinkV2`. + El parámetro `uri` de la integración privada apunta a un punto de conexión HTTP/HTTPS de la VPC, pero se utiliza para configurar el encabezado `Host` de la solicitud de integración. + El parámetro `uri` de la integración privada que tiene un punto de conexión HTTPS en la VPC se utiliza para contrastar el nombre de dominio especificado con el del certificado instalado en el punto de conexión de VPC. Puede utilizar una variable de etapa para hacer referencia al ID de `VpcLinkV2`. También puede asignar el valor del ID directamente a `connectionId`. El archivo de OpenAPI con formato JSON contiene un ejemplo de una API con un enlace VPC al que hace referencia una variable de etapa (`${stageVariables.vpcLinkIdV2}`): ``` { "swagger": "2.0", "info": { "version": "2017-11-17T04:40:23Z", "title": "MyApiWithVpcLinkV2" }, "host": "abcdef123.execute-api.us-west-2.amazonaws.com", "basePath": "/test", "schemes": [ "https" ], "paths": { "/": { "get": { "produces": [ "application/json" ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } } }, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "uri": "https://example.com:443/path", "passthroughBehavior": "when_no_match", "connectionType": "VPC_LINK", "connectionId": "${stageVariables.vpcLinkV2Id}", "integration-target": "arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011", "httpMethod": "GET", "type": "http_proxy" } } } }, "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ ## Actualización de una integración privada En el siguiente ejemplo se actualiza el enlace de VPC V2 para una integración privada. ------ #### [ Consola de administración de AWS ] **Actualización de una integración privada** 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST con una integración privada. 1. Elija el recurso y el método que utiliza una integración privada. 1. En la pestaña **Solicitud de integración**, en **Configuración de solicitud de integración**, elija **Editar**. 1. Puede editar la configuración de la integración privada. Si actualmente utiliza un enlace de VPC V1, puede cambiar el enlace de la VPC por un enlace de VPC V2. 1. Seleccione **Save**. 1. Vuelva a implementar la API para que los cambios se apliquen. ------ #### [ AWS CLI ] El siguiente comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) actualiza una integración privada para usar un enlace de VPC V2: ``` aws apigateway update-integration \ --rest-api-id a1b2c3d4e5 \ --resource-id a1b2c3 \ --http-method GET \ --patch-operations "[{\"op\":\"replace\",\"path\":\"/connectionId\",\"value\":\"pk0000\"}, {\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"http://example.com\"}, {\"op\":\"replace\",\"path\":\"/integrationTarget\",\"value\":\"arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011\"}]" ``` ------ # Integración privada mediante enlaces de VPC V1 (heredado) **nota** La siguiente implementación de integraciones privadas utiliza enlaces de VPC V1. Los enlaces de VPC V1 son recursos heredados. Se recomienda utilizar los [enlaces de VPC V2 para las API de REST](apigateway-vpc-links-v2.md). Para crear una integración privada, primero debe crear un Network Load Balancer. El Network Load Balancer debe tener un [agente de escucha](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html) que envíe las solicitudes a los recursos de la VPC. Para mejorar la disponibilidad de la API, asegúrese de que el Network Load Balancer dirija el tráfico a los recursos de varias zonas de disponibilidad de Región de AWS. A continuación, debe crear un vínculo de VPC que utilizará para conectar la API y el Network Load Balancer. Después de crear un vínculo de VPC, se crean integraciones privadas para enviar el tráfico de la API a los recursos de esta a través de dicho vínculo y el Network Load Balancer. El equilibrador de carga de red y la API deben pertenecer a la misma Cuenta de AWS. **Topics** + [ # Configuración de un equilibrador de carga de red para integraciones privadas de API Gateway (heredado) ](set-up-nlb-for-vpclink-using-console.md) + [ # Concesión de permisos para API Gateway para crear un enlace de VPC (heredado) ](grant-permissions-to-create-vpclink.md) + [ # Configuración de una API de API Gateway con integraciones privadas a través de la AWS CLI (heredado) ](set-up-api-with-vpclink-cli.md) + [ # Cuentas de API Gateway utilizadas para integraciones privadas (heredado) ](set-up-api-with-vpclink-accounts.md) # Configuración de un equilibrador de carga de red para integraciones privadas de API Gateway (heredado) **nota** La siguiente implementación de integraciones privadas utiliza enlaces de VPC V1. Los enlaces de VPC V1 son recursos heredados. Se recomienda utilizar los [enlaces de VPC V2 para las API de REST](apigateway-vpc-links-v2.md). En el siguiente procedimiento, se describen los pasos necesarios para configurar un Network Load Balancer para integraciones privadas de API Gateway utilizando la consola de Amazon EC2 y se incluyen referencias a instrucciones detalladas sobre cada paso. Para cada VPC en la que disponga de recursos, solo necesita configurar un NLB y un VPCLink. El NLB admite varios [agentes de escucha](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html) y [grupos de destino](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html) por NLB. Puede configurar cada servicio como un agente de escucha específico en el NLB y utilizar un único VPCLink para conectarse al NLB. Al crear la integración privada en API Gateway, defina cada servicio utilizando el puerto específico asignado a cada servicio. Para obtener más información, consulte [Tutorial: Creación de una API de REST con una integración privada](getting-started-with-private-integration.md). El equilibrador de carga de red y la API deben pertenecer a la misma Cuenta de AWS. **Si desea crear un Network Load Balancer privada para una integración privada con la consola de API Gateway** 1. Inicie sesión en la Consola de administración de AWS y abra la consola de Amazon EC2 en [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. Instale un servidor web en una instancia de Amazon EC2. Para ver una configuración de ejemplo, consulte [Instalación de un servidor web LAMP en Amazon Linux 2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-lamp-amazon-linux-2.html). 1. Cree un Network Load Balancer, registre la instancia EC2 con un grupo de destino y agregue el grupo de destino a un agente de escucha del Network Load Balancer. Para obtener información más detallada, siga las instrucciones que se describen en [Introducción a los balanceadores de carga de red](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancer-getting-started.html). 1. Una vez que se haya creado el equilibrador de carga de red, haga lo siguiente: 1. Anote el ARN del equilibrador de carga de red. Lo necesitará para crear un enlace VPC en API Gateway e integrar la API con los recurso de la VPC detrás del Network Load Balancer. 1. Desactive la evaluación del grupo de seguridad para PrivateLink. + Para desactivar la evaluación de grupos de seguridad para el tráfico de PrivateLink mediante la consola, puede seleccionar la pestaña **Seguridad** y, a continuación, **Editar**. En **Configuración de seguridad**, seleccione **Aplicar reglas de entrada al tráfico de PrivateLink**. + Utilice el siguiente comando [set-security-groups](https://docs.aws.amazon.com/cli/latest/reference/elbv2/set-security-groups.html) para desactivar la evaluación de grupos de seguridad para el tráfico de PrivateLink: ``` aws elbv2 set-security-groups --load-balancer-arn arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/net/my-loadbalancer/abc12345 \ --security-groups sg-123345a --enforce-security-group-inbound-rules-on-private-link-traffic off ``` **nota** No agregue ninguna dependencia a los CIDR de API Gateway, ya que es probable que cambien sin previo aviso. # Concesión de permisos para API Gateway para crear un enlace de VPC (heredado) **nota** La siguiente implementación de integraciones privadas utiliza enlaces de VPC V1. Los enlaces de VPC V1 son recursos heredados. Se recomienda utilizar los [enlaces de VPC V2 para las API de REST](apigateway-vpc-links-v2.md). Para que usted o un usuario de la cuenta puedan crear y mantener un enlace VPC, deben tener permiso para crear, eliminar y consultar configuraciones de servicios de punto de conexión de VPC y examinar los balanceadores de carga. Para conceder este tipo de permisos, siga estos pasos. **Para conceder permisos para crear, actualizar y eliminar un enlace VPC** 1. Cree una política de IAM similar a la siguiente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "apigateway:POST", "apigateway:GET", "apigateway:PATCH", "apigateway:DELETE" ], "Resource": [ "arn:aws:apigateway:us-east-1::/vpclinks", "arn:aws:apigateway:us-east-1::/vpclinks/*" ] }, { "Effect": "Allow", "Action": [ "elasticloadbalancing:DescribeLoadBalancers" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2:CreateVpcEndpointServiceConfiguration", "ec2:DeleteVpcEndpointServiceConfigurations", "ec2:DescribeVpcEndpointServiceConfigurations", "ec2:ModifyVpcEndpointServicePermissions" ], "Resource": "*" } ] } ``` ------ Si desea habilitar el etiquetado para el enlace de VPC, asegúrese de permitir las operaciones de etiquetado. Para obtener más información, consulte [Permitir operaciones de etiquetado](apigateway-tagging-iam-policy.md#allow-tagging). 1. Cree o seleccione un rol de IAM y asocie la política anterior al rol. 1. Asigne el rol de IAM a sí mismo o al usuario de la cuenta que está creando los enlaces VPC. # Configuración de una API de API Gateway con integraciones privadas a través de la AWS CLI (heredado) **nota** La siguiente implementación de integraciones privadas utiliza enlaces de VPC V1. Los enlaces de VPC V1 son recursos heredados. Se recomienda utilizar los [enlaces de VPC V2 para las API de REST](apigateway-vpc-links-v2.md). En el siguiente tutorial se muestra cómo utilizar la AWS CLI para crear un enlace de VPC y una integración privada. Los siguientes requisitos previos son necesarios: + Es necesario haber creado y configurado un Equilibrador de carga de red con el origen de la VPC como el objetivo. Para obtener más información, consulte [Configuración de un equilibrador de carga de red para integraciones privadas de API Gateway (heredado)](set-up-nlb-for-vpclink-using-console.md). Este debe estar en la misma Cuenta de AWS que la API. Necesita el ARN del Equilibrador de carga de red para crear el enlace de la VPC. + Para crear y administrar un `VpcLink`, necesita los permisos necesarios para crear un `VpcLink` en la API. No necesita los permisos para utilizar el `VpcLink`. Para obtener más información, consulte [Concesión de permisos para API Gateway para crear un enlace de VPC (heredado)](grant-permissions-to-create-vpclink.md). **Para configurar una API con integración privada a través de la AWS CLI** 1. Utilice el siguiente comando [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-vpc-link.html) para crear un `VpcLink` que apunte al equilibrador de carga de red especificado: ``` aws apigateway create-vpc-link \ --name my-test-vpc-link \ --target-arns arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef ``` El resultado de este comando confirma la recepción de la solicitud y muestra el estado `PENDING` para `VpcLink` que se está creando. ``` { "status": "PENDING", "targetArns": [ "arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef" ], "id": "gim7c3", "name": "my-test-vpc-link" } ``` API Gateway tarda de 2 a 4 minutos en completar la creación de `VpcLink`. Si la operación finaliza correctamente, el valor de `status` es `AVAILABLE`. Puede verificarlo llamando al siguiente comando [get-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-vpc-link.html): ``` aws apigateway get-vpc-link --vpc-link-id gim7c3 ``` Si se produce un error en la operación, obtendrá el estado `FAILED` y `statusMessage` contendrá el mensaje de error. Por ejemplo, si intenta crear un enlace `VpcLink` con un equilibrador de carga de red que ya está asociado a un punto de conexión de VPC, obtendrá lo siguiente en la propiedad `statusMessage`: ``` "NLB is already associated with another VPC Endpoint Service" ``` Después de que se cree `VpcLink` correctamente, puede crear una API e integrarla con el recurso de la VPC a través de `VpcLink`. Anote el valor de `id` del `VpcLink` recién creado. En este resultado de ejemplo, es `gim7c3`. Lo necesitará para configurar la integración privada. 1. Utilice el siguiente comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) para crear un recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) de API Gateway: ``` aws apigateway create-rest-api --name 'My VPC Link Test' ``` Anote el valor de `id` de `RestApi` y el valor de `rootResourceId` de `RestApi` del resultado devuelto. Necesitará este valor para realizar otras operaciones en la API. A continuación, cree una API con solo un método `GET` en el recurso raíz (`/`) e integre el método con el `VpcLink`. 1. Utilice el siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) para crear el método `GET /`: ``` aws apigateway put-method \ --rest-api-id abcdef123 \ --resource-id skpp60rab7 \ --http-method GET \ --authorization-type "NONE" ``` Si no utiliza la integración de proxy con `VpcLink`, también debe configurar al menos un método de respuesta del código de estado `200`. En este caso, utilizará la integración de proxy. 1. Tras crear el método `GET /`, se configura la integración. En el caso de una integración privada, se utiliza el parámetro `connection-id` para proporcionar el ID de `VpcLink`. Puede utilizar una variable de fase o ingresar directamente el ID de `VpcLink`. El parámetro `uri` no se utiliza para direccionar las solicitudes al punto de conexión, sino para configurar el encabezado `Host` y validar el certificado. ------ #### [ Use the VPC link ID ] Utilice el siguiente comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) para usar el ID de `VpcLink` directamente en la integración: ``` aws apigateway put-integration \ --rest-api-id abcdef123 \ --resource-id skpp60rab7 \ --uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id gim7c3 ``` ------ #### [ Use a stage variable ] Utilice el siguiente comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) para usar una variable de etapa para hacer referencia al ID de enlace de VPC. Cuando implementa la API en una etapa, se establece el ID de enlace de la VPC. ``` aws apigateway put-integration \ --rest-api-id abcdef123 \ --resource-id skpp60rab7 \ --uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id "\${stageVariables.vpcLinkId}" ``` No olvide utilizar comillas dobles en la expresión de la variable de etapa (`${stageVariables.vpcLinkId}`) y utilizar caracteres de escape con `$`. ------ En cualquier momento, también puede actualizar la integración para cambiar el `connection-id`. Utilice el siguiente comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) para actualizar su integración: ``` aws apigateway update-integration \ --rest-api-id abcdef123 \ --resource-id skpp60rab7 \ --http-method GET \ --patch-operations '[{"op":"replace","path":"/connectionId","value":"${stageVariables.vpcLinkId}"}]' ``` No olvide utilizar una lista JSON con forma de cadena como valor del parámetro `patch-operations`. Puesto que ha utilizado la integración de proxy privada, ahora la API está lista para la implementación y ejecuciones de pruebas. 1. Si usó la variable de etapa para definir el `connection-id`, necesita implementar la API para probarla. Utilice el siguiente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) para implementar la API con una variable de etapa: ``` aws apigateway create-deployment \ --rest-api-id abcdef123 \ --stage-name test \ --variables vpcLinkId=gim7c3 ``` Para actualizar la variable de etapa con un ID de `VpcLink` diferente (por ejemplo, `asf9d7`), utilice el siguiente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html): ``` aws apigateway update-stage \ --rest-api-id abcdef123 \ --stage-name test \ --patch-operations op=replace,path='/variables/vpcLinkId',value='asf9d7' ``` Si codifica la propiedad `connection-id` con el literal del ID de `VpcLink`, no necesita implementar la API para probarla. Use el comando [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html) para probar la API antes de implementarla. 1. Use los siguientes comandos para invocar la API: ``` curl -X GET https://abcdef123.execute-api.us-east-2.amazonaws.com/test ``` Si lo desea, también puede ingresar la URL de invocación de la API en un navegador web para ver los resultados. # Cuentas de API Gateway utilizadas para integraciones privadas (heredado) Los siguientes ID de cuenta de API Gateway específicos de la región se agregan automáticamente al servicio de punto de conexión de VPC como `AllowedPrincipals` cuando se crea un `VpcLink`. | **Región** | **ID de cuenta** | | --- | --- | | us-east-1 | 392220576650 | | us-east-2 | 718770453195 | | us-west-1 | 968246515281 | | us-west-2 | 109351309407 | | ca-central-1 | 796887884028 | | eu-west-1 | 631144002099 | | eu-west-2 | 544388816663 | | eu-west-3 | 061510835048 | | eu-central-1 | 474240146802 | | eu-central-2 | 166639821150 | | eu-north-1 | 394634713161 | | eu-south-1 | 753362059629 | | eu-south-2 | 359345898052 | | ap-northeast-1 | 969236854626 | | ap-northeast-2 | 020402002396 | | ap-northeast-3 | 360671645888 | | ap-southeast-1 | 195145609632 | | ap-southeast-2 | 798376113853 | | ap-southeast-3 | 652364314486 | | ap-southeast-4 | 849137399833 | | ap-south-1 | 507069717855 | | ap-south-2 | 644042651268 | | ap-east-1 | 174803364771 | | sa-east-1 | 287228555773 | | me-south-1 | 855739686837 | | me-central-1 | 614065512851 | # Simulación de integraciones para las API de REST en API Gateway Amazon API Gateway admite integraciones simuladas para métodos API. Esta característica permite a los desarrolladores de API generar respuestas de API directamente desde API Gateway sin necesidad de un backend de integración. Como desarrollador de una API, puede utilizar esta característica para que los equipos dependientes puedan trabajar con una API antes de que se complete el desarrollo del proyecto. También puede usar esta característica para aprovisionar una página de inicio para la API, en la que se proporcione una descripción general de la API y cómo navegar por ella. Para ver un ejemplo de una página de inicio como esta, consulte la solicitud y la respuesta de integración del método GET en el recurso raíz de la API de ejemplo que se describe en [Tutorial: Crear una API de REST importando un ejemplo](api-gateway-create-api-from-example.md). Como desarrollador de una API, puede decidir cómo API Gateway responde a una solicitud de integración simulada. Para ello, configura la solicitud de integración y la respuesta de integración del método para asociar una respuesta a un código de estado determinado. Para que un método con la integración simulada devuelva una respuesta `200`, configure la plantilla de asignación del cuerpo de la solicitud de integración para que devuelva lo siguiente. ``` {"statusCode": 200} ``` Configure una respuesta de integración `200` para que tenga la siguiente plantilla de asignación de cuerpo; por ejemplo: ``` { "statusCode": 200, "message": "Go ahead without me." } ``` De igual modo, para que el método devuelva, por ejemplo, una respuesta de error `500`, configure la plantilla de asignación del cuerpo de la solicitud de integración para que devuelva lo siguiente. ``` {"statusCode": 500} ``` Configure una respuesta de integración `500` con, por ejemplo, la siguiente plantilla de asignación: ``` { "statusCode": 500, "message": "The invoked method is not supported on the API resource." } ``` Si lo desea, también puede hacer que un método de la integración simulada devuelva la respuesta de integración predeterminada sin definir la plantilla de asignación de solicitudes de integración. La respuesta de integración predeterminada es la única que tiene la opción **HTTP status regex (Expresión regular de estado de HTTP)** sin definir. Asegúrese de que se establecen los comportamientos de acceso directo apropiados. **nota** Las integraciones simuladas no se han diseñado para admitir plantillas de respuestas grandes. Si las necesita para su caso de uso, considere el uso de una integración de Lambda en su lugar. Si utiliza una plantilla de asignación de solicitudes de integración, puede insertar la lógica de la aplicación para decidir qué respuesta de integración simulada debe devolverse en función de unas determinadas condiciones. Por ejemplo, puede utilizar un parámetro de consulta `scope` en la solicitud de entrada para determinar si se va a devolver una respuesta de éxito o error: ``` { #if( $input.params('scope') == "internal" ) "statusCode": 200 #else "statusCode": 500 #end } ``` De esta forma, el método de la integración simulada permite realizar llamadas internas mientras que otros tipos de llamadas se rechazan con respuestas de error. En esta sección, se describe cómo utilizar la consola de API Gateway para habilitar la integración simulada para un método de la API. **Topics** + [ # Habilitar la integración simulada a través de la consola de API Gateway ](how-to-mock-integration-console.md) # Habilitar la integración simulada a través de la consola de API Gateway Debe tener un método disponible en API Gateway. Siga las instrucciones en [Tutorial: Creación de una API de REST con integración no de proxy HTTP](api-gateway-create-api-step-by-step.md). 1. Elija un recurso de API y seleccione **Crear método**. Para configurar el método, haga lo siguiente: 1. En **Tipo de método**, seleccione un método. 1. En **Tipo de integración**, seleccione **Simulación**. 1. Elija **Crear método**. 1. En la pestaña **Solicitud de método**, en **Configuración de solicitud de método**, elija **Editar**. 1. Elija **Parámetros de cadenas de consulta de URL**. Elija **Añadir cadena de consulta** y, en **Nombre**, introduzca **scope**. Este parámetro de consulta determina si el intermediario es o no interno. 1. Seleccione **Save**. 1. En la pestaña **Respuesta de método**, elija **Crear respuesta** y, a continuación, haga lo siguiente: 1. En **Estado HTTP**, escriba **500**. 1. Seleccione **Save**. 1. En la pestaña **Solicitud de integración**, en **Configuración de la solicitud de integración**, seleccione **Editar**. 1. Elija **Plantillas de mapeo** y, a continuación, haga lo siguiente: 1. Elija **Add mapping template (Añadir plantilla de asignación)**. 1. En **Tipo de contenido**, ingrese **application/json**. 1. En **Cuerpo de la plantilla**, introduzca lo siguiente: ``` { #if( $input.params('scope') == "internal" ) "statusCode": 200 #else "statusCode": 500 #end } ``` 1. Seleccione **Save**. 1. En la pestaña **Respuesta de integración**, en **Predeterminado: respuesta**, elija **Editar**. 1. Elija **Plantillas de mapeo** y, a continuación, haga lo siguiente: 1. En **Tipo de contenido**, ingrese **application/json**. 1. En **Cuerpo de la plantilla**, introduzca lo siguiente: ``` { "statusCode": 200, "message": "Go ahead without me" } ``` 1. Seleccione **Save**. 1. Elija **Crear respuesta**. Para crear una respuesta 500, haga lo siguiente: 1. En **Expresión regular de estado de HTTP**, escriba **5\$1d\$12\$1**. 1. En **Estado de respuesta del método**, seleccione **500**. 1. Seleccione **Save**. 1. En **5\$1d\$12\$1 - Respuesta**, seleccione **Editar**. 1. Elija **Plantillas de mapeo** y, a continuación, elija **Agregar plantilla de mapeo**. 1. En **Tipo de contenido**, ingrese **application/json**. 1. En **Cuerpo de la plantilla**, introduzca lo siguiente: ``` { "statusCode": 500, "message": "The invoked method is not supported on the API resource." } ``` 1. Seleccione **Save**. 1. Elija la pestaña **Prueba**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña. Para probar la integración simulada, haga lo siguiente: 1. Escriba `scope=internal` en **Cadenas de consulta**. Seleccione **Probar** El resultado de la prueba es: ``` Request: /?scope=internal Status: 200 Latency: 26 ms Response Body { "statusCode": 200, "message": "Go ahead without me" } Response Headers {"Content-Type":"application/json"} ``` 1. Escriba `scope=public` en `Query strings` o déjelo en blanco. Seleccione **Probar** El resultado de la prueba es: ``` Request: / Status: 500 Latency: 16 ms Response Body { "statusCode": 500, "message": "The invoked method is not supported on the API resource." } Response Headers {"Content-Type":"application/json"} ``` También puede devolver los encabezados de una respuesta de integración simulada agregando primero un encabezado a la respuesta del método y configurando después una asignación de encabezado en la respuesta de integración. De hecho, es así como la consola de API Gateway permite la compatibilidad con CORS, devolviendo los encabezados requeridos por CORS. # Solicitud de la validación de las API de REST en API Gateway Puede configurar API Gateway para que realice una validación básica de una solicitud de API antes de continuar con la solicitud de integración. Cuando no se supera la validación, API Gateway invalida inmediatamente la solicitud, devuelve una respuesta de error 400 al intermediario y publica los resultados de la validación en logs de CloudWatch Logs. Esto reduce las llamadas innecesarias al backend. Y lo que es más importante, le permite centrarse en el trabajo de validación específico de su aplicación. Para validar el cuerpo de una solicitud, debe verificar que los parámetros obligatorios de la solicitud sean válidos y no nulos o especificar un esquema de modelo para una validación de datos más complicada. **Topics** + [ ## Información general de la validación básica de solicitudes en API Gateway ](#api-gateway-request-validation-basic-definitions) + [ # Modelos de datos para las API de REST ](models-mappings-models.md) + [ # Configuración de la validación básica de solicitudes en API Gateway ](api-gateway-request-validation-set-up.md) + [ # Plantilla de AWS CloudFormation de una API de ejemplo con validación de solicitudes básica ](api-gateway-request-validation-sample-cloudformation.md) ## Información general de la validación básica de solicitudes en API Gateway API Gateway puede realizar la validación básica de las solicitudes, de modo que pueda centrarse en la validación específica de la aplicación en el backend. Para la validación, API Gateway verifica una o ambas de las condiciones siguientes: + Los parámetros de la solicitud necesarios en el URI, la cadena de consulta y los encabezados de una solicitud de entrada están presentes y no están vacíos. API Gateway solo comprueba la existencia de un parámetro y no verifica el tipo ni el formato. + La carga útil de solicitud aplicable se adhiere a la solicitud de [esquema JSON](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) configurada del método para un tipo de contenido determinado. Si no se encuentra ningún tipo de contenido coincidente, no se realiza la validación de la solicitud. Para utilizar el mismo modelo independientemente del tipo de contenido, establezca el tipo de contenido para el modelo de datos en `$default`. Para habilitar la validación, debe especificar reglas de validación en un [validador de solicitudes](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html), agregar el validador al [mapa de validadores de solicitudes](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) de la API y asignar el validador a métodos de la API individuales. **nota** La validación del cuerpo de la solicitud y [Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway](integration-passthrough-behaviors.md) son dos temas distintos. Cuando una carga de solicitud no tiene ningún esquema de modelo coincidente, tiene la opción de elegir acceder directamente a ella o bloquear la carga original. Para obtener más información, consulte [Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway](integration-passthrough-behaviors.md). # Modelos de datos para las API de REST En API Gateway, un modelo define la estructura de datos de una carga. En API Gateway, los modelos se definen mediante el [borrador 4 del esquema JSON](https://tools.ietf.org/html/draft-zyp-json-schema-04). El siguiente objeto JSON incluye datos de muestra del ejemplo de la tienda de mascotas (Pet Store). ``` { "id": 1, "type": "dog", "price": 249.99 } ``` Los datos contienen el `id`, `type` y `price` de la mascota. Un modelo de estos datos le permite: + Utilizar la validación básica de solicitudes. + Crear plantillas de mapeo para la transformación de datos. + Crear un tipo de datos definido por el usuario (UDT) al generar un SDK. ![\[Ejemplo de modelo de datos JSON para la API de PetStore.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/how-to-validate-requests.png) En este modelo: 1. El objeto `$schema` representa un identificador de versión válido del esquema JSON. Este esquema es la versión 4 del borrador del esquema JSON. 1. El objeto `title` es un identificador descriptivo del modelo. Este título es `PetStoreModel`. 1. La palabra clave de validación `required` requiere `type` y `price` para la validación básica de solicitudes. 1. Las `properties` del modelo son `id`, `type` y `price`. Cada objeto tiene propiedades que se describen en el modelo. 1. El objeto `type` solo puede tener los valores `dog`, `cat` o `fish`. 1. El objeto `price` es un número y está restringido con un valor `minimum` de 25 y un valor `maximum` de 500. ## Modelo PetStore ``` 1 { 2 "$schema": "http://json-schema.org/draft-04/schema#", 3 "title": "PetStoreModel", 4 "type" : "object", 5 "required" : [ "price", "type" ], 6 "properties" : { 7 "id" : { 8 "type" : "integer" 9 }, 10 "type" : { 11 "type" : "string", 12 "enum" : [ "dog", "cat", "fish" ] 13 }, 14 "price" : { 15 "type" : "number", 16 "minimum" : 25.0, 17 "maximum" : 500.0 18 } 19 } 20 } ``` En este modelo: 1. En la línea 2, el objeto `$schema` representa un identificador de versión válido del esquema JSON. Este esquema es la versión 4 del borrador del esquema JSON. 1. En la línea 3, el objeto `title` es un identificador descriptivo del modelo. Este título es `PetStoreModel`. 1. En la línea 5, la palabra clave de validación `required` requiere `type` y `price` para la validación básica de solicitudes. 1. En las líneas 6 a 17, las `properties` del modelo son `id`, `type` y `price`. Cada objeto tiene propiedades que se describen en el modelo. 1. En la línea 12, el objeto `type` solo puede tener los valores `dog`, `cat` o `fish`. 1. En las líneas 14 a 17, el objeto `price` es un número y está restringido con un valor `minimum` de 25 y un valor `maximum` de 500. ## Creación de modelos más complejos Puede utilizar la primitiva `$ref` para crear definiciones reutilizables para modelos más largos. Por ejemplo, puede crear una definición llamada `Price` en la sección `definitions` que describa el objeto `price`. El valor de `$ref` es la definición de `Price`. ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "PetStoreModelReUsableRef", "required" : ["price", "type" ], "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "price" : { "$ref": "#/definitions/Price" } }, "definitions" : { "Price": { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } } ``` También puede hacer referencia a otro esquema de modelo definido en un archivo de modelo externo. Defina el valor de la propiedad `$ref` en la ubicación del modelo. En el siguiente ejemplo, el modelo `Price` se define en el modelo `PetStorePrice` de la API `a1234`. ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "PetStorePrice", "type": "number", "minimum": 25, "maximum": 500 } ``` El modelo más largo puede hacer referencia al modelo `PetStorePrice`. ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "PetStoreModelReusableRefAPI", "required" : [ "price", "type" ], "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "price" : { "$ref": "https://apigateway.amazonaws.com/restapis/a1234/models/PetStorePrice" } } } ``` ## Uso de modelos de datos de salida Si transforma sus datos, puede definir un modelo de carga en la respuesta de integración. Se puede utilizar un modelo de carga al generar un SDK. Para lenguajes con establecimiento inflexible de tipos, como Java, Objective-C o Swift, el objeto se corresponde con un tipo de datos definido por el usuario (UDT). API Gateway crea un UDT si le facilita un modelo de datos al generar un SDK. Para obtener más información sobre las transformaciones de datos, consulte [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md). En el siguiente ejemplo se muestran datos de salida de una respuesta de integración. ``` { [ { "description" : "Item 1 is a dog.", "askingPrice" : 249.99 }, { "description" : "Item 2 is a cat.", "askingPrice" : 124.99 }, { "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ] } ``` En el siguiente ejemplo se muestra un modelo de carga que describe los datos de salida. ``` { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PetStoreOutputModel", "type" : "object", "required" : [ "description", "askingPrice" ], "properties" : { "description" : { "type" : "string" }, "askingPrice" : { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } } ``` Con este modelo, puede llamar a un SDK para recuperar los valores de las propiedades `description` y `askingPrice` al leer las propiedades `PetStoreOutputModel[i].description` y `PetStoreOutputModel[i].askingPrice`. Si no se proporciona un modelo, API Gateway utiliza el modelo vacío para crear un UDT predeterminado. ## Pasos a seguir a continuación + En esta sección se proporcionan recursos que puede utilizar para obtener más información sobre los conceptos presentados en este tema. Puede seguir los tutoriales de validación de solicitudes: + [Configuración de la validación de solicitudes mediante la consola de API Gateway](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-in-console) + [Configuración de la validación básica de solicitudes mediante la AWS CLI](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-cli) + [Configuración de la validación básica de solicitudes con una definición de OpenAPI](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-importing-swagger) + Para obtener más información sobre la transformación de datos y las plantillas de asignación, [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md). # Configuración de la validación básica de solicitudes en API Gateway En esta sección se muestra cómo configurar la validación de solicitudes para API Gateway mediante la consola, la AWS CLI y una definición de OpenAPI. **Topics** + [ ## Configuración de la validación de solicitudes mediante la consola de API Gateway ](#api-gateway-request-validation-setup-in-console) + [ ## Configuración de la validación básica de solicitudes mediante la AWS CLI ](#api-gateway-request-validation-setup-cli) + [ ## Configuración de la validación básica de solicitudes con una definición de OpenAPI ](#api-gateway-request-validation-setup-importing-swagger) ## Configuración de la validación de solicitudes mediante la consola de API Gateway Para utilizar la consola de API Gateway para validar una solicitud, seleccione uno de los tres validadores para una solicitud de API: + **Validar el cuerpo**. + **Validar los parámetros de la cadena de consulta y los encabezados**. + **Validar el cuerpo, los parámetros de la cadena de consulta y los encabezados**. Al aplicar uno de los validadores en un método de la API, la consola de API Gateway lo agrega al mapa [RequestValidators](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) de la API. Para seguir este tutorial, utilizará una plantilla CloudFormation para crear una API de API Gateway incompleta. Esta API incompleta tiene un recurso `/validator` con los métodos `GET` y `POST`. Ambos métodos están integrados con el punto de conexión HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Configurará dos tipos de validación de solicitudes: + En el método `GET`, configurará la validación de solicitudes para los parámetros de la cadena de consulta URL. + En el método `POST`, configurará la validación de solicitudes para el cuerpo de la solicitud. Esto permitirá que solo ciertas llamadas a la API pasen a la API. Descargue y descomprima [la plantilla de creación de aplicaciones para CloudFormation](samples/request-validation-tutorial-console.zip). Usará esta plantilla para crear una API incompleta. Finalizará el resto de los pasos en la consola de API Gateway. **Para crear una pila de CloudFormation** 1. Abra la consola de CloudFormation en [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Seleccione **Create stack (Crear pila)** y, a continuación, seleccione **With new resources (standard) (Con nuevos recursos [estándar])**. 1. En **Specify template (Especificar plantilla)**, elija **Upload a template file (Cargar un archivo de plantilla)**. 1. Seleccione la plantilla que ha descargado. 1. Elija **Next (Siguiente)**. 1. En **Stack name (Nombre de pila)**, escriba **request-validation-tutorial-console** y, a continuación, elija **Next (Siguiente)**. 1. En **Configure stack options (Configurar opciones de pila)**, elija **Next (Siguiente)**. 1. Para **Capabilities** (Capacidades), sepa que CloudFormation puede crear recursos de IAM en su cuenta. 1. Elija **Siguiente** y, a continuación, elija **Enviar**. CloudFormation aprovisiona los recursos especificados en la plantilla. Puede tardar varios minutos en finalizar el aprovisionamiento de los recursos. Cuando el estado de la pila de CloudFormation sea **CREATE\$1COMPLETE**, estará listo para continuar con el paso siguiente. **Para seleccionar la API recién creada** 1. Seleccione la pila **request-validation-tutorial-console** recién creada. 1. Seleccione **Recursos**. 1. En **ID físico**, seleccione la API. Este enlace lo dirigirá a la consola de API Gateway. Antes de modificar los métodos `GET` y `POST`, debe crear un modelo. **Para crear un modelo** 1. Se requiere un modelo para usar la validación de solicitudes en el cuerpo de una solicitud entrante. Para crear un modelo, en el panel de navegación principal, elija **Modelos**. 1. Seleccione **Crear modelo**. 1. En **Nombre**, escriba **PetStoreModel**. 1. En **Tipo de contenido**, indique **application/json**. Si no se encuentra ningún tipo de contenido coincidente, no se realiza la validación de la solicitud. Para utilizar el mismo modelo independientemente del tipo de contenido, introduzca **\$1default**. 1. En **Descripción**, indique **My PetStore Model** como descripción del modelo. 1. En **Esquema del modelo**, pegue el siguiente modelo en el editor de código y seleccione **Crear**. ``` { "type" : "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "name" : { "type" : "string" }, "price" : { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } } ``` Para obtener más información acerca del modelo, consulte [Modelos de datos para las API de REST](models-mappings-models.md). **Para configurar la validación de solicitudes para un método `GET`** 1. En el panel de navegación principal, seleccione **Recursos** y, a continuación, seleccione el método **GET**. 1. En la pestaña **Solicitud de método**, en **Configuración de solicitud de método**, elija **Editar**. 1. En **Validador de solicitud**, seleccione **Validar parámetros de cadena de consulta y encabezados**. 1. En **Parámetros de cadenas de consulta de URL**, haga lo siguiente: 1. Elija **Añadir cadena de consulta**. 1. En **Nombre**, escriba **petType**. 1. Active la opción **Obligatorio**. 1. Mantenga **Almacenamiento en caché** desactivado. 1. Seleccione **Save**. 1. En la pestaña **Solicitud de integración**, en **Configuración de la solicitud de integración**, seleccione **Editar**. 1. En **Parámetros de cadenas de consulta de URL**, haga lo siguiente: 1. Elija **Añadir cadena de consulta**. 1. En **Nombre**, escriba **petType**. 1. En **Asignado desde**, introduzca **method.request.querystring.petType**. Esto mapea el **petType** con el tipo de mascota. Para obtener más información sobre el mapeo de datos, consulte [el tutorial de mapeo de datos](set-up-data-transformations-in-api-gateway.md#mapping-example-console). 1. Mantenga **Almacenamiento en caché** desactivado. 1. Seleccione **Save**. **Para probar la validación de solicitudes para el método `GET`** 1. Elija la pestaña **Prueba**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña. 1. En **Cadenas de consulta**, introduzca **petType=dog** y seleccione **Prueba**. 1. La prueba del método dará como resultado `200 OK` y mostrará una lista de perros. Para obtener información sobre cómo transformar estos datos de salida, consulte el [tutorial de mapeo de datos.](set-up-data-transformations-in-api-gateway.md#mapping-example-console) 1. Elimine **petType=dog** y seleccione **Pruebas**. 1. La prueba del método devolverá un error `400` con el siguiente mensaje de error: ``` { "message": "Missing required request parameters: [petType]" } ``` **Para configurar la validación de solicitudes para el método `POST`** 1. En el panel de navegación principal, seleccione **Recursos** y, a continuación, seleccione el método **POST**. 1. En la pestaña **Solicitud de método**, en **Configuración de solicitud de método**, elija **Editar**. 1. En **Validador de solicitudes**, seleccione **Validar cuerpo**. 1. En **Cuerpo de la solicitud**, seleccione **Agregar modelo**. 1. En **Tipo de contenido**, ingrese **application/json**. Si no se encuentra ningún tipo de contenido coincidente, no se realiza la validación de la solicitud. Para utilizar el mismo modelo independientemente del tipo de contenido, introduzca  `$default`. En **Modelo**, seleccione **PetStoreModel**. 1. Seleccione **Save**. **Para probar la validación de solicitudes para un método `POST`** 1. Elija la pestaña **Prueba**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña. 1. En **Cuerpo de la solicitud**, pegue lo siguiente en el editor de código: ``` { "id": 2, "name": "Bella", "type": "dog", "price": 400 } ``` Seleccione **Probar** 1. La prueba del método devolverá `200 OK` y un mensaje de éxito. 1. En **Cuerpo de la solicitud**, pegue lo siguiente en el editor de código: ``` { "id": 2, "name": "Bella", "type": "dog", "price": 4000 } ``` Seleccione **Probar** 1. La prueba del método devolverá un error `400` con el siguiente mensaje de error: ``` { "message": "Invalid request body" } ``` En la parte inferior de los registros de pruebas, se mostrará el motivo por el que el cuerpo de la solicitud no es válido. En este caso, el precio de la mascota estaba fuera del máximo especificado en el modelo. **Para eliminar una pila de CloudFormation** 1. Abra la consola de CloudFormation en [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Seleccione su pila de CloudFormation. 1. Elija **Delete (Eliminar)** y, a continuación, confirme su elección. ### Pasos a seguir a continuación + Para obtener información sobre cómo transformar estos datos de salida y realizar más mapeos de datos, consulte el [tutorial de mapeo de datos.](set-up-data-transformations-in-api-gateway.md#mapping-example-console) + Siga el tutorial [Configuración de la validación básica de solicitudes mediante la AWS CLI](#api-gateway-request-validation-setup-cli) para realizar pasos similares con la AWS CLI. ## Configuración de la validación básica de solicitudes mediante la AWS CLI Puede crear un validador para configurar la validación de solicitudes mediante la AWS CLI Para seguir este tutorial, utilizará una plantilla CloudFormation para crear una API de API Gateway incompleta. **nota** Esta no es la misma plantilla de CloudFormation que la del tutorial de la consola. Con un recurso `/validator` preexpuesto, creará los métodos `GET` y `POST`. Ambos métodos están integrados con el punto de conexión HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Configurará las dos validaciones de solicitudes siguientes: + En el método `GET`, creará un validador `params-only` para validar los parámetros de la cadena de consulta de URL. + En el método `POST`, creará un validador `body-only` para validar el cuerpo de la solicitud. Esto permitirá que solo ciertas llamadas a la API pasen a la API. **Para crear una pila de CloudFormation** Descargue y descomprima [la plantilla de creación de aplicaciones para CloudFormation](samples/request-validation-tutorial-cli.zip). Para completar el siguiente tutorial, necesita la [versión 2 de la AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). Para comandos largos, se utiliza un carácter de escape (`\`) para dividir un comando en varias líneas. **nota** En Windows, algunos comandos de la CLI de Bash que utiliza habitualmente (por ejemplo, `zip`) no son compatibles con los terminales integrados del sistema operativo. Para obtener una versión de Ubuntu y Bash integrada con Windows, [instale el subsistema de Windows para Linux](https://learn.microsoft.com/en-us/windows/wsl/install). Los comandos de la CLI de ejemplo de esta guía utilizan el formato Linux. Los comandos que incluyen documentos JSON en línea deben reformatearse si utiliza la CLI de Windows. 1. Utilice el siguiente comando para crear la pila CloudFormation. ``` aws cloudformation create-stack --stack-name request-validation-tutorial-cli --template-body file://request-validation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM ``` 1. CloudFormation aprovisiona los recursos especificados en la plantilla. Puede tardar varios minutos en finalizar el aprovisionamiento de los recursos. Use el siguiente comando para ver el estado de su pila CloudFormation. ``` aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli ``` 1. Cuando el estado de su pila CloudFormation sea `StackStatus: "CREATE_COMPLETE"`, utilice el siguiente comando para recuperar los valores de salida relevantes para los pasos futuros. ``` aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}" ``` A continuación se muestran los valores de salida: + ApiID, que es el identificador de la API. Para este tutorial, el ID de la API es `abc123`. + ResourceId, que es el identificador del recurso del validador donde están expuestos los métodos `GET` y `POST`. Para este tutorial, el ID del recurso es `efg456`. **Para crear los validadores de solicitudes e importar un modelo** 1. Se requiere un validador para utilizar la validación de solicitudes con la AWS CLI. Utilice el siguiente comando para crear un validador que valide únicamente los parámetros de la solicitud. ``` aws apigateway create-request-validator --rest-api-id abc123 \ --no-validate-request-body \ --validate-request-parameters \ --name params-only ``` Anote el ID del validador `params-only`. 1. Utilice el siguiente comando para crear un validador que valide únicamente el cuerpo de la solicitud. ``` aws apigateway create-request-validator --rest-api-id abc123 \ --validate-request-body \ --no-validate-request-parameters \ --name body-only ``` Anote el ID del validador `body-only`. 1. Se requiere un modelo para usar la validación de solicitudes en el cuerpo de una solicitud entrante. Utilice el siguiente comando para importar un modelo. ``` aws apigateway create-model --rest-api-id abc123 --name PetStoreModel --description 'My PetStore Model' --content-type 'application/json' --schema '{"type": "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : {"type" : "integer"},"type" : {"type" : "string", "enum" : [ "dog", "cat", "fish" ]},"name" : { "type" : "string"},"price" : {"type" : "number","minimum" : 25.0, "maximum" : 500.0}}}}' ``` Si no se encuentra ningún tipo de contenido coincidente, no se realiza la validación de la solicitud. Para utilizar el mismo modelo independientemente del tipo de contenido, especifique `$default` como la clave. **Para crear los métodos `GET` y `POST`** 1. Use el siguiente comando para añadir el método HTTP `GET` en el recurso `/validate`. Este comando crea el método `GET`, agrega el validador `params-only` y establece la cadena de consulta `petType` según sea necesario. ``` aws apigateway put-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --authorization-type "NONE" \ --request-validator-id aaa111 \ --request-parameters "method.request.querystring.petType=true" ``` Use el siguiente comando para añadir el método HTTP `POST` en el recurso `/validate`. Este comando crea el método `POST`, agrega el validador `body-only` y adjunta el modelo al validador exclusivo para el cuerpo. ``` aws apigateway put-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --authorization-type "NONE" \ --request-validator-id bbb222 \ --request-models 'application/json'=PetStoreModel ``` 1. Use el siguiente comando para configurar la respuesta `200 OK` del método `GET /validate`. ``` aws apigateway put-method-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --status-code 200 ``` Use el siguiente comando para configurar la respuesta `200 OK` del método `POST /validate`. ``` aws apigateway put-method-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 ``` 1. Use el siguiente comando para configurar una `Integration` con un punto de conexión HTTP especificado para el método `GET /validation`. ``` aws apigateway put-integration --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --type HTTP \ --integration-http-method GET \ --request-parameters '{"integration.request.querystring.type" : "method.request.querystring.petType"}' \ --uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets' ``` Use el siguiente comando para configurar una `Integration` con un punto de conexión HTTP especificado para el método `POST /validation`. ``` aws apigateway put-integration --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --type HTTP \ --integration-http-method GET \ --uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets' ``` 1. Use el siguiente comando para configurar la respuesta de integración para el método `GET /validation`. ``` aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456\ --http-method GET \ --status-code 200 \ --selection-pattern "" ``` Use el siguiente comando para configurar la respuesta de integración para el método `POST /validation`. ``` aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 \ --selection-pattern "" ``` **Para probar el API** 1. Para probar el método `GET`, que realizará la validación de la solicitud para las cadenas de consulta, utilice el siguiente comando: ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --path-with-query-string '/validate?petType=dog' ``` El resultado devolverá `200 OK` y una lista de perros. 1. Use el siguiente comando para probar sin incluir la cadena de consulta `petType`. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET ``` El resultado devolverá un error `400`. 1. Para probar el método `POST`, que realizará la validación de la solicitud para el cuerpo de la solicitud, utilice el siguiente comando: ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --body '{"id": 1, "name": "bella", "type": "dog", "price" : 400 }' ``` El resultado devolverá `200 OK` y un mensaje de éxito. 1. Use el siguiente comando para probar el uso de un cuerpo no válido. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --body '{"id": 1, "name": "bella", "type": "dog", "price" : 1000 }' ``` El resultado devolverá un error `400`, ya que el precio del perro supera el precio máximo definido por el modelo. **Para eliminar una pila de CloudFormation** + Use el siguiente comando para eliminar los recursos CloudFormation. ``` aws cloudformation delete-stack --stack-name request-validation-tutorial-cli ``` ## Configuración de la validación básica de solicitudes con una definición de OpenAPI Puede declarar un validador de solicitudes en el nivel de la API especificando un conjunto de objetos [Objeto x-amazon-apigateway-request-validators.requestValidator](api-gateway-swagger-extensions-request-validators.requestValidator.md) en el mapa [Objeto x-amazon-apigateway-request-validators](api-gateway-swagger-extensions-request-validators.md) para seleccionar qué parte de la solicitud se validará. En la definición de OpenAPI de ejemplo hay dos validadores: + El validador `all`, que valida tanto el cuerpo, utilizando el modelo de datos `RequestBodyModel`, como los parámetros. El modelo de datos `RequestBodyModel` exige que el objeto JSON de entrada contenga las propiedades `name`, `type` y `price`. La propiedad `name` puede ser cualquier cadena, `type` debe ser uno de los campos de la enumeración especificada (`["dog", "cat", "fish"]`) y `price` debe estar comprendido entre 25 y 500. El parámetro `id` no es obligatorio. + `param-only`, que valida solo los parámetros. Para habilitar un validador de solicitudes en todos los métodos de una API, especifique una propiedad [Propiedad x-amazon-apigateway-request-validator](api-gateway-swagger-extensions-request-validator.md) en el nivel de la API de la definición de OpenAPI. En el ejemplo de definición de OpenAPI, el validador `all` se usa en todos los métodos de la API, a menos que se invalide de otro modo. Cuando se utiliza un modelo para validar el cuerpo, si no se encuentra ningún tipo de contenido coincidente, no se realiza la validación de la solicitud. Para utilizar el mismo modelo independientemente del tipo de contenido, especifique `$default` como la clave. Para habilitar un validador de solicitudes para un método individual, especifique la propiedad `x-amazon-apigateway-request-validator` en el nivel de método. En el ejemplo de definición de OpenAPI, el validador `param-only` anula el validador `all` del método `GET`. Para importar el ejemplo de OpenAPI a API Gateway, consulte las siguientes instrucciones para [Importación de una API regional en API Gateway](import-export-api-endpoints.md) o para [Importación de una API optimizada para bordes en API Gateway](import-edge-optimized-api.md). ------ #### [ OpenAPI 3.0 ] ``` { "openapi" : "3.0.1", "info" : { "title" : "ReqValidators Sample", "version" : "1.0.0" }, "servers" : [ { "url" : "/{basePath}", "variables" : { "basePath" : { "default" : "/v1" } } } ], "paths" : { "/validation" : { "get" : { "parameters" : [ { "name" : "q1", "in" : "query", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response", "headers" : { "test-method-response-header" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ArrayOfError" } } } } }, "x-amazon-apigateway-request-validator" : "params-only", "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "400", "responseParameters" : { "method.response.header.test-method-response-header" : "'static value'" }, "responseTemplates" : { "application/xml" : "xml 400 response template", "application/json" : "json 400 response template" } }, "2\\d{2}" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.querystring.type" : "method.request.querystring.q1" }, "passthroughBehavior" : "when_no_match", "type" : "http" } }, "post" : { "parameters" : [ { "name" : "h1", "in" : "header", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RequestBodyModel" } } }, "required" : true }, "responses" : { "200" : { "description" : "200 response", "headers" : { "test-method-response-header" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ArrayOfError" } } } } }, "x-amazon-apigateway-request-validator" : "all", "x-amazon-apigateway-integration" : { "httpMethod" : "POST", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "400", "responseParameters" : { "method.response.header.test-method-response-header" : "'static value'" }, "responseTemplates" : { "application/xml" : "xml 400 response template", "application/json" : "json 400 response template" } }, "2\\d{2}" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.custom_h1" : "method.request.header.h1" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } }, "components" : { "schemas" : { "RequestBodyModel" : { "required" : [ "name", "price", "type" ], "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "name" : { "type" : "string" }, "price" : { "maximum" : 500.0, "minimum" : 25.0, "type" : "number" } } }, "ArrayOfError" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Error" } }, "Error" : { "type" : "object" } } }, "x-amazon-apigateway-request-validators" : { "all" : { "validateRequestParameters" : true, "validateRequestBody" : true }, "params-only" : { "validateRequestParameters" : true, "validateRequestBody" : false } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger" : "2.0", "info" : { "version" : "1.0.0", "title" : "ReqValidators Sample" }, "basePath" : "/v1", "schemes" : [ "https" ], "paths" : { "/validation" : { "get" : { "produces" : [ "application/json", "application/xml" ], "parameters" : [ { "name" : "q1", "in" : "query", "required" : true, "type" : "string" } ], "responses" : { "200" : { "description" : "200 response", "schema" : { "$ref" : "#/definitions/ArrayOfError" }, "headers" : { "test-method-response-header" : { "type" : "string" } } } }, "x-amazon-apigateway-request-validator" : "params-only", "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "400", "responseParameters" : { "method.response.header.test-method-response-header" : "'static value'" }, "responseTemplates" : { "application/xml" : "xml 400 response template", "application/json" : "json 400 response template" } }, "2\\d{2}" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.querystring.type" : "method.request.querystring.q1" }, "passthroughBehavior" : "when_no_match", "type" : "http" } }, "post" : { "consumes" : [ "application/json" ], "produces" : [ "application/json", "application/xml" ], "parameters" : [ { "name" : "h1", "in" : "header", "required" : true, "type" : "string" }, { "in" : "body", "name" : "RequestBodyModel", "required" : true, "schema" : { "$ref" : "#/definitions/RequestBodyModel" } } ], "responses" : { "200" : { "description" : "200 response", "schema" : { "$ref" : "#/definitions/ArrayOfError" }, "headers" : { "test-method-response-header" : { "type" : "string" } } } }, "x-amazon-apigateway-request-validator" : "all", "x-amazon-apigateway-integration" : { "httpMethod" : "POST", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "400", "responseParameters" : { "method.response.header.test-method-response-header" : "'static value'" }, "responseTemplates" : { "application/xml" : "xml 400 response template", "application/json" : "json 400 response template" } }, "2\\d{2}" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.custom_h1" : "method.request.header.h1" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } }, "definitions" : { "RequestBodyModel" : { "type" : "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "name" : { "type" : "string" }, "price" : { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } }, "ArrayOfError" : { "type" : "array", "items" : { "$ref" : "#/definitions/Error" } }, "Error" : { "type" : "object" } }, "x-amazon-apigateway-request-validators" : { "all" : { "validateRequestParameters" : true, "validateRequestBody" : true }, "params-only" : { "validateRequestParameters" : true, "validateRequestBody" : false } } } ``` ------ # Plantilla de AWS CloudFormation de una API de ejemplo con validación de solicitudes básica La siguiente definición de plantilla de ejemplo de CloudFormation define una API de ejemplo con la validación de solicitudes habilitada. La API es un subconjunto de la [API PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets). Expone un método `POST` para añadir una mascota a la colección `pets` y un método `GET` para consultar las mascotas de un tipo especificado. Hay dos validadores de solicitudes declarados: **`GETValidator`** Este validador está habilitado en el método `GET`. Permite a API Gateway verificar que el parámetro de consulta obligatorio (`q1`) está incluido y no está en blanco en la solicitud de entrada. **`POSTValidator`** Este validador está habilitado en el método `POST`. Permite a API Gateway verificar que el formato de la solicitud de carga se adhiere al `RequestBodyModel` especificado cuando el tipo de contenido es `application/json` si no se encuentra un tipo de contenido coincidente, no se realiza la validación de la solicitud. Para utilizar el mismo modelo independientemente del tipo de contenido, especifique `$default`. `RequestBodyModel` contiene un modelo adicional, `RequestBodyModelId`, para definir el ID de mascota. ``` AWSTemplateFormatVersion: 2010-09-09 Parameters: StageName: Type: String Default: v1 Description: Name of API stage. Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: ReqValidatorsSample RequestBodyModelId: Type: 'AWS::ApiGateway::Model' Properties: RestApiId: !Ref Api ContentType: application/json Description: Request body model for Pet ID. Schema: $schema: 'http://json-schema.org/draft-04/schema#' title: RequestBodyModelId properties: id: type: integer RequestBodyModel: Type: 'AWS::ApiGateway::Model' Properties: RestApiId: !Ref Api ContentType: application/json Description: Request body model for Pet type, name, price, and ID. Schema: $schema: 'http://json-schema.org/draft-04/schema#' title: RequestBodyModel required: - price - name - type type: object properties: id: "$ref": !Sub - 'https://apigateway.amazonaws.com/restapis/${Api}/models/${RequestBodyModelId}' - Api: !Ref Api RequestBodyModelId: !Ref RequestBodyModelId price: type: number minimum: 25 maximum: 500 name: type: string type: type: string enum: - "dog" - "cat" - "fish" GETValidator: Type: AWS::ApiGateway::RequestValidator Properties: Name: params-only RestApiId: !Ref Api ValidateRequestBody: False ValidateRequestParameters: True POSTValidator: Type: AWS::ApiGateway::RequestValidator Properties: Name: body-only RestApiId: !Ref Api ValidateRequestBody: True ValidateRequestParameters: False ValidationResource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'validation' ValidationMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref ValidationResource HttpMethod: GET AuthorizationType: NONE RequestValidatorId: !Ref GETValidator RequestParameters: method.request.querystring.q1: true Integration: Type: HTTP_PROXY IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ ValidationMethodPost: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref ValidationResource HttpMethod: POST AuthorizationType: NONE RequestValidatorId: !Ref POSTValidator RequestModels: application/json : !Ref RequestBodyModel Integration: Type: HTTP_PROXY IntegrationHttpMethod: POST Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - ValidationMethodGet - RequestBodyModel Properties: RestApiId: !Ref Api StageName: !Sub '${StageName}' Outputs: ApiRootUrl: Description: Root Url of the API Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}' ``` # Transformaciones de datos para las API de REST en API Gateway **nota** En esta sección se explican las características que se utilizan con una integración sin proxy. No obstante, recomendamos que, siempre que sea posible, utilice una integración de proxy para la API de REST. Una integración de proxy HTTP tiene una configuración de integración simplificada y puede evolucionar con el backend sin tener que eliminar la configuración existente. Para obtener más información, consulte [Elegir un tipo de integración de API de API Gateway](api-gateway-api-integration-types.md). Si utiliza una integración sin proxy, puede utilizar dos características de API Gateway para transformar la solicitud de método y la respuesta de integración. Podría transformar la solicitud de método si esta tiene un formato de carga útil diferente al de la carga útil de la solicitud de integración. Podría transformar la respuesta de integración si devuelve un formato de carga útil diferente al formato que necesita devolver en la respuesta del método. Para obtener más información sobre el ciclo de vida de la solicitud, consulte [Recurso de ejemplo para una API de REST](rest-api-develop.md#rest-api-develop-example). En el siguiente ejemplo se muestra una transformación de datos en la que, para el encabezado `"x-version:beta"`, el parámetro de encabezado `x-version` se transforma en el parámetro de encabezado `app-version`. La transformación de datos de `x-version` a `app-version` se produce en la solicitud de integración. De esta manera, el punto de conexión de integración recibe el valor del parámetro de encabezado transformado. Cuando el punto de conexión de integración devuelve un código de estado, este se transforma de `200` a `204` antes de la respuesta de método. ![\[Diagrama de transformación de datos de API Gateway\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/develop-non-proxy.png) Para crear una transformación de datos, puede utilizar las siguientes características: **Asignación de parámetros** En la asignación de parámetros, puede modificar los parámetros de ruta de URL de solicitud de integración, los parámetros de cadena de consulta de URL o los valores de encabezado HTTP, pero no puede modificar la carga útil de solicitud de integración. También puede modificar los valores de encabezado de respuesta HTTP. Utilice la asignación de parámetros para crear valores de encabezado estáticos para el uso compartido de recursos entre orígenes (CORS). Puede usar la asignación de parámetros en la solicitud de integración para integraciones de proxy y de no proxy, pero para usar la asignación de parámetros para una respuesta de integración, necesita una integración de no proxy. La asignación de parámetros no requiere ningún script en [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Para obtener más información, consulte [Asignación de parámetros para las API de REST en API Gateway](rest-api-parameter-mapping.md). **Transformaciones de plantillas de asignación** En las transformaciones de plantillas de asignación, se utiliza una plantilla de asignación para asignar parámetros de ruta de URL, parámetros de cadena de consulta de URL, encabezados HTTP y el cuerpo de solicitud de integración o de respuesta de integración. Una *plantilla de asignación* es un script expresado en [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) mediante [expresiones JSONPath](https://goessner.net/articles/JsonPath/) y aplicado a la carga útil en función del encabezado `Content-type`. Con una plantilla de asignación, puede hacer lo siguiente: + Seleccionar los datos que desee enviar mediante la integración con Servicios de AWS, como las funciones de Amazon DynamoDB o de Lambda o los puntos de conexión HTTP. Para obtener más información, consulte [Tutorial: modificación de la solicitud y respuesta de integración para integraciones con servicios de AWS](set-up-data-transformations-in-api-gateway.md). + Anular condicionalmente los parámetros de solicitud de integración y de respuesta de integración de una API, crear nuevos valores de encabezado y anular códigos de estado. Para obtener más información, consulte [Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway](apigateway-override-request-response-parameters.md). También puede especificar el comportamiento de la API cuando el cuerpo de una solicitud de integración tenga un encabezado `Content-type` sin plantillas de asignación que coincidan. Esto se denomina comportamiento de acceso directo a la integración. Para obtener más información, consulte [Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway](integration-passthrough-behaviors.md). ## Elección entre la asignación de parámetros y las transformaciones de plantillas de asignación Le recomendamos que utilice la asignación de parámetros para transformar los datos siempre que sea posible. Si la API requiere que cambie el cuerpo o que realice modificaciones y anulaciones condicionales basadas en la solicitud de integración entrante o en la respuesta de integración y no puede utilizar una integración de proxy, utilice las transformaciones de plantillas de asignación. # Asignación de parámetros para las API de REST en API Gateway **nota** Si utiliza una API de HTTP, consulte [Transformación de las solicitudes y respuestas de API para las API HTTP en API Gateway](http-api-parameter-mapping.md). En la asignación de parámetros, asigne parámetros de solicitud o de respuesta. Puede asignar parámetros mediante expresiones de asignación de parámetros o valores estáticos. Para obtener una lista de expresiones de asignación, consulte [Referencia de origen de asignación de parámetros para las API de REST en API Gateway](rest-api-parameter-mapping-sources.md). Puede usar la asignación de parámetros en la solicitud de integración para integraciones de proxy y de no proxy, pero para usar la asignación de parámetros para una respuesta de integración, necesita una integración de no proxy. Por ejemplo, puede asignar el parámetro de encabezado de solicitud de método `puppies` al parámetro de encabezado de solicitud de integración `DogsAge0`. A continuación, si un cliente envía el encabezado `puppies:true` a la API, la solicitud de integración envía el encabezado de solicitud `DogsAge0:true` al punto de conexión de integración. En el siguiente diagrama se muestra el ciclo de vida de la solicitud de este ejemplo. ![\[Diagrama del ejemplo de asignación de parámetros de API Gateway para una solicitud\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/parameter-mapping-example1.png) Para crear este ejemplo con API Gateway, consulte [Ejemplo 1: asignar un parámetro de solicitud de método a un parámetro de solicitud de integración](request-response-data-mappings.md#request-response-data-mappings-example-1). Como otro ejemplo, también puede asignar el parámetro de encabezado de respuesta de integración `kittens` al parámetro de encabezado de respuesta de método `CatsAge0`. Si el punto de conexión de integración devuelve `kittens:false`, el cliente recibe el encabezado `CatsAge0:false`. En el siguiente diagrama se muestra el ciclo de vida de la solicitud de este ejemplo. ![\[Diagrama del ejemplo de asignación de parámetros de API Gateway para una respuesta\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/parameter-mapping-example2.png) **Topics** + [ # Ejemplos de asignación de parámetros para las API de REST en API Gateway ](request-response-data-mappings.md) + [ # Referencia de origen de asignación de parámetros para las API de REST en API Gateway ](rest-api-parameter-mapping-sources.md) # Ejemplos de asignación de parámetros para las API de REST en API Gateway En los siguientes ejemplos se muestra cómo crear expresiones de asignación de parámetros mediante la consola de API Gateway, OpenAPI y plantillas de CloudFormation. Para ver un ejemplo de cómo utilizar la asignación de parámetros para crear los encabezados CORS necesarios, consulte [CORS para las API de REST en API Gateway](how-to-cors.md). ## Ejemplo 1: asignar un parámetro de solicitud de método a un parámetro de solicitud de integración En el siguiente ejemplo se asigna el parámetro de encabezado de solicitud de método `puppies` al parámetro de encabezado de solicitud de integración `DogsAge0`. ------ #### [ Consola de administración de AWS ] **Asignación del parámetro de solicitud de método** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. Elija un método. El método debe tener una integración sin proxy. 1. En **Configuración de solicitud de método**, elija **Editar**. 1. Elija **Encabezados de solicitud HTTP**. 1. Elija **Agregar encabezado**. 1. En **Nombre**, escriba **puppies**. 1. Seleccione **Save**. 1. Elija la pestaña **Solicitud de integración** y, a continuación, en **Configuración de solicitud de integración**, elija **Editar**. La Consola de administración de AWS agrega automáticamente una asignación de parámetros de `method.request.header.puppies ` a `puppies` por usted, pero debe cambiar el **Nombre** para que coincida con el parámetro de encabezado de solicitud que espera el punto de conexión de integración. 1. En **Nombre**, escriba **DogsAge0**. 1. Seleccione **Save**. 1. Vuelva a implementar la API para que los cambios se apliquen. En los siguientes pasos se muestra cómo verificar que la asignación de parámetros se ha realizado correctamente. **(Opcional) Prueba de la asignación de parámetros** 1. Elija la pestaña **Prueba**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña. 1. Para los encabezados, introduzca **puppies:true**. 1. Seleccione **Probar** 1. En **Registros**, el resultado debería tener el siguiente aspecto: ``` Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true} Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations: Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344} ``` El parámetro de encabezado de solicitud ha cambiado de `puppies` a `DogsAge0`. ------ #### [ CloudFormation ] En este ejemplo, utiliza la propiedad [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar un archivo de definición de OpenAPI en API Gateway. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: ParameterMappingExample version: "2025-02-04T00:30:41Z" paths: /pets: get: parameters: - name: puppies in: header schema: type: string responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets responses: default: statusCode: "200" requestParameters: integration.request.header.DogsAge0: method.request.header.puppies passthroughBehavior: when_no_match type: http ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] ``` { "openapi" : "3.0.1", "info" : { "title" : "ParameterMappingExample", "version" : "2025-02-04T00:30:41Z" }, "paths" : { "/pets" : { "get" : { "parameters" : [ { "name" : "puppies", "in" : "header", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.DogsAge0" : "method.request.header.puppies" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } } } ``` ------ ## Ejemplo 2: asignar varios parámetros de solicitud de método a diferentes parámetros de solicitud de integración En el siguiente ejemplo, se asigna el parámetro de cadena de consulta de solicitud de método de varios valores `methodRequestQueryParam` al parámetro de cadena de consulta de solicitud de integración `integrationQueryParam` y se asigna el parámetro de encabezado de solicitud de método `methodRequestHeaderParam` al parámetro de ruta de solicitud de integración `integrationPathParam`. ------ #### [ Consola de administración de AWS ] **Asignación de los parámetros de solicitud de método** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. Elija un método. El método debe tener una integración sin proxy. 1. En **Configuración de solicitud de método**, elija **Editar**. 1. Elija **Parámetros de cadenas de consulta de URL**. 1. Elija **Añadir cadena de consulta**. 1. En **Nombre**, escriba **methodRequestQueryParam**. 1. Elija **Encabezados de solicitud HTTP**. 1. Elija **Agregar encabezado**. 1. En **Nombre**, escriba **methodRequestHeaderParam**. 1. Seleccione **Save**. 1. Elija la pestaña **Solicitud de integración** y, a continuación, en **Configuración de solicitud de integración**, elija **Editar**. 1. Elija los **Parámetros de la ruta URL**. 1. Elija **Añadir parámetro de ruta**. 1. En **Nombre**, escriba **integrationPathParam**. 1. En **Asignado desde**, introduzca **method.request.header.methodRequestHeaderParam**. Esto asigna el encabezado de solicitud de método que especificó en la solicitud de método a un nuevo parámetro de ruta de solicitud de integración. 1. Elija **Parámetros de cadenas de consulta de URL**. 1. Elija **Añadir cadena de consulta**. 1. En **Nombre**, escriba **integrationQueryParam**. 1. En **Asignado desde**, introduzca **method.request.multivaluequerystring.methodRequestQueryParam**. Esto asigna el parámetro de cadena de consulta de varios valores a un nuevo parámetro de cadena de consulta de solicitud de integración de valor único. 1. Seleccione **Save**. 1. Vuelva a implementar la API para que los cambios se apliquen. ------ #### [ CloudFormation ] En este ejemplo, utiliza la propiedad [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar un archivo de definición de OpenAPI en API Gateway. La siguiente definición de OpenAPI crea las siguientes asignaciones de parámetros para una integración de HTTP: + El encabezado de la solicitud de método, llamado `methodRequestHeaderParam`, al parámetro de ruta de la solicitud de integración, llamado `integrationPathParam` + La cadena de consulta de la solicitud de método de varios valores, llamada `methodRequestQueryParam`, a la cadena de consulta de la solicitud de integración, llamada `integrationQueryParam` ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: Parameter mapping example 2 version: "2025-01-15T19:12:31Z" paths: /: post: parameters: - name: methodRequestQueryParam in: query schema: type: string - name: methodRequestHeaderParam in: header schema: type: string responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets responses: default: statusCode: "200" requestParameters: integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam requestTemplates: application/json: '{"statusCode": 200}' passthroughBehavior: when_no_templates timeoutInMillis: 29000 type: http ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] La siguiente definición de OpenAPI crea las siguientes asignaciones de parámetros para una integración de HTTP: + El encabezado de la solicitud de método, llamado `methodRequestHeaderParam`, al parámetro de ruta de la solicitud de integración, llamado `integrationPathParam` + La cadena de consulta de la solicitud de método de varios valores, llamada `methodRequestQueryParam`, a la cadena de consulta de la solicitud de integración, llamada `integrationQueryParam` ``` { "openapi" : "3.0.1", "info" : { "title" : "Parameter mapping example 2", "version" : "2025-01-15T19:12:31Z" }, "paths" : { "/" : { "post" : { "parameters" : [ { "name" : "methodRequestQueryParam", "in" : "query", "schema" : { "type" : "string" } }, { "name" : "methodRequestHeaderParam", "in" : "header", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam", "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam" }, "requestTemplates" : { "application/json" : "{\"statusCode\": 200}" }, "passthroughBehavior" : "when_no_templates", "timeoutInMillis" : 29000, "type" : "http" } } } } } ``` ------ ## Ejemplo 3: asignar campos del cuerpo de la solicitud JSON a los parámetros de la solicitud de integración También puede asignar parámetros de solicitud de integración desde campos del cuerpo de la solicitud JSON mediante una [expresión JSONPath](http://goessner.net/articles/JsonPath/index.html#e2). El siguiente ejemplo asigna el cuerpo de solicitud de método a un encabezado de solicitud de integración denominado `body-header` y asigna parte del cuerpo de solicitud, expresado mediante una expresión JSON, a un encabezado de solicitud de integración denominado `pet-price`. Para probar este ejemplo, proporcione una entrada que contenga una categoría de precio, como la siguiente: ``` [ { "id": 1, "type": "dog", "price": 249.99 } ] ``` ------ #### [ Consola de administración de AWS ] **Asignación de los parámetros de solicitud de método** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. Elija un método `POST`, `PUT`, `PATCH` o `ANY`. El método debe tener una integración sin proxy. 1. En **Configuración de solicitud de integración**, elija **Editar**. 1. Elija **Parámetros de encabezado de solicitud de URL**. 1. Elija **Agregar parámetro de encabezado de solicitud**. 1. En **Nombre**, escriba **body-header**. 1. En **Asignado desde**, introduzca **method.request.body**. Esto asigna el cuerpo de solicitud de método a un nuevo parámetro de encabezado de solicitud de integración. 1. Elija **Agregar parámetro de encabezado de solicitud**. 1. En **Nombre**, escriba **pet-price**. 1. En **Asignado desde**, introduzca ** method.request.body[0].price**. Esto asigna una parte del cuerpo de solicitud de método a un nuevo parámetro de encabezado de solicitud de integración. 1. Seleccione **Save**. 1. Vuelva a implementar la API para que los cambios se apliquen. ------ #### [ CloudFormation ] En este ejemplo, utiliza la propiedad [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar un archivo de definición de OpenAPI en API Gateway. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: Parameter mapping example 3 version: "2025-01-15T19:19:14Z" paths: /: post: responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets responses: default: statusCode: "200" requestParameters: integration.request.header.pet-price: method.request.body[0].price integration.request.header.body-header: method.request.body requestTemplates: application/json: '{"statusCode": 200}' passthroughBehavior: when_no_templates timeoutInMillis: 29000 type: http ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] La siguiente definición de OpenAPI asigna los parámetros de solicitud de integración de los campos del cuerpo de solicitud JSON. ``` { "openapi" : "3.0.1", "info" : { "title" : "Parameter mapping example 3", "version" : "2025-01-15T19:19:14Z" }, "paths" : { "/" : { "post" : { "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.pet-price" : "method.request.body[0].price", "integration.request.header.body-header" : "method.request.body" }, "requestTemplates" : { "application/json" : "{\"statusCode\": 200}" }, "passthroughBehavior" : "when_no_templates", "timeoutInMillis" : 29000, "type" : "http" } } } } } ``` ------ ## Ejemplo 4: asignar la respuesta de integración a la respuesta de método También puede asignar la respuesta de integración a la respuesta de método. En el siguiente ejemplo se asigna el cuerpo de respuesta de integración a un encabezado de respuesta de método denominado `location`, se asigna el encabezado de respuesta de integración `x-app-id` al encabezado de respuesta de método `id` y se asigna el encabezado de respuesta de integración de varios valores `item` al encabezado de respuesta de método `items`. ------ #### [ Consola de administración de AWS ] **Asignación de la respuesta de integración** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. Elija un método. El método debe tener una integración sin proxy. 1. Elija la pestaña **Respuesta de método** y, a continuación, para **Respuesta 200**, elija **Editar**. 1. En **Nombre de encabezado**, elija **Agregar encabezado**. 1. Cree tres encabezados llamados **id**, **item** y **location**. 1. Seleccione **Save**. 1. Elija la pestaña **Respuesta de integración** y, a continuación, en **Predeterminado: respuesta**, elija **Editar**. 1. En **Asignaciones de encabezado**, introduzca lo siguiente. 1. En **id**, introduzca **integration.response.header.x-app-id** 1. En **item**, introduzca **integration.response.multivalueheader.item** 1. En **location**, introduzca **integration.response.body.redirect.url** 1. Seleccione **Save**. 1. Vuelva a implementar la API para que los cambios se apliquen. ------ #### [ CloudFormation ] En este ejemplo, utiliza la propiedad [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar un archivo de definición de OpenAPI en API Gateway. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: Parameter mapping example version: "2025-01-15T19:21:35Z" paths: /: post: responses: "200": description: 200 response headers: item: schema: type: string location: schema: type: string id: schema: type: string x-amazon-apigateway-integration: type: http httpMethod: GET uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets responses: default: statusCode: "200" responseParameters: method.response.header.id: integration.response.header.x-app-id method.response.header.location: integration.response.body.redirect.url method.response.header.item: integration.response.multivalueheader.item requestTemplates: application/json: '{"statusCode": 200}' passthroughBehavior: when_no_templates timeoutInMillis: 29000 ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] La siguiente definición de OpenAPI asigna la respuesta de integración a la respuesta de método. ``` { "openapi" : "3.0.1", "info" : { "title" : "Parameter mapping example", "version" : "2025-01-15T19:21:35Z" }, "paths" : { "/" : { "post" : { "responses" : { "200" : { "description" : "200 response", "headers" : { "item" : { "schema" : { "type" : "string" } }, "location" : { "schema" : { "type" : "string" } }, "id" : { "schema" : { "type" : "string" } } } } }, "x-amazon-apigateway-integration" : { "type" : "http", "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200", "responseParameters" : { "method.response.header.id" : "integration.response.header.x-app-id", "method.response.header.location" : "integration.response.body.redirect.url", "method.response.header.item" : "integration.response.multivalueheader.item" } } }, "requestTemplates" : { "application/json" : "{\"statusCode\": 200}" }, "passthroughBehavior" : "when_no_templates", "timeoutInMillis" : 29000 } } } } } ``` ------ # Referencia de origen de asignación de parámetros para las API de REST en API Gateway Cuando crea una asignación de parámetro, especifica los parámetros de solicitud de método o de respuesta de integración que desea modificar y especifica cómo modificarlos. En la siguiente tabla se muestran los parámetros de solicitud de método que puede asignar y la expresión para crear la asignación. En estas expresiones, *name* es el nombre de un parámetro de solicitud de método. Por ejemplo, para asignar el parámetro de encabezado de solicitud `puppies`, utilice la expresión `method.request.header.puppies`. La expresión debe coincidir con la expresión regular `'^[a-zA-Z0-9._$-]+$]'`. Puede utilizar la asignación de parámetros en la solicitud de integración para integraciones de proxy y de no proxy. | **Origen de datos asignado** | **Expresión de asignación** | | --- | --- | | Ruta de solicitud de método | method.request.path.name | | Cadena de consulta de solicitud de método | method.request.querystring.name | | Cadena de consulta de solicitud de método multivalor | method.request.multivaluequerystring.name | | Encabezado de solicitud de método | method.request.header.name | | Encabezado de solicitud de método multivalor | method.request.multivalueheader.name | | Cuerpo de solicitud de método | method.request.body | | Cuerpo de solicitud de método (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION* es una expresión JSONPath para un campo JSON del cuerpo de una solicitud. Para obtener más información, consulte [Expresión JSONPath](http://goessner.net/articles/JsonPath/index.html#e2). | | Variables de etapa | stageVariables.name | | Variables de contexto | `context.name` El nombre debe ser una de las [variables de contexto admitidas](api-gateway-mapping-template-reference.md#context-variable-reference). | | Valor estático | `'static_value'`. El valor de *static\$1value* es un literal de cadena que se debe incluir entre comillas simples. Por ejemplo, `'https://www.example.com'`. | En la siguiente tabla se muestran los parámetros de respuesta de integración que puede asignar y la expresión para crear la asignación. En estas expresiones, *name* es el nombre de un parámetro de respuesta de integración. Puede asignar encabezados de respuesta de método desde cualquier encabezado de respuesta de integración o cuerpo de respuesta de integración, variables de contexto o valores estáticos. Para utilizar la asignación de parámetros para una respuesta de integración, necesita una integración de no proxy. | Origen de datos asignado | Expresión de asignación | | --- | --- | | Encabezado de respuesta de integración | integration.response.header.name | | Encabezado de respuesta de integración | integration.response.multivalueheader.name | | Cuerpo de respuesta de integración | integration.response.body | | Cuerpo de respuesta de integración (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION* es una expresión JSONPath para un campo JSON del cuerpo de una respuesta. Para obtener más información, consulte [Expresión JSONPath](http://goessner.net/articles/JsonPath/index.html#e2). | | Variable de etapa | stageVariables.name | | Variable de contexto | `context.name` El nombre debe ser una de las [variables de contexto admitidas](api-gateway-mapping-template-reference.md#context-variable-reference). | | Valor estático | ` 'static_value'` El valor de *static\$1value* es un literal de cadena que se debe incluir entre comillas simples. Por ejemplo, `'https://www.example.com'`. | # Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway Las transformaciones de plantillas de asignación utilizan una plantilla de asignación para modificar la solicitud de integración o respuesta de integración. Una *plantilla de asignación* es un script expresado en [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) y aplicado a una carga útil mediante [JSONPath](https://goessner.net/articles/JsonPath/) basado en el encabezado `Content-type`. Utiliza plantillas de asignación cuando utiliza las transformaciones de plantillas de asignación. En esta sección se describe la información conceptual relacionada con las plantillas de asignación. En el siguiente diagrama se muestra el ciclo de vida de la solicitud de un recurso `POST /pets` que tiene una integración con un punto de conexión de integración de PetStore. En esta API, un usuario envía datos sobre una mascota y el punto de conexión de integración devuelve la tarifa de adopción asociada a una mascota. En este ciclo de vida de la solicitud, las transformaciones de plantillas de asignación filtran el cuerpo de la solicitud al punto de conexión de integración y filtran el cuerpo de la respuesta desde el punto de conexión de integración. ![\[Ciclo de vida de solicitud de ejemplo\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/mapping-template-transforms.png) En esta sección se explica el ciclo de vida de la solicitud y la respuesta. ## Solicitud de método y solicitud de integración En el ejemplo anterior, si este es el cuerpo de solicitud enviado al método de solicitud: ``` POST /pets HTTP/1.1 Host:abcd1234.us-west-2.amazonaws.com Content-type: application/json { "id": 1, "type": "dog", "Age": 11, } ``` Este cuerpo de solicitud no tiene el formato correcto para que lo utilice el punto de conexión de integración, por lo que API Gateway realiza las transformaciones de plantilla de asignación. API Gateway solo realiza las transformaciones de plantilla de asignación porque hay una plantilla de asignación definida para Content-Type `application/json`. Si no define una plantilla de asignación para Content-Type, de forma predeterminada, API Gateway pasa el cuerpo a través de la solicitud de integración al punto de conexión de integración. Para modificar este comportamiento, consulte [Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway](integration-passthrough-behaviors.md). La siguiente plantilla de asignación transforma los datos de solicitud de método en la solicitud de integración antes de que se envíen al punto de conexión de integración: ``` #set($inputRoot = $input.path('$')) { "dogId" : "dog_"$elem.id, "Age": $inputRoot.Age } ``` 1. La variable `$inputRoot` representa el objeto raíz en los datos JSON originales de la sección anterior. Las directivas comienzan con el símbolo `#`. 1. El valor `dog` es una concatenación del `id` del usuario y un valor de cadena. 1. `Age` es del cuerpo de solicitud de método. A continuación, se reenvía el siguiente resultado al punto de conexión de integración: ``` { "dogId" : "dog_1", "Age": 11 } ``` ## Respuesta de integración y respuesta de método Después de que la solicitud se haya enviado correctamente al punto de conexión de integración, el punto de conexión envía una respuesta a la respuesta de integración de API Gateway. A continuación, se muestran los datos de salida de ejemplo del punto de conexión de integración: ``` { "dogId" : "dog_1", "adoptionFee": 19.95, } ``` La respuesta de método espera una carga útil diferente a la que devuelve la respuesta de integración. API Gateway realiza las transformaciones de plantillas de asignación. API Gateway solo realiza las transformaciones de plantilla de asignación porque hay una plantilla de asignación definida para Content-Type `application/json`. Si no define una plantilla de asignación para Content-Type, de forma predeterminada, API Gateway pasa el cuerpo a través de la respuesta de integración a la respuesta de método. Para modificar este comportamiento, consulte [Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway](integration-passthrough-behaviors.md). ``` #set($inputRoot = $input.path('$')) { "adoptionFee" : $inputRoot.adoptionFee, } ``` El siguiente resultado se envía a la respuesta del método: ``` {"adoptionFee": 19.95} ``` Esto completa el ejemplo de transformación de plantilla de asignación. Recomendamos que, cuando sea posible, en lugar de utilizar las transformaciones de plantilla de asignación, utilice una integración de proxy para transformar los datos. Para obtener más información, consulte [Elegir un tipo de integración de API de API Gateway](api-gateway-api-integration-types.md). # Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway Si la solicitud de método tiene una carga útil y no tiene una plantilla de asignación definida para el encabezado `Content-Type`, puede elegir pasar la carga útil de la solicitud suministrada por el cliente a través de la solicitud de integración al backend sin transformación. Este proceso se denomina "acceso directo a la integración". El comportamiento de acceso directo real de una solicitud entrante viene determinado por esta configuración. Hay tres opciones: **Cuando ninguna plantilla coincide con el encabezado Tipo de contenido solicitado** Elija esta opción si desea que el cuerpo de la solicitud de método se transmita a través de la solicitud de integración al backend sin transformación cuando el tipo de contenido de la solicitud de método no coincida con ningún tipo de contenido asociado a las plantillas de mapeo. Al llamar a la API de API Gateway, se elige esta opción estableciendo `WHEN_NO_MATCH` como el valor de la propiedad `passthroughBehavior` en [Integración](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). **Cuando no hay plantillas definidas (recomendado)** Elija esta opción si desea que el cuerpo de la solicitud de método se transmita a través de la solicitud de integración al backend sin transformación cuando no se haya definido ninguna plantilla de mapeo en la solicitud de integración. Si se define una plantilla cuando se selecciona esta opción, la solicitud de método con una carga útil y un tipo de contenido que no coincida con ninguna plantilla de asignación definida se rechazará con una respuesta HTTP 415 Tipo de medio no admitido. Al llamar a la API de API Gateway, se elige esta opción estableciendo `WHEN_NO_TEMPLATES` como el valor de la propiedad `passthroughBehavior` en [Integración](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). **Nunca** Elija esta opción si no desea que el cuerpo de la solicitud de método se transmita a través de la solicitud de integración al backend sin transformación cuando no se haya definido ninguna plantilla de mapeo en la solicitud de integración. Si se define una plantilla cuando esta opción está seleccionada, la solicitud de método de un tipo de contenido sin asignar se rechazará con una respuesta HTTP 415 Unsupported Media Type. Al llamar a la API de API Gateway, se elige esta opción estableciendo `NEVER` como el valor de la propiedad `passthroughBehavior` en [Integración](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). Los siguientes ejemplos muestran los posibles comportamientos del acceso directo. Ejemplo 1: Se define una plantilla de asignación en la solicitud de integración para el tipo de contenido `application/json`. | content-type | Opción de acceso directo | Comportamiento | | --- | --- | --- | | Ninguno El valor predeterminado de API Gateway es `application/json` | WHEN\$1NO\$1MATCH | La carga de solicitud se transforma mediante la plantilla. | | Ninguno El valor predeterminado de API Gateway es `application/json` | WHEN\$1NO\$1TEMPLATES | La carga de solicitud se transforma mediante la plantilla. | | Ninguno El valor predeterminado de API Gateway es `application/json` | NEVER | La carga de solicitud se transforma mediante la plantilla. | | application/json | WHEN\$1NO\$1MATCH | La carga de solicitud se transforma mediante la plantilla. | | application/json | WHEN\$1NO\$1TEMPLATES | La carga de solicitud se transforma mediante la plantilla. | | application/json | NEVER | La carga de solicitud se transforma mediante la plantilla. | | application/xml | WHEN\$1NO\$1MATCH | La carga de solicitud no se transforma y se envía al backend tal como está. | | application/xml | WHEN\$1NO\$1TEMPLATES | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. | | application/xml | NEVER | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. | Ejemplo 2: Se define una plantilla de asignación en la solicitud de integración para el tipo de contenido `application/xml`. | Content-type | Opción de acceso directo | Comportamiento | | --- | --- | --- | | Ninguno El valor predeterminado de API Gateway es `application/json` | WHEN\$1NO\$1MATCH | La carga de solicitud no se transforma y se envía al backend tal como está. | | Ninguno El valor predeterminado de API Gateway es `application/json` | WHEN\$1NO\$1TEMPLATES | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. | | Ninguno El valor predeterminado de API Gateway es `application/json` | NEVER | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. | | application/json | WHEN\$1NO\$1MATCH | La carga de solicitud no se transforma y se envía al backend tal como está. | | application/json | WHEN\$1NO\$1TEMPLATES | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. | | application/json | NEVER | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. | | application/xml | WHEN\$1NO\$1MATCH | La carga de solicitud se transforma mediante la plantilla. | | application/xml | WHEN\$1NO\$1TEMPLATES | La carga de solicitud se transforma mediante la plantilla. | | application/xml | NEVER | La carga de solicitud se transforma mediante la plantilla. | Ejemplo 3: no se han definido plantillas de asignación en la solicitud de integración. | Content-type | Opción de acceso directo | Comportamiento | | --- | --- | --- | | Ninguno El valor predeterminado de API Gateway es `application/json` | WHEN\$1NO\$1MATCH | La carga de solicitud no se transforma y se envía al backend tal como está. | | Ninguno El valor predeterminado de API Gateway es `application/json` | WHEN\$1NO\$1TEMPLATES | La carga de solicitud no se transforma y se envía al backend tal como está. | | Ninguno El valor predeterminado de API Gateway es `application/json` | NEVER | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. | | application/json | WHEN\$1NO\$1MATCH | La carga de solicitud no se transforma y se envía al backend tal como está. | | application/json | WHEN\$1NO\$1TEMPLATES | La carga de solicitud no se transforma y se envía al backend tal como está. | | application/json | NEVER | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. | | application/xml | WHEN\$1NO\$1MATCH | La carga de solicitud no se transforma y se envía al backend tal como está. | | application/xml | WHEN\$1NO\$1TEMPLATES | La carga de solicitud no se transforma y se envía al backend tal como está. | | application/xml | NEVER | La solicitud se rechaza con una respuesta HTTP 415 Unsupported Media Type. | # Ejemplo de plantilla de asignación adicional para las API de REST en API Gateway En el siguiente ejemplo se muestra una API de álbum de fotos en API Gateway que utiliza plantillas de asignación para transformar los datos de solicitud de integración y respuesta de integración. También utiliza modelos de datos para definir la carga útil de las solicitudes de métodos y las respuestas de integración. Para obtener más información acerca de los modelos de datos, consulte [Modelos de datos para las API de REST](models-mappings-models.md). ## Solicitud de método y solicitud de integración A continuación se muestra un modelo que define el cuerpo de solicitud de método. Este modelo de entrada requiere que el intermediario cargue una página de fotos y un mínimo de 10 fotos por cada página. Puede utilizar este modelo de entrada para generar un SDK o para utilizar la validación de solicitudes para la API. Durante la validación de la solicitud, si el cuerpo de solicitud de método no se adhiere a la estructura de datos del modelo, API Gateway rechaza la solicitud. ``` { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PhotosInputModel", "type": "object", "properties": { "photos": { "type": "object", "required" : [ "photo" ], "properties": { "page": { "type": "integer" }, "pages": { "type": "string" }, "perpage": { "type": "integer", "minimum" : 10 }, "total": { "type": "string" }, "photo": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "owner": { "type": "string" }, "photographer_first_name" : {"type" : "string"}, "photographer_last_name" : {"type" : "string"}, "secret": { "type": "string" }, "server": { "type": "string" }, "farm": { "type": "integer" }, "title": { "type": "string" }, "ispublic": { "type": "boolean" }, "isfriend": { "type": "boolean" }, "isfamily": { "type": "boolean" } } } } } } } } ``` A continuación, se muestra un ejemplo de cuerpo de solicitud de método que se adhiere a la estructura de datos del modelo de datos anterior. ``` { "photos": { "page": 1, "pages": "1234", "perpage": 100, "total": "123398", "photo": [ { "id": "12345678901", "owner": "23456789@A12", "photographer_first_name" : "Saanvi", "photographer_last_name" : "Sarkar", "secret": "abc123d456", "server": "1234", "farm": 1, "title": "Sample photo 1", "ispublic": true, "isfriend": false, "isfamily": false }, { "id": "23456789012", "owner": "34567890@B23", "photographer_first_name" : "Richard", "photographer_last_name" : "Roe", "secret": "bcd234e567", "server": "2345", "farm": 2, "title": "Sample photo 2", "ispublic": true, "isfriend": false, "isfamily": false } ] } } ``` En este ejemplo, si el cliente ha enviado el cuerpo de solicitud de método anterior, esta plantilla de asignación transforma la carga útil para que coincida con el formato requerido por el punto de conexión de integración. ``` #set($inputRoot = $input.path('$')) { "photos": [ #foreach($elem in $inputRoot.photos.photo) { "id": "$elem.id", "photographedBy": "$elem.photographer_first_name $elem.photographer_last_name", "title": "$elem.title", "ispublic": $elem.ispublic, "isfriend": $elem.isfriend, "isfamily": $elem.isfamily }#if($foreach.hasNext),#end #end ] } ``` En el siguiente ejemplo se muestran los datos de salida de la transformación: ``` { "photos": [ { "id": "12345678901", "photographedBy": "Saanvi Sarkar", "title": "Sample photo 1", "ispublic": true, "isfriend": false, "isfamily": false }, { "id": "23456789012", "photographedBy": "Richard Roe", "title": "Sample photo 2", "ispublic": true, "isfriend": false, "isfamily": false } ] } ``` Estos datos se envían a la solicitud de integración y, a continuación, al punto de conexión de integración. ## Respuesta de integración y respuesta de método A continuación, se muestra un modelo de salida de ejemplo para los datos fotográficos del punto de conexión de integración. Puede usar este modelo como modelo de respuesta de método, que es necesario al generar un SDK con establecimiento inflexible de tipos para la API. Esto provoca que el resultado se traduzca a una clase apropiada en Java u Objective-C. ``` { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PhotosOutputModel", "type": "object", "properties": { "photos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "photographedBy": { "type": "string" }, "title": { "type": "string" }, "ispublic": { "type": "boolean" }, "isfriend": { "type": "boolean" }, "isfamily": { "type": "boolean" } } } } } } ``` El punto de conexión de integración podría no responder con una respuesta que se adhiera a la estructura de datos de este modelo. Por ejemplo, la respuesta de integración podría tener el siguiente aspecto: ``` "photos": [ { "id": "12345678901", "photographedBy": "Saanvi Sarkar", "title": "Sample photo 1", "description": "My sample photo 1", "public": true, "friend": false, "family": false }, { "id": "23456789012", "photographedBy": "Richard Roe", "title": "Sample photo 2", "description": "My sample photo 1", "public": true, "friend": false, "family": false } ] } ``` El siguiente ejemplo de plantilla de asignación transforma los datos de respuesta de integración al formato esperado por la respuesta de método: ``` #set($inputRoot = $input.path('$')) { "photos": [ #foreach($elem in $inputRoot.photos.photo) { "id": "$elem.id", "photographedBy": "$elem.photographer_first_name $elem.photographer_last_name", "title": "$elem.title", "ispublic": $elem.public, "isfriend": $elem.friend, "isfamily": $elem.family }#if($foreach.hasNext),#end #end ] } ``` En el siguiente ejemplo se muestran los datos de salida de la transformación: ``` { "photos": [ { "id": "12345678901", "photographedBy": "Saanvi Sarkar", "title": "Sample photo 1", "ispublic": true, "isfriend": false, "isfamily": false }, { "id": "23456789012", "photographedBy": "Richard Roe", "title": "Sample photo 2", "ispublic": true, "isfriend": false, "isfamily": false } ] } ``` Estos datos se envían a la respuesta del método y luego se devuelven al cliente. # Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway Puede utilizar las transformaciones de plantilla de asignación para anular cualquier tipo de parámetro de solicitud, encabezado de respuesta o código de estado de respuesta. Utiliza una plantilla de asignación para hacer lo siguiente: + Realizar asignaciones de parámetros muchos a uno + Anular parámetros una vez aplicadas las asignaciones de API Gateway estándar + Asignar parámetros condicionalmente en función del contenido del cuerpo u otros valores de parámetro + Crear nuevos parámetros mediante programación + Anular los códigos de estado devueltos por el punto de conexión de integración Las invalidaciones son definitivas. Una invalidación solo puede aplicarse a cada parámetro una vez. Si intenta anular el mismo parámetro varias veces, API Gateway devuelve una respuesta `5XX`. Si tiene que invalidar el mismo parámetro varias veces en la plantilla, le recomendamos crear una variable y aplicar la invalidación al final de la plantilla. La plantilla solo se aplica una vez analizada en su totalidad. ## Ejemplo 1: anular el código de estado en función del cuerpo de integración En el siguiente ejemplo se utiliza la [API de ejemplo](api-gateway-create-api-from-example.md) para anular el código de estado en función del cuerpo de la respuesta de integración. ------ #### [ Consola de administración de AWS ] **Anulación de un código de estado basado en el cuerpo de respuesta de integración** 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Seleccione **Crear API**. 1. En **API de REST**, elija **Compilación**. 1. En **Detalles de la API**, elija **API de ejemplo**. 1. Seleccione **Crear API**. API Gateway crea una API de tienda de mascotas de ejemplo. Para recuperar información sobre una mascota, utilice la solicitud de método de API de `GET /pets/{petId}`, donde `{petId}` es un parámetro de ruta correspondiente a un número de identificación de una mascota. En este ejemplo, anula el código de respuesta del método `GET` a `400` cuando se detecta una condición de error. 1. En el árbol **Recursos**, elija el método `GET` en `/{petId}`. 1. Primero, pruebe la implementación actual de la API. Elija la pestaña **Prueba**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña. 1. En **petId**, introduzca **-1** y, a continuación, seleccione **Prueba**. El **Cuerpo de respuesta** indica un error de fuera de intervalo: ``` { "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] } ``` Además, la última línea bajo **Registros** termina por `Method completed with status: 200`. La integración se ha completado correctamente, pero se ha producido un error. Ahora, anulará el código de estado basado en el cuerpo de respuesta de integración. 1. En la pestaña **Respuesta de integración**, en **Predeterminado: respuesta**, seleccione **Editar**. 1. Elija **Plantillas de mapeo**. 1. Elija **Add mapping template (Añadir plantilla de asignación)**. 1. En **Tipo de contenido**, ingrese **application/json**. 1. En **Cuerpo de la plantilla**, introduzca lo siguiente: ``` #set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end ``` Esta plantilla de asignación utiliza la variable `$context.responseOverride.status` para anular el código de estado a `400` si la respuesta de integración contiene la cadena `error`. 1. Seleccione **Save**. 1. Elija la pestaña **Prueba**. 1. En **petId**, introduzca **-1**. 1. En los resultados, el **Response Body (Cuerpo de respuesta)** indica un error de fuera de intervalo: ``` { "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] } ``` Sin embargo, la última línea de **Registros** termina ahora por `Method completed with status: 400`. ------ #### [ CloudFormation ] En este ejemplo, utiliza la propiedad [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar un archivo de definición de OpenAPI en API Gateway. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: PetStore Example 1 description: Example pet store API. version: "2025-01-14T00:13:18Z" paths: /pets/{petId}: get: parameters: - name: petId in: path required: true schema: type: string responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId} responses: default: statusCode: "200" responseTemplates: application/json: |- #set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end requestParameters: integration.request.path.petId: method.request.path.petId passthroughBehavior: when_no_match type: http components: schemas: Pet: type: object properties: id: type: integer type: type: string price: type: number ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] La siguiente definición de OpenAPI crea el recurso `GET pets/{petId}` y anula el código de estado en función del cuerpo de integración. ``` { "openapi" : "3.0.1", "info" : { "title" : "PetStore Example 1", "description" : "Example pet store API.", "version" : "2025-01-14T00:13:18Z" }, "paths" : { "/pets/{petId}" : { "get" : { "parameters" : [ { "name" : "petId", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}", "responses" : { "default" : { "statusCode" : "200", "responseTemplates" : { "application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end" } } }, "requestParameters" : { "integration.request.path.petId" : "method.request.path.petId" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } }, "components" : { "schemas" : { "Pet" : { "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string" }, "price" : { "type" : "number" } } } } } } ``` ------ ## Ejemplo 2: anular el encabezado de solicitud y crear nuevos encabezados En el siguiente ejemplo se utiliza la [API de ejemplo](api-gateway-create-api-from-example.md) para anular el encabezado de solicitud y crear nuevos encabezados. ------ #### [ Consola de administración de AWS ] **Anulación del encabezado de solicitud de un método mediante la creación de un nuevo encabezado** 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija la API de ejemplo que creó en el tutorial anterior. El nombre de la API debe ser **PetStore**. 1. En el árbol **Recursos**, elija el método `GET` en `/pet`. 1. En la pestaña **Solicitud de método**, en **Configuración de solicitud de método**, elija **Editar**. 1. Elija **Encabezados de solicitud HTTP** y, a continuación, elija **Agregar encabezado**. 1. En **Nombre**, escriba **header1**. 1. Elija **Agregar encabezado** y, a continuación, cree un segundo encabezado llamado **header2**. 1. Seleccione **Save**. Ahora, combina estos encabezados en un valor de encabezado mediante una plantilla de asignación. 1. En la pestaña **Solicitud de integración**, en **Configuración de la solicitud de integración**, seleccione **Editar**. 1. En **Acceso directo de cuerpo de la solicitud**, elija **Cuando no haya plantillas definidas (recomendado)**. 1. Elija **Plantillas de mapeo** y, a continuación, haga lo siguiente: 1. Elija **Add mapping template (Añadir plantilla de asignación)**. 1. En **Tipo de contenido**, ingrese **application/json**. 1. En **Cuerpo de la plantilla**, introduzca lo siguiente: ``` #set($header1Override = "pets") #set($header3Value = "$input.params('header1')$input.params('header2')") $input.json("$") #set($context.requestOverride.header.header3 = $header3Value) #set($context.requestOverride.header.header1 = $header1Override) #set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value]) ``` Esta plantilla de asignación anula `header1` con la cadena `pets` y crea un encabezado de varios valores llamado `$header3Value` que combina `header1` y `header2`. 1. Seleccione **Save**. 1. Elija la pestaña **Prueba**. 1. En **Encabezados**, copie el siguiente código: ``` header1:header1Val header2:header2Val ``` 1. Seleccione **Test (Probar)**. En el cuadro **Registros**, debería ver una entrada que incluye este texto: ``` Endpoint request headers: {header3=header1Valheader2Val, header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id, Accept=application/json, multivalueheader=pets,header1Valheader2Val} ``` ------ #### [ CloudFormation ] En este ejemplo, utiliza la propiedad [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar un archivo de definición de OpenAPI en API Gateway. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: PetStore Example 2 description: Example pet store API. version: "2025-01-14T00:36:18Z" paths: /pets: get: parameters: - name: header2 in: header schema: type: string - name: page in: query schema: type: string - name: type in: query schema: type: string - name: header1 in: header schema: type: string responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets responses: default: statusCode: "200" requestParameters: integration.request.header.header1: method.request.header.header1 integration.request.header.header2: method.request.header.header2 integration.request.querystring.page: method.request.querystring.page integration.request.querystring.type: method.request.querystring.type requestTemplates: application/json: |- #set($header1Override = "pets") #set($header3Value = "$input.params('header1')$input.params('header2')") $input.json("$") #set($context.requestOverride.header.header3 = $header3Value) #set($context.requestOverride.header.header1 = $header1Override) #set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value]) passthroughBehavior: when_no_match type: http components: schemas: Pet: type: object properties: id: type: integer type: type: string price: type: number ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] La siguiente definición de OpenAPI crea el recurso `GET pets` y anula el encabezado de solicitud y crea nuevos encabezados. ``` { "openapi" : "3.0.1", "info" : { "title" : "PetStore Example 2", "description" : "Example pet store API.", "version" : "2025-01-14T00:36:18Z" }, "paths" : { "/pets" : { "get" : { "parameters" : [ { "name" : "header2", "in" : "header", "schema" : { "type" : "string" } }, { "name" : "page", "in" : "query", "schema" : { "type" : "string" } }, { "name" : "type", "in" : "query", "schema" : { "type" : "string" } }, { "name" : "header1", "in" : "header", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.header1" : "method.request.header.header1", "integration.request.header.header2" : "method.request.header.header2", "integration.request.querystring.page" : "method.request.querystring.page", "integration.request.querystring.type" : "method.request.querystring.type" }, "requestTemplates" : { "application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } } } ``` ------ Para utilizar una anulación de plantilla de asignación, agregue una o más de las siguientes variables `$context`. Para ver una lista de variables `$context`, consulte [Variables de contexto para transformaciones de datos](api-gateway-mapping-template-reference.md#context-variable-reference). # Tutorial: modificación de la solicitud y respuesta de integración para integraciones con servicios de AWS En el siguiente tutorial se muestra cómo utilizar las transformaciones de plantilla de asignación para configurar plantillas de asignación con el fin de transformar las solicitudes y respuestas de integración mediante la consola y la CLI de AWS. **Topics** + [ ## Configuración de la transformación de datos en la consola de API Gateway ](#mapping-example-console) + [ ## Configuración de la transformación de datos mediante la CLI de AWS ](#mapping-example-cli) + [ ## Plantilla CloudFormation de transformación de datos completada ](#api-gateway-data-transformations-full-cfn-stack) ## Configuración de la transformación de datos en la consola de API Gateway En este tutorial, creará una API y una tabla de DynamoDB incompletas con el siguiente archivo .zip [data-transformation-tutorial-console.zip](samples/data-transformation-tutorial-console.zip). Esta API incompleta tiene un recurso `/pets` con los métodos `GET` y `POST`. + El método `GET` obtendrá datos del punto de conexión HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Los datos de salida se transformarán según la plantilla de mapeo en [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md). + El método `POST` permitirá al usuario `POST` información de la mascota en una tabla de Amazon DynamoDB mediante una plantilla de mapeo. Descargue y descomprima [la plantilla de creación de aplicaciones para CloudFormation](samples/data-transformation-tutorial-console.zip). Utilizará esta plantilla para crear una tabla de DynamoDB para publicar información sobre la mascota y una API incompleta. Finalizará el resto de los pasos en la consola de API Gateway. **Para crear una pila de CloudFormation** 1. Abra la consola de CloudFormation en [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Seleccione **Create stack (Crear pila)** y, a continuación, seleccione **With new resources (standard) (Con nuevos recursos [estándar])**. 1. En **Specify template (Especificar plantilla)**, elija **Upload a template file (Cargar un archivo de plantilla)**. 1. Seleccione la plantilla que ha descargado. 1. Elija **Next (Siguiente)**. 1. En **Stack name (Nombre de pila)**, escriba **data-transformation-tutorial-console** y, a continuación, elija **Next (Siguiente)**. 1. En **Configure stack options (Configurar opciones de pila)**, elija **Next (Siguiente)**. 1. Para **Capabilities** (Capacidades), sepa que CloudFormation puede crear recursos de IAM en su cuenta. 1. Elija **Siguiente** y, a continuación, elija **Enviar**. CloudFormation aprovisiona los recursos especificados en la plantilla. Puede tardar varios minutos en finalizar el aprovisionamiento de los recursos. Cuando el estado de la pila de CloudFormation sea **CREATE\$1COMPLETE**, estará listo para continuar con el paso siguiente. **Para probar la respuesta de integración de `GET`** 1. En la pestaña **Recursos** de la pila CloudFormation de **data-transformation-tutorial-console**, seleccione el ID físico de su API. 1. En el panel de navegación principal, seleccione **Recursos** y, a continuación, seleccione el método **GET**. 1. Elija la pestaña **Prueba**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña. El resultado de la prueba mostrará lo siguiente: ``` [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` Transformará este resultado según la plantilla de mapeo en [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md). **Para transformar la respuesta de integración de `GET`** 1. Elija la pestaña **Respuesta de integración**. Actualmente, no hay plantillas de mapeo definidas, por lo que la respuesta de integración no se transformará. 1. En **Predeterminado: respuesta**, seleccione **Editar**. 1. Elija **Plantillas de mapeo** y, a continuación, haga lo siguiente: 1. Elija **Add mapping template (Añadir plantilla de asignación)**. 1. En **Tipo de contenido**, ingrese **application/json**. 1. En **Cuerpo de la plantilla**, introduzca lo siguiente: ``` #set($inputRoot = $input.path('$')) [ #foreach($elem in $inputRoot) { "description" : "Item $elem.id is a $elem.type.", "askingPrice" : $elem.price }#if($foreach.hasNext),#end #end ] ``` Seleccione **Save**. **Para probar la respuesta de integración de `GET`** + Elija la pestaña **Prueba** y, a continuación, seleccione **Prueba**. El resultado de la prueba mostrará la respuesta transformada. ``` [ { "description" : "Item 1 is a dog.", "askingPrice" : 249.99 }, { "description" : "Item 2 is a cat.", "askingPrice" : 124.99 }, { "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ] ``` **Para transformar los datos de entrada del método `POST`** 1. Elija el método **POST**. 1. Elija la pestaña **Solicitud de integración** y, a continuación, en **Configuración de solicitud de integración**, elija **Editar**. La plantilla CloudFormation ha rellenado algunos de los campos de la solicitud de integración. + El tipo de integración es Servicio de AWS. + El Servicio de AWS es DynamoDB. + El método HTTP es `POST`. + La acción es `PutItem`. + La función de ejecución que permite a API Gateway incluir un elemento en la tabla de DynamoDB es `data-transformation-tutorial-console-APIGatewayRole`. CloudFormation ha creado este rol para permitir que API Gateway tuviera los permisos mínimos para interactuar con DynamoDB. No se ha especificado el nombre de la tabla de DynamoDB. Especificará el nombre en los pasos siguientes. 1. En **Acceso directo de cuerpo de la solicitud**, seleccione **Nunca**. Esto significa que la API rechazará los datos con tipos de contenido que no tengan una plantilla de mapeo. 1. Elija **Plantillas de mapeo**. 1. El **Tipo de contenido** está establecido en `application/json`. Esto significa que la API rechazará un tipo de contenido que no sea application/json. Para obtener más información sobre los comportamientos del acceso directo a la integración, consulte . [Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway](integration-passthrough-behaviors.md) 1. Especifique el siguiente código en el editor de texto. ``` { "TableName":"data-transformation-tutorial-console-ddb", "Item": { "id": { "N": $input.json("$.id") }, "type": { "S": $input.json("$.type") }, "price": { "N": $input.json("$.price") } } } ``` Esta plantilla especifica la tabla como `data-transformation-tutorial-console-ddb` y establece los elementos como `id`, `type` y `price`. Los elementos procederán del cuerpo del método `POST`. También puede usar un modelo de datos para ayudar a crear una plantilla de mapeo. Para obtener más información, consulte [Solicitud de la validación de las API de REST en API Gateway](api-gateway-method-request-validation.md). 1. Elija **Guardar** para guardar la plantilla de mapeo. **Para añadir un método y una respuesta de integración desde el método `POST`** CloudFormation ha creado un método y una respuesta de integración en blanco. Editará esta respuesta para proporcionar más información. Para obtener más información sobre cómo editar las respuestas, consulte [Ejemplos de asignación de parámetros para las API de REST en API Gateway](request-response-data-mappings.md). 1. En la pestaña **Respuesta de integración**, en **Predeterminado: respuesta**, seleccione **Editar**. 1. Elija **Plantillas de mapeo** y, a continuación, elija **Agregar plantilla de mapeo**. 1. En **Content-type**, introduzca **application/json**. 1. En el editor de código, introduzca la siguiente plantilla de mapeo de salida para enviar un mensaje de salida: ``` { "message" : "Your response was recorded at $context.requestTime" } ``` Para obtener más información acerca de las variables de contexto, consulte [Variables de contexto para transformaciones de datos](api-gateway-mapping-template-reference.md#context-variable-reference). 1. Elija **Guardar** para guardar la plantilla de mapeo. **Probar el método `POST`** Elija la pestaña **Prueba**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña. 1. En el cuerpo de la solicitud, introduzca el siguiente ejemplo. ``` { "id": "4", "type" : "dog", "price": "321" } ``` 1. Seleccione **Probar** El resultado debería mostrar su mensaje de éxito. Puede abrir la consola de DynamoDB en [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) para comprobar que el elemento de ejemplo esté en la tabla. **Para eliminar una pila de CloudFormation** 1. Abra la consola de CloudFormation en [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Seleccione su pila de CloudFormation. 1. Elija **Delete (Eliminar)** y, a continuación, confirme su elección. ## Configuración de la transformación de datos mediante la CLI de AWS En este tutorial, creará una API y una tabla de DynamoDB incompletas con el siguiente archivo .zip [data-transformation-tutorial-cli.zip](samples/data-transformation-tutorial-cli.zip). Esta API incompleta tiene un recurso `/pets` con un método `GET` integrado en el punto de conexión HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Creará un método `POST` para conectarse a una tabla de DynamoDB y utilizará plantillas de mapeo para introducir datos en una tabla de DynamoDB. + Transformará los datos de salida según la plantilla de mapeo en [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md). + Creará un método `POST` para permitir al usuario `POST` información de la mascota en una tabla de Amazon DynamoDB mediante una plantilla de mapeo. **Para crear una pila de CloudFormation** Descargue y descomprima [la plantilla de creación de aplicaciones para CloudFormation](samples/data-transformation-tutorial-cli.zip). Para completar el siguiente tutorial, necesita la [versión 2 de la AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). Para comandos largos, se utiliza un carácter de escape (`\`) para dividir un comando en varias líneas. **nota** En Windows, algunos comandos de la CLI de Bash que utiliza habitualmente (por ejemplo, `zip`) no son compatibles con los terminales integrados del sistema operativo. Para obtener una versión de Ubuntu y Bash integrada con Windows, [instale el subsistema de Windows para Linux](https://learn.microsoft.com/en-us/windows/wsl/install). Los comandos de la CLI de ejemplo de esta guía utilizan el formato Linux. Los comandos que incluyen documentos JSON en línea deben reformatearse si utiliza la CLI de Windows. 1. Utilice el siguiente comando para crear la pila CloudFormation. ``` aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM ``` 1. CloudFormation aprovisiona los recursos especificados en la plantilla. Puede tardar varios minutos en finalizar el aprovisionamiento de los recursos. Use el siguiente comando para ver el estado de su pila CloudFormation. ``` aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli ``` 1. Cuando el estado de su pila CloudFormation sea `StackStatus: "CREATE_COMPLETE"`, utilice el siguiente comando para recuperar los valores de salida relevantes para los pasos futuros. ``` aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}" ``` A continuación se muestran los valores de salida: + ApiRole, que es el nombre del rol que permite a API Gateway incluir elementos en la tabla de DynamoDB. En este tutorial, el nombre de rol es `data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG`. + DDBTableName, que es el nombre de la tabla de DynamoDB. En este tutorial, el nombre de la tabla es `data-transformation-tutorial-cli-ddb`. + ResourceId, que es el identificador del recurso de las mascotas donde están expuestos los métodos `GET` y `POST`. Para este tutorial, el ID del recurso es `efg456`. + ApiID, que es el identificador de la API. Para este tutorial, el ID de la API es `abc123`. **Para probar el método `GET` antes de la transformación de datos** + Utilice el siguiente comando para probar el método `GET`. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET ``` El resultado de la prueba mostrará lo siguiente. ``` [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` Transformará este resultado según la plantilla de mapeo en [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md). **Para transformar la respuesta de integración de `GET`** + Use el siguiente comando para actualizar la respuesta de integración del método `GET`. Reemplace *rest-api-id* y *resource-id* con sus valores. Utilice el siguiente comando para crear la respuesta de integración. ``` aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --status-code 200 \ --selection-pattern "" \ --response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}' ``` **Para probar el método `GET`** + Utilice el siguiente comando para probar el método `GET`. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ ``` El resultado de la prueba mostrará la respuesta transformada. ``` [ { "description" : "Item 1 is a dog.", "askingPrice" : 249.99 }, { "description" : "Item 2 is a cat.", "askingPrice" : 124.99 }, { "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ] ``` **Para crear un método `POST`** 1. Use el siguiente comando para crear un método nuevo en el recurso `/pets`. ``` aws apigateway put-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --authorization-type "NONE" \ ``` Este método le permitirá enviar información de mascotas a la tabla de DynamoDB que creó en la pila CloudFormation. 1. Utilice el siguiente comando para una integración Servicio de AWS en el método `POST`. ``` aws apigateway put-integration --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --type AWS \ --integration-http-method POST \ --uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \ --credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \ --request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}' ``` 1. Utilice el siguiente comando para crear una respuesta de método para una llamada correcta del método `POST`. ``` aws apigateway put-method-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 ``` 1. Utilice el siguiente comando para crear una respuesta de integración para una llamada correcta del método `POST`. ``` aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 \ --selection-pattern "" \ --response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}' ``` **Para probar el método `POST`** + Utilice el siguiente comando para probar el método `POST`. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}' ``` El resultado mostrará el mensaje correcto. **Para eliminar una pila de CloudFormation** + Use el siguiente comando para eliminar los recursos CloudFormation. ``` aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli ``` ## Plantilla CloudFormation de transformación de datos completada El siguiente ejemplo es una plantilla CloudFormation completada, que crea una API y una tabla de DynamoDB con un recurso `/pets` con los métodos `GET` y `POST`. + El método `GET` obtendrá datos del punto de conexión HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Los datos de salida se transformarán según la plantilla de mapeo en [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md). + El método `POST` permitirá al usuario `POST` información de la mascota en una tabla de DynamoDB mediante una plantilla de mapeo. ### Plantilla de CloudFormation de ejemplo ``` AWSTemplateFormatVersion: 2010-09-09 Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data. Parameters: StageName: Type: String Default: v1 Description: Name of API stage. Resources: DynamoDBTable: Type: 'AWS::DynamoDB::Table' Properties: TableName: !Sub data-transformation-tutorial-complete AttributeDefinitions: - AttributeName: id AttributeType: N KeySchema: - AttributeName: id KeyType: HASH ProvisionedThroughput: ReadCapacityUnits: 5 WriteCapacityUnits: 5 APIGatewayRole: Type: 'AWS::IAM::Role' Properties: AssumeRolePolicyDocument: Version: 2012-10-17 Statement: - Action: - 'sts:AssumeRole' Effect: Allow Principal: Service: - apigateway.amazonaws.com Policies: - PolicyName: APIGatewayDynamoDBPolicy PolicyDocument: Version: 2012-10-17 Statement: - Effect: Allow Action: - 'dynamodb:PutItem' Resource: !GetAtt DynamoDBTable.Arn Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: data-transformation-complete-api ApiKeySourceType: HEADER PetsResource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'pets' PetsMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: GET ApiKeyRequired: false AuthorizationType: NONE Integration: Type: HTTP Credentials: !GetAtt APIGatewayRole.Arn IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ PassthroughBehavior: WHEN_NO_TEMPLATES IntegrationResponses: - StatusCode: '200' ResponseTemplates: application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]" MethodResponses: - StatusCode: '200' PetsMethodPost: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: POST ApiKeyRequired: false AuthorizationType: NONE Integration: Type: AWS Credentials: !GetAtt APIGatewayRole.Arn IntegrationHttpMethod: POST Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem PassthroughBehavior: NEVER RequestTemplates: application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}" IntegrationResponses: - StatusCode: 200 ResponseTemplates: application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}" MethodResponses: - StatusCode: '200' ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - PetsMethodGet Properties: RestApiId: !Ref Api StageName: !Sub '${StageName}' Outputs: ApiId: Description: API ID for CLI commands Value: !Ref Api ResourceId: Description: /pets resource ID for CLI commands Value: !Ref PetsResource ApiRole: Description: Role ID to allow API Gateway to put and scan items in DynamoDB table Value: !Ref APIGatewayRole DDBTableName: Description: DynamoDB table name Value: !Ref DynamoDBTable ``` # Ejemplos que utilizan variables para las transformaciones de plantilla de asignación para API Gateway En los siguientes ejemplos se muestra cómo utilizar las variables `$context`, `input` y `util` en las plantillas de asignación. Puede utilizar una integración simulada o una integración sin proxy de Lambda que devuelva el evento de entrada a API Gateway. Para obtener una lista de todas las variables admitidas para las transformaciones de datos, consulte [Variables para transformaciones de datos para API Gateway](api-gateway-mapping-template-reference.md). ## Ejemplo 1: pase de múltiples variables `$context` al punto de conexión de integración El siguiente ejemplo muestra una plantilla de asignación que mapea variables `$context` de entrada a las variables de backend con nombres ligeramente diferentes en una carga de la solicitud de integración: ``` { "stage" : "$context.stage", "request_id" : "$context.requestId", "api_id" : "$context.apiId", "resource_path" : "$context.resourcePath", "resource_id" : "$context.resourceId", "http_method" : "$context.httpMethod", "source_ip" : "$context.identity.sourceIp", "user-agent" : "$context.identity.userAgent", "account_id" : "$context.identity.accountId", "api_key" : "$context.identity.apiKey", "caller" : "$context.identity.caller", "user" : "$context.identity.user", "user_arn" : "$context.identity.userArn" } ``` La salida de esta plantilla de asignación debe tener el siguiente aspecto: ``` { stage: 'prod', request_id: 'abcdefg-000-000-0000-abcdefg', api_id: 'abcd1234', resource_path: '/', resource_id: 'efg567', http_method: 'GET', source_ip: '192.0.2.1', user-agent: 'curl/7.84.0', account_id: '111122223333', api_key: 'MyTestKey', caller: 'ABCD-0000-12345', user: 'ABCD-0000-12345', user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar' } ``` Una de las variables es una clave de API. En este ejemplo se supone que el método requiere una clave de API. ## Ejemplo 2: pase de todos los parámetros de solicitud al punto de conexión de integración a través de una carga útil JSON El siguiente ejemplo pasa todos los parámetros de solicitud, como los parámetros `path`, `querystring` y `header`, a través del punto de conexión de integración mediante una carga útil de JSON: ``` #set($allParams = $input.params()) { "params" : { #foreach($type in $allParams.keySet()) #set($params = $allParams.get($type)) "$type" : { #foreach($paramName in $params.keySet()) "$paramName" : "$util.escapeJavaScript($params.get($paramName))" #if($foreach.hasNext),#end #end } #if($foreach.hasNext),#end #end } } ``` Si una solicitud tiene los siguientes parámetros de entrada: + Un parámetro de ruta denominado `myparam` + Parámetros de cadenas de consulta `querystring1=value1,value2` + Encabezados `"header1" : "value1"`. La salida de esta plantilla de asignación debe tener el siguiente aspecto: ``` {"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}} ``` ## Ejemplo 3: pase de una subsección de una solicitud de método al punto de conexión de integración En el siguiente ejemplo se utiliza el parámetro de entrada `name` para recuperar solo el parámetro `name` y el parámetro de entrada `input.json('$')` para recuperar todo el cuerpo de la solicitud de método: ``` { "name" : "$input.params('name')", "body" : $input.json('$') } ``` Para una solicitud que incluye los parámetros de cadena de consulta `name=Bella&type=dog` y el cuerpo siguiente: ``` { "Price" : "249.99", "Age": "6" } ``` La salida de esta plantilla de asignación debe tener el siguiente aspecto: ``` { "name" : "Bella", "body" : {"Price":"249.99","Age":"6"} } ``` Esta plantilla de asignación elimina el parámetro de cadena de consulta `type=dog`. Si la entrada JSON contiene caracteres sin escape que no puede analizar JavaScript, es posible que API Gateway devuelva una respuesta 400. Aplique `$util.escapeJavaScript($input.json('$'))` para asegurarse de que la entrada JSON se pueda analizar correctamente. El ejemplo anterior con `$util.escapeJavaScript($input.json('$'))` se aplica de la siguiente manera: ``` { "name" : "$input.params('name')", "body" : "$util.escapeJavaScript($input.json('$'))" } ``` En este caso, la salida de esta plantilla de asignación debe tener el siguiente aspecto: ``` { "name" : "Bella", "body": {"Price":"249.99","Age":"6"} } ``` ## Ejemplo 4: uso de una expresión JSONPath para pasar una subsección de una solicitud de método al punto de conexión de integración En el siguiente ejemplo se utilizan expresiones JSONPath para recuperar solo el parámetro de entrada `name` y el valor de `Age` del cuerpo de solicitud: ``` { "name" : "$input.params('name')", "body" : $input.json('$.Age') } ``` Para una solicitud que incluye los parámetros de cadena de consulta `name=Bella&type=dog` y el cuerpo siguiente: ``` { "Price" : "249.99", "Age": "6" } ``` La salida de esta plantilla de asignación debe tener el siguiente aspecto: ``` { "name" : "Bella", "body" : "6" } ``` Esta plantilla de asignación elimina el parámetro de cadena de consulta `type=dog` y el campo `Price` del cuerpo. Si una carga de solicitud de método contiene caracteres sin escape que no puede analizar JavaScript, es posible que API Gateway devuelva una respuesta `400`. Aplique `$util.escapeJavaScript()` para asegurarse de que la entrada JSON se pueda analizar correctamente. El ejemplo anterior con `$util.escapeJavaScript($input.json('$.Age'))` se aplica de la siguiente manera: ``` { "name" : "$input.params('name')", "body" : "$util.escapeJavaScript($input.json('$.Age'))" } ``` En este caso, la salida de esta plantilla de asignación debe tener el siguiente aspecto: ``` { "name" : "Bella", "body": "\"6\"" } ``` ## Ejemplo 5: uso de una expresión JSONPath para pasar información sobre una solicitud de método al punto de conexión de integración En el siguiente ejemplo se utilizan `$input.params()`, `$input.path()` y `$input.json()` para enviar información sobre una solicitud de método al punto de conexión de integración. Esta plantilla de asignación utiliza el método `size()` para proporcionar el número de elementos de una lista. ``` { "id" : "$input.params('id')", "count" : "$input.path('$.things').size()", "things" : $input.json('$.things') } ``` Para una solicitud que incluye el parámetros de ruta `123` y el cuerpo siguiente: ``` { "things": { "1": {}, "2": {}, "3": {} } } ``` La salida de esta plantilla de asignación debe tener el siguiente aspecto: ``` {"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}} ``` Si una carga de solicitud de método contiene caracteres sin escape que no puede analizar JavaScript, es posible que API Gateway devuelva una respuesta `400`. Aplique `$util.escapeJavaScript()` para asegurarse de que la entrada JSON se pueda analizar correctamente. El ejemplo anterior con `$util.escapeJavaScript($input.json('$.things'))` se aplica de la siguiente manera: ``` { "id" : "$input.params('id')", "count" : "$input.path('$.things').size()", "things" : "$util.escapeJavaScript($input.json('$.things'))" } ``` La salida de esta plantilla de asignación debe tener el siguiente aspecto: ``` {"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"} ``` # Variables para transformaciones de datos para API Gateway Cuando cree una asignación de parámetro, puede utilizar variables de contexto como origen de datos. Cuando cree las transformaciones de plantilla de asignación, puede utilizar variables de contexto, de entrada y de utilidad en los scripts que escriba en [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Por obtener ejemplos de plantillas de asignación que utilizan estas variables de referencia, consulte [Ejemplos que utilizan variables para las transformaciones de plantilla de asignación para API Gateway](api-gateway-mapping-variable-examples.md). Para obtener una lista de variables de referencia para el registro de acceso, consulte [Variables para el registro de acceso para API Gateway](api-gateway-variables-for-access-logging.md). ## Variables de contexto para transformaciones de datos Puede utilizar las siguientes variables `$context` que distinguen entre mayúsculas y minúsculas para transformaciones de datos. | Parámetro | Descripción | | --- | --- | | \$1context.accountId | El ID de cuenta de AWS del propietario de la API. | | \$1context.apiId | El identificador que API Gateway asigna a su API. | | \$1context.authorizer.claims.property | Una propiedad de las notificaciones devueltas por el grupo de usuarios de Amazon Cognito una vez que se ha autenticado correctamente al intermediario del método. Para obtener más información, consulte [Control del acceso a las API de REST con grupos de usuarios de Amazon Cognito como autorizador](apigateway-integrate-with-cognito.md). La llamada a `$context.authorizer.claims` devuelve null. | | \$1context.authorizer.principalId | La identificación de usuario principal asociada con el token enviado por el cliente y devuelto por el autorizador de Lambda de API Gateway (que anteriormente se denominaba autorizador personalizado). Para obtener más información, consulte [Uso de autorizadores Lambda de API Gateway](apigateway-use-lambda-authorizer.md). | | \$1context.authorizer.property | El valor en forma de cadena del par clave-valor especificado de la asignación `context` que devuelve la función de Lambda del autorizador de Lambda de API Gateway. Por ejemplo, si el autorizador devuelve la siguiente asignación de `context`: 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
La llamada a `$context.authorizer.key` devuelve la cadena `"value"`, la llamada a `$context.authorizer.numKey` devuelve la cadena `"1"` y la llamada a `$context.authorizer.boolKey` devuelve la cadena `"true"`. En el caso de la *propiedad*, el único carácter especial admitido es el carácter `(_)` de subrayado. Para obtener más información, consulte [Uso de autorizadores Lambda de API Gateway](apigateway-use-lambda-authorizer.md). | | \$1context.awsEndpointRequestId | El ID de solicitud del punto de enlace de AWS. | | \$1context.deploymentId | El ID de la implementación de la API. | | \$1context.domainName | El nombre de dominio completo que se utiliza para invocar la API. Este debe ser el mismo que el encabezado `Host` entrante. | | \$1context.domainPrefix | La primera etiqueta del `$context.domainName`. | | \$1context.error.message | Una cadena que contiene un mensaje de error de API Gateway. Esta variable solo se puede usar para una sustitución sencilla de variables en una plantilla de mapeo de cuerpo [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), que no procesa el motor de Velocity Template Language, y en el registro de acceso. Para obtener más información, consulte [Supervisión de la ejecución de la API de WebSocket con métricas de CloudWatch](apigateway-websocket-api-logging.md) y [Configuración de respuestas de gateway para personalizar respuestas de errores](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.messageString | El valor entrecomillado de \$1context.error.message, es decir, "\$1context.error.message". | | \$1context.error.responseType | Un [tipo](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). Esta variable solo se puede usar para una sustitución sencilla de variables en una plantilla de mapeo de cuerpo [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), que no procesa el motor de Velocity Template Language, y en el registro de acceso. Para obtener más información, consulte [Supervisión de la ejecución de la API de WebSocket con métricas de CloudWatch](apigateway-websocket-api-logging.md) y [Configuración de respuestas de gateway para personalizar respuestas de errores](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.validationErrorString | Una cadena que contiene un mensaje de error de validación detallado. | | \$1context.extendedRequestId | El ID ampliado que API Gateway genera y asigna a la solicitud de API. El ID de solicitud ampliado contiene información útil para la depuración y la resolución de problemas. | | \$1context.httpMethod | El método HTTP utilizado. Los valores válidos son: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` y `PUT`. | | \$1context.identity.accountId | El ID de cuenta de AWS asociado con la solicitud. | | \$1context.identity.apiKey | Para los métodos de API que necesitan una clave de API, esta variable es la clave de API asociada a la solicitud del método. Para métodos que no requieren una clave de API, esta variable corresponde a valores null. Para obtener más información, consulte [Planes de uso y clave de API para las API de REST en API Gateway](api-gateway-api-usage-plans.md). | | \$1context.identity.apiKeyId | El ID de clave de API asociado a una solicitud de API que requiere una clave de API. | | \$1context.identity.caller | El identificador principal del intermediario que firmó la solicitud. Compatible con recursos que utilizan la autorización de IAM. | | \$1context.identity.cognitoAuthenticationProvider | Una lista separada por comas de todos los proveedores de autenticación de Amazon Cognito utilizados por el intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito. Por ejemplo, para una identidad de un grupo de usuarios de Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Consulte [Uso de las identidades federadas](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) en la *Guía para desarrolladores de Amazon Cognito* para obtener información sobre los proveedores de autenticación de Amazon Cognito disponibles. | | \$1context.identity.cognitoAuthenticationType | El tipo de autenticación de Amazon Cognito del intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito. Los valores posibles incluyen `authenticated` para identidades autenticadas y `unauthenticated` para identidades no autenticadas. | | \$1context.identity.cognitoIdentityId | El ID de identidad de Amazon Cognito del intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito. | | \$1context.identity.cognitoIdentityPoolId | El ID del grupo de identidades de Amazon Cognito del intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito. | | \$1context.identity.principalOrgId | El [ID de organización de AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). | | \$1context.identity.sourceIp | La dirección IP de origen de la conexión TCP inmediata que realiza la solicitud al punto de conexión de API Gateway. | | \$1context.identity.clientCert.clientCertPem | El certificado de cliente codificado en PEM que el cliente presentó durante la autenticación TLS mutua. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua. | | \$1context.identity.clientCert.subjectDN | Nombre distintivo del asunto del certificado que presenta un cliente. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua. | | \$1context.identity.clientCert.issuerDN | Nombre distintivo del emisor del certificado que presenta un cliente. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua. | | \$1context.identity.clientCert.serialNumber | Número de serie del certificado. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua. | | \$1context.identity.clientCert.validity.notBefore | Fecha antes de la cual el certificado no es válido. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua. | | \$1context.identity.clientCert.validity.notAfter | Fecha después de la cual el certificado no es válido. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada. Presente solo en los registros de acceso si falla la autenticación TLS mutua. | | \$1context.identity.vpcId | El ID de VPC de la VPC que realiza la solicitud al punto de conexión de API Gateway. | | \$1context.identity.vpceId | El ID de punto de conexión de VPC del punto de conexión de VPC que realiza la solicitud al punto de conexión de API Gateway. Está presente solo cuando tiene una API privada. | | \$1context.identity.user | El identificador principal del usuario que se autorizará a acceder al recurso. Compatible con recursos que utilizan la autorización de IAM. | | \$1context.identity.userAgent | El encabezado [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) del intermediario de la API. | | \$1context.identity.userArn | El Nombre de recurso de Amazon (ARN) del usuario identificado después de la autenticación. Para obtener más información, consulte [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). | | \$1context.isCanaryRequest | Devuelve `true` si la solicitud se dirigió al canario y `false` si no se dirigió al canario. Está presente solo cuando tiene un canario activado. | | \$1context.path | Ruta de acceso de la solicitud. Por ejemplo, en el caso del URL de una solicitud que no es de proxy https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, el valor de \$1context.path es /\$1stage\$1/root/child. | | \$1context.protocol | Protocolo de la solicitud; por ejemplo, HTTP/1.1. Las API de API Gateway pueden aceptar solicitudes HTTP/2, pero API Gateway envía solicitudes a las integraciones de backend mediante HTTP/1.1. Como resultado, el protocolo de solicitud se registra como HTTP/1.1 incluso si un cliente envía una solicitud que usa HTTP/2. | | \$1context.requestId | ID de la solicitud. Los clientes pueden anular este ID de solicitud. Utilice `$context.extendedRequestId` para un ID de solicitud único que genera API Gateway. | | \$1context.requestOverride.header.header\$1name | La invalidación del encabezado de solicitud. Si este parámetro se define, contiene los encabezados que se utilizarán en lugar de los **HTTP Headers (Encabezados HTTP)** que se definen en el panel **Integration Request (Solicitud de integración)**. Para obtener más información, consulte [Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.path.path\$1name | La invalidación de la ruta de acceso de la solicitud. Si este parámetro se define, contiene la ruta de acceso de la solicitud que se utilizará en lugar de los **URL Path Parameters (Parámetros de ruta URL)** que se definen en el panel **Integration Request (Solicitud de integración)**. Para obtener más información, consulte [Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.querystring.querystring\$1name | La invalidación de la cadena de consulta de solicitud. Si este parámetro se define, contiene las cadenas de consulta de solicitud que se utilizarán en lugar de los **URL Query String Parameters (Parámetros de cadena de consulta URL)** que se definen en el panel **Integration Request (Solicitud de integración)**. Para obtener más información, consulte [Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseOverride.header.header\$1name | La invalidación del encabezado de respuesta. Si este parámetro se define, contiene el encabezado que se devolverá en lugar del Response header (Encabezado de respuesta) que se define como Default mapping (Asignación predeterminada) en el panel Integration Response (Respuesta de integración). Para obtener más información, consulte [Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseOverride.status | La invalidación del código de estado de respuesta. Si este parámetro se define, contiene el código de estado que se devolverá en lugar del Method response status (Estado de respuesta de método) que se define como Default mapping (Asignación predeterminada) en el panel Integration Response (Respuesta de integración). Para obtener más información, consulte [Anulación de los parámetros de solicitud y respuesta y de los códigos de estado de la API para las API de REST en API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestTime | Hora de la solicitud en formato [CLF](https://httpd.apache.org/docs/current/logs.html#common)-(dd/MMM/yyyy:HH:mm:ss \$1-hhmm). | | \$1context.requestTimeEpoch | Hora de la solicitud en formato [Epoch](https://en.wikipedia.org/wiki/Unix_time) en milisegundos. | | \$1context.resourceId | El identificador que API Gateway asigna a su recurso. | | \$1context.resourcePath | La ruta a su recurso. Por ejemplo, en el caso del URI de una solicitud que no es de proxy `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, el valor de `$context.resourcePath` es `/root/child`. Para obtener más información, consulte [Tutorial: Creación de una API de REST con integración no de proxy HTTP](api-gateway-create-api-step-by-step.md). | | \$1context.stage | La etapa de implementación de la solicitud de la API (por ejemplo, `Beta` o `Prod`). | | \$1context.wafResponseCode | La respuesta recibida desde [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` o `WAF_BLOCK`. No se establecerá si la etapa no está asociada a una ACL web. Para obtener más información, consulte [Uso de AWS WAF para proteger sus API de REST en API Gateway](apigateway-control-access-aws-waf.md). | | \$1context.webaclArn | El ARN completo de la ACL web que se utiliza para decidir si se debe permitir o bloquear la solicitud. No se establecerá si la etapa no está asociada a una ACL web. Para obtener más información, consulte [Uso de AWS WAF para proteger sus API de REST en API Gateway](apigateway-control-access-aws-waf.md). | ## Variables de entrada Puede utilizar las siguientes variables `$input` que distinguen entre mayúsculas y minúsculas para hacer referencia a la carga útil de solicitud del método y a los parámetros de solicitud del método. Están disponibles las siguientes funciones: | Variable y función | Descripción | | --- | --- | | \$1input.body | Devuelve la carga de solicitud bruta como una cadena. Puede utilizar `$input.body` para conservar números enteros de punto flotante, como `10.00`. | | \$1input.json(x) | Esta función evalúa una expresión JSONPath y devuelve los resultados como una cadena JSON. Por ejemplo, `$input.json('$.pets')` devuelve una cadena JSON que representa la estructura de `pets` (mascotas). Para obtener más información acerca de JSONPath, consulte [JSONPath](https://goessner.net/articles/JsonPath/) o [JSONPath for Java](https://github.com/json-path/JsonPath). | | \$1input.params() | Devuelve una asignación de todos los parámetros de solicitud. Recomendamos que se utilice `$util.escapeJavaScript` para sanear el resultado a fin de evitar un posible ataque de inyección. Para un control total del saneamiento de solicitudes, utilice una integración de proxy sin plantilla y gestione dicho saneamiento en su integración. | | \$1input.params(x) | Devuelve el valor de un parámetro de solicitud de método de la ruta, cadena de consulta o valor de encabezado (buscado en este orden) dada una cadena de nombre de parámetro `x`. Recomendamos que se utilice `$util.escapeJavaScript` para sanear el parámetro a fin de evitar un posible ataque de inyección. Para un control total del saneamiento de parámetros, utilice una integración de proxy sin plantilla y gestione dicho saneamiento en su integración. | | \$1input.path(x) | Toma una cadena de expresión JSONPath (`x`) y devuelve una representación del resultado en forma de objeto JSON. Esto le permite tener acceso y manipular los elementos de la carga de forma nativa en [Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Por ejemplo, si la expresión `$input.path('$.pets')` devuelve un objeto como este: 
[
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }, 
  { 
    "id": 2, 
    "type": "cat", 
    "price": 124.99 
  }, 
  { 
    "id": 3, 
    "type": "fish", 
    "price": 0.99 
  } 
]
`$input.path('$.pets').size()` devolvería `"3"`. Para obtener más información acerca de JSONPath, consulte [JSONPath](https://goessner.net/articles/JsonPath/) o [JSONPath for Java](https://github.com/json-path/JsonPath). | ## Variables de etapa Puede utilizar las siguientes variables de etapa como marcadores de posición para ARN y URL en integraciones de método. Para obtener más información, consulte [Uso de variables de etapa para una API de REST en API Gateway](stage-variables.md). | Sintaxis | Descripción | | --- | --- | | \$1stageVariables.variable\$1name, \$1stageVariables['variable\$1name'], o bien \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name* representa un nombre de variable de etapa. | ## Variables de utilidad Puede utilizar las siguientes variables `$util` que distinguen entre mayúsculas y minúsculas para utilizar funciones de utilidad en las plantillas de asignación. A menos que se especifique lo contrario, el conjunto de caracteres predeterminado es UTF-8. | Función | Descripción | | --- | --- | | \$1util.escapeJavaScript() | Aplica caracteres de escape a los caracteres de una cadena usando reglas de cadena de JavaScript. Esta función convertirá todas las comillas simples (`'`) en caracteres de escape (`\'`). Sin embargo, JSON no admite comillas simples con caracteres de escape. Por lo tanto, cuando la salida de esta función se utiliza en una propiedad de JSON, debe convertir todas las comillas simples con caracteres de escape (`\'`) en comillas simples normales (`'`). Esto se muestra en el siguiente ejemplo: 
 "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")"
| | \$1util.parseJson() | Toma un elemento JSON en forma de cadena y devuelve una representación del resultado en forma de objeto. Puede utilizar el resultado de esta función para tener acceso y manipular los elementos de la carga de forma nativa en Apache Velocity Template Language (VTL). Por ejemplo, si tiene la siguiente carga: 
{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}
y usa la siguiente plantilla de asignación 
#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
Obtendrá el siguiente resultado: 
{
   "errorMessageObjKey2ArrVal" : 1
}
| | \$1util.urlEncode() | Convierte una cadena en formato "application/x-www-form-urlencoded". | | \$1util.urlDecode() | Descodifica una cadena "application/x-www-form-urlencoded". | | \$1util.base64Encode() | Codifica los datos en una cadena codificada en base64. | | \$1util.base64Decode() | Descodifica los datos de una cadena codificada en base64. | # Respuestas de Gateway para las API de REST en API Gateway Una respuesta de gateway se identifica mediante un tipo de respuesta definido por API Gateway. La respuesta se compone de un código de estado HTTP, un conjunto de encabezados adicionales especificados mediante asignaciones de parámetros y una carga útil generada por una plantilla de asignación distinta de [VTL](https://velocity.apache.org/engine/devel/vtl-reference.html). En la API REST de API Gateway, una respuesta de gateway se representa mediante [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). En OpenAPI, una instancia de `GatewayResponse` se describe mediante la extensión [x-amazon-apigateway-gateway-responses.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md). Para habilitar una respuesta de gateway, debe configurar una para un [tipo de respuesta admitido](supported-gateway-response-types.md) en el nivel de API. Siempre que API Gateway devuelve una respuesta de este tipo, se aplican las plantillas de mapeo de encabezados y cargas definidas en la respuesta de gateway para devolver los resultados asignados al intermediario de la API. En la siguiente sección, le mostramos cómo configurar respuestas de gateway utilizando la consola de API Gateway y la API REST de API Gateway. ## Configuración de respuestas de gateway para personalizar respuestas de errores Si API Gateway no puede procesar una solicitud entrante, devuelve al cliente una respuesta de error sin reenviar la solicitud al backend de integración. De forma predeterminada, la respuesta de error contiene un breve mensaje de error descriptivo. Por ejemplo, si intenta llamar a una operación en un recurso de API no definido, recibe una respuesta de error con el mensaje `{ "message": "Missing Authentication Token" }`. Si es la primera vez que utiliza API Gateway, es posible que le resulte difícil entender qué es lo que ha ocurrido. Para algunas de las respuestas de error, API Gateway permite a los desarrolladores de API que personalicen las respuestas de forma que devuelvan las respuestas en formatos diferentes. Para el ejemplo de `Missing Authentication Token`, puede añadir una pista a la carga de respuesta original con la posible causa, como en este ejemplo: `{"message":"Missing Authentication Token", "hint":"The HTTP method or resources may not be supported."}`. Cuando la API es un mediador entre un intercambio externo y AWS Cloud, se utilizan plantillas de asignación de VTL para la solicitud de integración o la respuesta de integración para asignar la carga de un formato a otro. Sin embargo, las plantillas de asignación de VTL solo funcionan para solicitudes válidas con respuestas correctas. En el caso de las solicitudes no válidas, API Gateway omite la integración en su totalidad y devuelve una respuesta de error. Debe utilizar la personalización para representar las respuestas de error en un formato compatible con el intercambio. Aquí, la personalización se presenta en una plantilla de asignación que no es de VTL que solo admite sustituciones de variables sencillas. Con el fin de generalizar la respuesta de error generada por API Gateway a cualquier respuesta generada por API Gateway, nos referimos a estas respuestas como *respuesta de gateway*. Esto permite distinguir las respuestas generadas por API Gateway de las respuestas de integración. Una plantilla de asignación de respuesta de gateway puede tener acceso a los valores de la variable `$context` y a los valores de la propiedad `$stageVariables`, así como a los parámetros de solicitud de método, con el formato `method.request.param-position.param-name`. Para obtener más información acerca de las variables `$context`, consulte [Variables de contexto para transformaciones de datos](api-gateway-mapping-template-reference.md#context-variable-reference). Para obtener más información acerca de `$stageVariables`, consulte [Variables de etapa](api-gateway-mapping-template-reference.md#stagevariables-template-reference). Para obtener más información sobre los parámetros de solicitud de método, consulte [Variables de entrada](api-gateway-mapping-template-reference.md#input-variable-reference). **Topics** + [ ## Configuración de respuestas de gateway para personalizar respuestas de errores ](#customize-gateway-responses) + [ # Configurar una respuesta de gateway para una API REST mediante la consola de API Gateway ](set-up-gateway-response-using-the-console.md) + [ # Configurar una respuesta de gateway mediante la API REST de API Gateway ](set-up-gateway-response-using-the-api.md) + [ # Configurar la personalización de respuestas de gateway en OpenAPI ](set-up-gateway-responses-in-swagger.md) + [ # Tipos de respuestas de puerta de enlace para API Gateway ](supported-gateway-response-types.md) # Configurar una respuesta de gateway para una API REST mediante la consola de API Gateway En el siguiente ejemplo se muestra cómo configurar una respuesta de puerta de enlace para una API de REST mediante la consola de API Gateway **Para personalizar una respuesta de gateway mediante la consola de API Gateway** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. En el panel de navegación principal, elija **Respuestas de puerta de enlace**. 1. Elija un tipo de respuesta y, a continuación, elija **Editar**. En este tutorial, utilizamos **Falta el token de autenticación** como ejemplo. 1. Puede cambiar el **Código de estado** generado por API Gateway para devolver un código de estado diferente según los requisitos de la API. En este ejemplo, la personalización cambia el código de estado del valor predeterminado (`403`) a `404`, porque este mensaje de error se produce cuando un cliente llama a un recurso no admitido o no válido que se considera no encontrado. 1. Para devolver encabezados personalizados, elija **Agregar encabezado de respuesta** en **Encabezados de respuesta**. Con fines ilustrativos, añadimos los siguientes encabezados personalizados: ``` Access-Control-Allow-Origin:'a.b.c' x-request-id:method.request.header.x-amzn-RequestId x-request-path:method.request.path.petId x-request-query:method.request.querystring.q ``` En las asignaciones de encabezado anteriores, un nombre de dominio estático (`'a.b.c'`) se asigna al encabezado `Allow-Control-Allow-Origin` para permitir el acceso de CORS a la API; el encabezado de solicitud de entrada `x-amzn-RequestId` se asigna a `request-id` en la respuesta, la variable de ruta `petId` de la solicitud entrante se asigna al encabezado `request-path` de la respuesta y el parámetro de consulta `q` de la solicitud original se asigna al encabezado `request-query` de la respuesta. 1. En **Plantillas de respuesta**, mantenga `application/json` para **Tipo de contenido** e ingrese la siguiente plantilla de mapeo del cuerpo en el editor **Cuerpo de la plantilla**: ``` { "message":"$context.error.messageString", "type": "$context.error.responseType", "statusCode": "'404'", "stage": "$context.stage", "resourcePath": "$context.resourcePath", "stageVariables.a": "$stageVariables.a" } ``` Este ejemplo muestra cómo asignar las propiedades `$context` y `$stageVariables` a propiedades del cuerpo de la respuesta de gateway. 1. Seleccione **Save changes (Guardar cambios)**. 1. Implemente la API en una etapa nueva o existente. Pruebe la respuesta de la puerta de enlace llamando al siguiente comando CURL si la URL de invocación del método de API correspondiente es `https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/{petId}`: ``` curl -v -H 'x-amzn-RequestId:123344566' https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/5/type?q=1 ``` Como el parámetro de cadena de consulta adicional `q=1` no es compatible con la API, se devuelve un error de la respuesta de puerta de enlace especificada. Debería obtener una respuesta de gateway similar a la siguiente: ``` > GET /custErr/pets/5?q=1 HTTP/1.1 Host: o81lxisefl.execute-api.us-east-1.amazonaws.com User-Agent: curl/7.51.0 Accept: */* HTTP/1.1 404 Not Found Content-Type: application/json Content-Length: 334 Connection: keep-alive Date: Tue, 02 May 2017 03:15:47 GMT x-amzn-RequestId: 123344566 Access-Control-Allow-Origin: a.b.c x-amzn-ErrorType: MissingAuthenticationTokenException header-1: static x-request-query: 1 x-request-path: 5 X-Cache: Error from cloudfront Via: 1.1 441811a054e8d055b893175754efd0c3.cloudfront.net (CloudFront) X-Amz-Cf-Id: nNDR-fX4csbRoAgtQJ16u0rTDz9FZWT-Mk93KgoxnfzDlTUh3flmzA== { "message":"Missing Authentication Token", "type": MISSING_AUTHENTICATION_TOKEN, "statusCode": '404', "stage": custErr, "resourcePath": /pets/{petId}, "stageVariables.a": a } ``` En el ejemplo anterior se presupone que el backend de la API es [Pet Store](http://petstore-demo-endpoint.execute-api.com/petstore/pets) y que la API tiene un variable de etapa, `a`, definida. # Configurar una respuesta de gateway mediante la API REST de API Gateway Antes de personalizar un respuesta de gateway mediante la API REST de API Gateway, debe haber creado una API y haber obtenido su identificador. Para recuperar el identificador de la API, puede seguir la relación de enlace [restapi:gateway-responses](https://docs.aws.amazon.com/apigateway/latest/api/API_GetGatewayResponses.html) y examinar el resultado. **Para personalizar una respuesta de gateway mediante la API REST de API Gateway** 1. Para sobrescribir una instancia completa de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) llame a la acción [gatewayresponse:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutGatewayResponse.html). Especifique un [responseType](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) (tipo de respuesta) deseado en el parámetro de ruta de URL y proporcione en la carga de la solicitud los mapeos [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#statusCode) (código de estado), [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseParameters) (parámetros de respuesta) y [responseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseTemplates) (plantillas de respuesta). 1. Para actualizar parte de una instancia de `GatewayResponse`, llame a la acción [gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html). Especifique el parámetro `responseType` deseado en la ruta URL y proporcione en la carga útil de la solicitud las propiedades individuales `GatewayResponse` que desee, por ejemplo, el mapeo `responseParameters` o `responseTemplates`. # Configurar la personalización de respuestas de gateway en OpenAPI Puede utilizar la extensión `x-amazon-apigateway-gateway-responses` en el nivel de raíz de la API para personalizar respuestas de gateway en OpenAPI. La siguiente definición de OpenAPI muestra un ejemplo de personalización de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) del tipo `MISSING_AUTHENTICATION_TOKEN`. ``` "x-amazon-apigateway-gateway-responses": { "MISSING_AUTHENTICATION_TOKEN": { "statusCode": 404, "responseParameters": { "gatewayresponse.header.x-request-path": "method.input.params.petId", "gatewayresponse.header.x-request-query": "method.input.params.q", "gatewayresponse.header.Access-Control-Allow-Origin": "'a.b.c'", "gatewayresponse.header.x-request-header": "method.input.params.Accept" }, "responseTemplates": { "application/json": "{\n \"message\": $context.error.messageString,\n \"type\": \"$context.error.responseType\",\n \"stage\": \"$context.stage\",\n \"resourcePath\": \"$context.resourcePath\",\n \"stageVariables.a\": \"$stageVariables.a\",\n \"statusCode\": \"'404'\"\n}" } } ``` En este ejemplo, la personalización cambia el código de estado del valor predeterminado (`403`) a `404`. También añade a la respuesta de gateway cuatro parámetros de encabezado y una plantilla de asignación de cuerpo para el tipo de medio `application/json`. # Tipos de respuestas de puerta de enlace para API Gateway API Gateway expone las siguientes respuestas de gateway para su personalización por desarrolladores de la API. | Tipo de respuesta de gateway | Código de estado predeterminado | Descripción | | --- | --- | --- | | ACCESS\$1DENIED | 403 | La respuesta de gateway para un error de autorización (por ejemplo, cuando un autorizador de Amazon Cognito o personalizado deniega el acceso). Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_4XX`. | | API\$1CONFIGURATION\$1ERROR | 500 | La respuesta de gateway para una configuración de API no válida, incluida cuando una dirección de punto de enlace no válida enviada, cuando falla la descodificación base64 en datos binarios, cuando no se ha habilitado la compatibilidad con los datos binarios o cuando un mapeo de respuesta de integración que no coincide con ninguna plantilla y no se ha configurado ninguna plantilla predeterminada. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_5XX`. | | AUTHORIZER\$1CONFIGURATION\$1ERROR | 500 | La respuesta de gateway por no poder conectarse a un autorizador de Amazon Cognito o personalizado. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_5XX`. | | AUTHORIZER\$1FAILURE | 500 | La respuesta de gateway cuando un autorizador de Amazon Cognito o personalizado no puede autenticar al intermediario. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_5XX`. | | BAD\$1REQUEST\$1PARAMETERS | 400 | La respuesta de gateway cuando el parámetro de la solicitud no se puede validar de acuerdo con un validador de solicitudes habilitado. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_4XX`. | | BAD\$1REQUEST\$1BODY | 400 | La respuesta de gateway cuando el cuerpo de la solicitud no se puede validar de acuerdo con un validador de solicitudes habilitado. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_4XX`. | | DEFAULT\$14XX | Null | La respuesta de gateway predeterminada para un tipo de respuesta sin especificar con el código de estado `4XX`. Si se cambia el código de estado de esta respuesta de gateway, se cambian los códigos de estado de todas las demás respuestas `4XX` al nuevo valor. Si se restablece este código de estado a null, se revierten los códigos de estado de todas las demás respuestas `4XX` a sus valores originales. [Las respuestas personalizadas de AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html) tienen prioridad sobre las respuestas de gateway personalizadas. | | DEFAULT\$15XX | Null | La respuesta de gateway predeterminada para un tipo de respuesta sin especificar con un código de estado `5XX`. Si se cambia el código de estado de esta respuesta de gateway, se cambian los códigos de estado de todas las demás respuestas `5XX` al nuevo valor. Si se restablece este código de estado a null, se revierten los códigos de estado de todas las demás respuestas `5XX` a sus valores originales. | | EXPIRED\$1TOKEN | 403 | La respuesta de gateway para un error de token de autenticación de AWS caducado. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_4XX`. | | INTEGRATION\$1FAILURE | 504 | La respuesta de gateway para un error de integración. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_5XX`. | | INTEGRATION\$1TIMEOUT | 504 | La respuesta de gateway para un error de tiempo de espera de la integración agotado. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_5XX`. | | INVALID\$1API\$1KEY | 403 | La respuesta de gateway para una clave de API no válida enviada para un método que requiere una clave de API. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_4XX`. | | INVALID\$1SIGNATURE | 403 | La respuesta de gateway para un error de firma de AWS no válida. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_4XX`. | | MISSING\$1AUTHENTICATION\$1TOKEN | 403 | La respuesta de gateway para un error de token de autenticación que falta, incluidos los casos en los que el cliente intenta invocar un método o recurso de API no admitido. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_4XX`. | | QUOTA\$1EXCEEDED | 429 | La respuesta de gateway para el error de cuota del plan de uso superada. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_4XX`. | | REQUEST\$1TOO\$1LARGE | 413 | La respuesta de gateway para el error de solicitud demasiado grande. Si no se especifica el tipo de respuesta, se asigna a: `HTTP content length exceeded 10485760 bytes`. | | RESOURCE\$1NOT\$1FOUND | 404 | La respuesta de gateway cuando API Gateway no puede encontrar el recurso especificado después de que la solicitud de API supera la autenticación y autorización, excepto para la autenticación y autorización de la clave de API. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_4XX`. | | THROTTLED | 429 | La respuesta de gateway cuando se exceden los límites de solicitudes de nivel de plan, método, etapa o cuenta. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_4XX`. | | UNAUTHORIZED | 401 | La respuesta de gateway cuando el autorizador de Amazon Cognito o personalizado no puede autenticar al intermediario. | | UNSUPPORTED\$1MEDIA\$1TYPE | 415 | La respuesta de gateway cuando una carga es de un tipo de medio no admitido, si se ha habilitado el comportamiento de paso a través estricto. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_4XX`. | | WAF\$1FILTERED | 403 | La respuesta de gateway cuando AWS WAF bloquea una solicitud. Si no se especifica el tipo de respuesta, se asigna el tipo `DEFAULT_4XX`. [Las respuestas personalizadas de AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html) tienen prioridad sobre las respuestas de gateway personalizadas. | # CORS para las API de REST en API Gateway [Intercambio de Recursos de Origen Cruzado (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) es una característica de seguridad del navegador que restringe las solicitudes HTTP de origen cruzado que se inician desde secuencias de comandos que se ejecutan en el navegador. Para obtener más información, consulte [¿Qué es el CORS?](https://aws.amazon.com/what-is/cross-origin-resource-sharing/) ## Determinar si se habilita la compatibilidad con CORS Una solicitud HTTP *de origen cruzado* es una que se hace para: + Un *dominio* diferente (por ejemplo, de `example.com` a `amazondomains.com`) + Un *subdominio* diferente (por ejemplo, de `example.com` a `petstore.example.com`) + Un *puerto* diferente (por ejemplo, de `example.com` a `example.com:10777`) + Un *protocolo* diferente (por ejemplo, de `https://example.com` a `http://example.com`) Si no puede acceder a la API y recibe un mensaje de error que contiene `Cross-Origin Request Blocked`, es posible que deba habilitar CORS. Las solicitudes HTTP de origen cruzado se pueden dividir en dos tipos: solicitudes *simples* y solicitudes *no simples*. ## Habilitar CORS para una solicitud sencilla Una solicitud HTTP es *simple* si se cumplen todas las condiciones siguientes: + Se emite contra un recurso de API que permite únicamente solicitudes `GET`, `HEAD` y `POST`. + Si se trata de una solicitud de método `POST`, debe incluir un encabezado `Origin`. + El tipo de contenido de la carga de la solicitud es `text/plain`, `multipart/form-data` o `application/x-www-form-urlencoded`. + La solicitud no contiene encabezados personalizados. + Cualquier requisito adicional enumerado en la [documentación de CORS de Mozilla para solicitudes simples](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Simple_requests). Para solicitudes simples de método `POST` de origen cruzado, la respuesta del recurso debe incluir el encabezado `Access-Control-Allow-Origin: '*'` o `Access-Control-Allow-Origin:'origin'`. Todas los demás solicitudes HTTP de origen cruzado son solicitudes *no simples*. ## Habilitar CORS para una solicitud no sencilla Si los recursos de su API reciben solicitudes no sencillas, deberá habilitar la compatibilidad con CORS adicional en función del tipo de integración. ### Habilitar CORS para integraciones que no sean de proxy Para estas integraciones, el [protocolo CORS](https://fetch.spec.whatwg.org/#http-cors-protocol) requiere que el navegador envíe una solicitud preliminar al servidor y espere la aprobación (o una solicitud de credenciales) desde el servidor antes de enviar la solicitud real. Debe configurar su API para enviar una respuesta adecuada a la solicitud de verificación previa. Para crear una respuesta con comprobación previa: 1. Cree un método `OPTIONS` con una integración simulada. 1. Añada los siguientes encabezados de respuesta a la respuesta del método 200: + `Access-Control-Allow-Headers` + `Access-Control-Allow-Methods` + `Access-Control-Allow-Origin` 1. Configuración del comportamiento de acceso directo de integración a `NEVER`. En este caso, la solicitud del método de un tipo de contenido sin asignar se rechazará con una respuesta HTTP 415 Unsupported Media Type. Para obtener más información, consulte [Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway](integration-passthrough-behaviors.md). 1. Introduzca valores para los encabezados de las respuestas. Para permitir todos los orígenes, todos los métodos y los encabezados comunes, utilice los siguientes valores de encabezado: + `Access-Control-Allow-Headers: 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'` + `Access-Control-Allow-Methods: 'DELETE,GET,HEAD,OPTIONS,PUT,POST,PATCH'` + `Access-Control-Allow-Origin: '*'` Tras crear la solicitud con comprobación previa, debe devolver el encabezado `Access-Control-Allow-Origin: '*'` o `Access-Control-Allow-Origin:'origin'` de todos los métodos habilitados para CORS para al menos las 200 respuestas. ### Habilitar CORS para integraciones que no sean de proxy mediante Consola de administración de AWS Puede utilizar la Consola de administración de AWS para habilitar CORS. API Gateway crea un método `OPTIONS` y agrega el encabezado `Access-Control-Allow-Origin` a las respuestas de integración de métodos existentes. Esto no siempre funciona y, a veces, es necesario modificar manualmente la respuesta de integración para que devuelva el encabezado `Access-Control-Allow-Origin` de todos los métodos compatibles con CORS de al menos las 200 respuestas. Si tiene tipos de medios binarios configurados como `*/*` para la API, cuando API Gateway crea un método `OPTIONS`, cambie el `contentHandling` a `CONVERT_TO_TEXT`. El siguiente comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) cambia el `contentHandling` a `CONVERT_TO_TEXT` para una solicitud de integración: ``` aws apigateway update-integration \ --rest-api-id abc123 \ --resource-id aaa111 \ --http-method OPTIONS \ --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT' ``` El siguiente comando [update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html) cambia el `contentHandling` a `CONVERT_TO_TEXT` para una respuesta de integración: ``` aws apigateway update-integration-response \ --rest-api-id abc123 \ --resource-id aaa111 \ --http-method OPTIONS \ --status-code 200 \ --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT' ``` ## Habilitar la compatibilidad con CORS para integraciones de proxy En el caso de una integración de proxy Lambda o de proxy HTTP, el backend es responsable de devolver los encabezados `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods` y `Access-Control-Allow-Headers`, ya que una integración de proxy no devuelve una respuesta de integración. Las siguientes funciones de ejemplo de Lambda devuelven los encabezados CORS necesarios: ------ #### [ Node.js ] ``` export const handler = async (event) => { const response = { statusCode: 200, headers: { "Access-Control-Allow-Headers" : "Content-Type", "Access-Control-Allow-Origin": "https://www.example.com", "Access-Control-Allow-Methods": "OPTIONS,POST,GET" }, body: JSON.stringify('Hello from Lambda!'), }; return response; }; ``` ------ #### [ Python 3 ] ``` import json def lambda_handler(event, context): return { 'statusCode': 200, 'headers': { 'Access-Control-Allow-Headers': 'Content-Type', 'Access-Control-Allow-Origin': 'https://www.example.com', 'Access-Control-Allow-Methods': 'OPTIONS,POST,GET' }, 'body': json.dumps('Hello from Lambda!') } ``` ------ **Topics** + [ ## Determinar si se habilita la compatibilidad con CORS ](#apigateway-cors-request-types) + [ ## Habilitar CORS para una solicitud sencilla ](#apigateway-cors-simple-request) + [ ## Habilitar CORS para una solicitud no sencilla ](#apigateway-enable-cors-non-simple) + [ ## Habilitar la compatibilidad con CORS para integraciones de proxy ](#apigateway-enable-cors-proxy) + [ # Habilitar CORS en un recurso mediante la consola de API Gateway ](how-to-cors-console.md) + [ # Habilitar CORS en un recurso mediante la característica Importar API de API Gateway ](enable-cors-for-resource-using-swagger-importer-tool.md) + [ # Prueba de CORS para una API en API Gateway ](apigateway-test-cors.md) # Habilitar CORS en un recurso mediante la consola de API Gateway Puede utilizar la consola de API Gateway para habilitar el soporte de CORS con uno o todos los métodos en un recurso de la API REST que ha creado. Después de habilitar la compatibilidad con COR, defina el comportamiento de acceso directo de integración como `NEVER`. En este caso, la solicitud del método de un tipo de contenido sin asignar se rechazará con una respuesta HTTP 415 Unsupported Media Type. Para obtener más información, consulte [Comportamiento de solicitud de método para cargas útiles sin plantillas de asignación para las API de REST en API Gateway](integration-passthrough-behaviors.md) **importante** Los recursos pueden contener recursos secundarios. La habilitación del soporte de CORS para un recurso y sus métodos no lo habilita de forma recursiva para recursos secundarios y sus métodos. **Para habilitar soporte de CORS en un recurso de API de REST** 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elegir una API. 1. Elija un recurso en **Resources (Recursos)**. 1. En la sección **Detalles del recurso**, elija **Habilitar CORS**. ![\[En el panel Recursos, elija Habilitar CORS.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors.png) 1. En el cuadro **Habilitar CORS**, haga lo siguiente: 1. (Opcional) Si creó una respuesta de puerta de enlace personalizada y desea habilitar la compatibilidad con CORS para una respuesta, seleccione una respuesta de puerta de enlace. 1. Seleccione cada método para habilitar la compatibilidad con CORS. El método `OPTION` debe tener CORS habilitado. Si habilita la compatibilidad con CORS para un método `ANY`, se habilita CORS para todos los métodos. 1. En el campo de entrada **Access-Control-Allow-Headers**, escriba una cadena estática de una lista separada por comas de encabezados que el cliente debe enviar en la solicitud real del recurso. Utilice la lista de encabezados proporcionada por la consola `'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'` o especifique sus propios encabezados. 1. Utilice el valor proporcionado por la consola `'*'` como valor de encabezado **Access-Control-Allow-Origin** para permitir solicitudes de acceso de todos los orígenes o especifique un origen al que se permite acceder al recurso. 1. Seleccione **Save**. ![\[Seleccione qué encabezados se permiten\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors-resources.png) **importante** Al aplicar las instrucciones anteriores al método `ANY` en una integración de proxy, no se establecerán los encabezados de CORS correspondientes. En su lugar, el backend debe devolver los encabezados CORS correspondientes, como por ejemplo `Access-Control-Allow-Origin`. Una vez habilitado CORS en el método `GET`, se añade un método `OPTIONS` al recurso si no aún no se ha añadido. La respuesta `200` del método `OPTIONS` se configura automáticamente para devolver los tres encabezados `Access-Control-Allow-*` para el protocolo preliminar. Asimismo, el método (`GET`) real también está configurado de forma predeterminada para devolver el encabezado `Access-Control-Allow-Origin` en su respuesta 200. Para otros tipos de respuestas, tendrá que configurarlas manualmente para que devuelvan el encabezado `Access-Control-Allow-Origin'` con '\$1' un orígenes específicos, si no desea recibir el error `Cross-origin access`. Después de habilitar la compatibilidad con CORS en su recurso, debe implementar o volver a implementar la API para que la nueva configuración surta efecto. Para obtener más información, consulte [Creación de una implementación](set-up-deployments.md#create-deployment). **nota** Si no puede habilitar la compatibilidad con CORS en el recurso después de seguir el procedimiento, le recomendamos que compare la configuración de CORS con el recurso `/pets` de la API de ejemplo. Para obtener información sobre cómo crear la API de ejemplo, consulte [Tutorial: Crear una API de REST importando un ejemplo](api-gateway-create-api-from-example.md). # Habilitar CORS en un recurso mediante la característica Importar API de API Gateway Si utiliza la característica [Importar API de API Gateway](api-gateway-import-api.md), puede configurar la compatibilidad de CORS con un archivo de OpenAPI. En primer lugar, debe definir un método `OPTIONS` en el recurso que devuelva los encabezados necesarios. **nota** Los navegadores web esperan que los encabezados Access-Control-Allow-Headers y Access-Control-Allow-Origin estén configurados en cada método de API que acepta solicitudes de CORS. Además, algunos navegadores primero realizan una solicitud HTTP a un método `OPTIONS` en el mismo recurso y, a continuación, esperan recibir los mismos encabezados. ## Método `Options` de ejemplo En el siguiente ejemplo, se crea un método `OPTIONS` para una integración simulada. ------ #### [ OpenAPI 3.0 ] ``` /users: options: summary: CORS support description: | Enable CORS by returning correct headers tags: - CORS responses: 200: description: Default response for CORS method headers: Access-Control-Allow-Origin: schema: type: "string" Access-Control-Allow-Methods: schema: type: "string" Access-Control-Allow-Headers: schema: type: "string" content: {} x-amazon-apigateway-integration: type: mock requestTemplates: application/json: "{\"statusCode\": 200}" passthroughBehavior: "never" responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Methods: "'*'" method.response.header.Access-Control-Allow-Origin: "'*'" ``` ------ #### [ OpenAPI 2.0 ] ``` /users: options: summary: CORS support description: | Enable CORS by returning correct headers consumes: - "application/json" produces: - "application/json" tags: - CORS x-amazon-apigateway-integration: type: mock requestTemplates: "{\"statusCode\": 200}" passthroughBehavior: "never" responses: "default": statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Methods : "'*'" method.response.header.Access-Control-Allow-Origin : "'*'" responses: 200: description: Default response for CORS method headers: Access-Control-Allow-Headers: type: "string" Access-Control-Allow-Methods: type: "string" Access-Control-Allow-Origin: type: "string" ``` ------ Una vez que haya configurado el método `OPTIONS` para su recurso, puede añadir los encabezados necesarios a los otros métodos del mismo recurso necesarios para aceptar solicitudes de CORS. 1. Declare **Access-Control-Allow-Origin** y **Headers (Encabezados)** en los tipos de respuesta. ------ #### [ OpenAPI 3.0 ] ``` responses: 200: description: Default response for CORS method headers: Access-Control-Allow-Origin: schema: type: "string" Access-Control-Allow-Methods: schema: type: "string" Access-Control-Allow-Headers: schema: type: "string" content: {} ``` ------ #### [ OpenAPI 2.0 ] ``` responses: 200: description: Default response for CORS method headers: Access-Control-Allow-Headers: type: "string" Access-Control-Allow-Methods: type: "string" Access-Control-Allow-Origin: type: "string" ``` ------ 1. En la etiqueta `x-amazon-apigateway-integration`, configure la asignación de esos encabezados a los valores estáticos: ------ #### [ OpenAPI 3.0 ] ``` responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Methods: "'*'" method.response.header.Access-Control-Allow-Origin: "'*'" responseTemplates: application/json: | {} ``` ------ #### [ OpenAPI 2.0 ] ``` responses: "default": statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Methods : "'*'" method.response.header.Access-Control-Allow-Origin : "'*'" ``` ------ ## API de ejemplo En el siguiente ejemplo, se crea una API completa con un método `OPTIONS` y un método `GET` con una integración `HTTP`. ------ #### [ OpenAPI 3.0 ] ``` openapi: "3.0.1" info: title: "cors-api" description: "cors-api" version: "2024-01-16T18:36:01Z" servers: - url: "/{basePath}" variables: basePath: default: "/test" paths: /: get: operationId: "GetPet" responses: "200": description: "200 response" headers: Access-Control-Allow-Origin: schema: type: "string" content: {} x-amazon-apigateway-integration: httpMethod: "GET" uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets" responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Origin: "'*'" passthroughBehavior: "never" type: "http" options: responses: "200": description: "200 response" headers: Access-Control-Allow-Origin: schema: type: "string" Access-Control-Allow-Methods: schema: type: "string" Access-Control-Allow-Headers: schema: type: "string" content: application/json: schema: $ref: "#/components/schemas/Empty" x-amazon-apigateway-integration: responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'" method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Origin: "'*'" requestTemplates: application/json: "{\"statusCode\": 200}" passthroughBehavior: "never" type: "mock" components: schemas: Empty: type: "object" ``` ------ #### [ OpenAPI 2.0 ] ``` swagger: "2.0" info: description: "cors-api" version: "2024-01-16T18:36:01Z" title: "cors-api" basePath: "/test" schemes: - "https" paths: /: get: operationId: "GetPet" produces: - "application/json" responses: "200": description: "200 response" headers: Access-Control-Allow-Origin: type: "string" x-amazon-apigateway-integration: httpMethod: "GET" uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets" responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Origin: "'*'" passthroughBehavior: "never" type: "http" options: consumes: - "application/json" produces: - "application/json" responses: "200": description: "200 response" schema: $ref: "#/definitions/Empty" headers: Access-Control-Allow-Origin: type: "string" Access-Control-Allow-Methods: type: "string" Access-Control-Allow-Headers: type: "string" x-amazon-apigateway-integration: responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'" method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Origin: "'*'" requestTemplates: application/json: "{\"statusCode\": 200}" passthroughBehavior: "never" type: "mock" definitions: Empty: type: "object" ``` ------ # Prueba de CORS para una API en API Gateway Puede probar la configuración de CORS de su API invocando su API y comprobando los encabezados de CORS en la respuesta. El siguiente comando `curl` envía una solicitud OPTIONS a una API implementada. ``` curl -v -X OPTIONS https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name} ``` ``` < HTTP/1.1 200 OK < Date: Tue, 19 May 2020 00:55:22 GMT < Content-Type: application/json < Content-Length: 0 < Connection: keep-alive < x-amzn-RequestId: a1b2c3d4-5678-90ab-cdef-abc123 < Access-Control-Allow-Origin: * < Access-Control-Allow-Headers: Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token < x-amz-apigw-id: Abcd= < Access-Control-Allow-Methods: DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT ``` Los encabezados `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers` y `Access-Control-Allow-Methods` de la respuesta muestran que la API admite CORS. Para obtener más información, consulte [CORS para las API de REST en API Gateway](how-to-cors.md). # Tipos de medios binarios para las API de REST en API Gateway En API Gateway, la solicitud y respuesta de la API tienen una carga de texto o binaria. Una carga de texto es una cadena JSON codificada en `UTF-8`. Una carga binaria es cualquier otra cosa distinta de una carga de texto. La carga binaria puede ser, por ejemplo, un archivo JPEG, un archivo GZip o un archivo XML. La configuración de la API necesaria para admitir medios binarios depende de si la API utiliza integraciones de proxy o que no son de proxy. Si utiliza una integración de proxy con transmisión de respuesta de carga útil, no necesita configurar los tipos de medios binarios. Para obtener más información, consulte [Transmisión de la respuesta de integración para las integraciones de proxy en API Gateway](response-transfer-mode.md). ## AWS LambdaIntegraciones proxy de Para tratar cargas útiles binarias para integraciones proxy de AWS Lambda, debe codificar a base64 la respuesta de su función. También debe configurar [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) para su API. La configuración `binaryMediaTypes` de su API es una lista de tipos de contenido que su API trata como datos binarios. Los tipos de medios binarios de ejemplo incluyen `image/png` o `application/octet-stream`. Puede utilizar el carácter comodín (`*`) para cubrir varios tipos de medios. API Gateway utiliza el primer encabezado `Accept` de los clientes para determinar si una respuesta debe devolver medios binarios. Para devolver medios binarios cuando no se puede controlar el orden de los valores de encabezado `Accept`, como las solicitudes de un navegador, establezca los tipos de medios binarios de la API en `*/*`. Para ver el código de ejemplo, consulte [Devolución de medios binarios desde una integración de proxy de Lambda en API Gateway](lambda-proxy-binary-media.md). Si utiliza una integración de proxy de Lambda con transmisión de respuesta de carga útil, no necesita configurar los tipos de medios binarios. Para obtener más información, consulte [Configuración de una integración de proxy de Lambda con transmisión de respuesta de carga útil en API Gateway](response-transfer-mode-lambda.md). ## Integraciones que no son de proxy Para tratar cargas binarias para integraciones que no son de proxy, agregue los tipos de medios a la lista [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) del recurso `RestApi`. La configuración `binaryMediaTypes` de su API es una lista de tipos de contenido que su API trata como datos binarios. Como alternativa, puede establecer las propiedades [contentHandling](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) en los recursos [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) e [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html). El valor `contentHandling` puede ser `CONVERT_TO_BINARY`, `CONVERT_TO_TEXT` o no estar definido. **nota** En el caso de las integraciones de `MOCK` o privadas, no se permite establecer las propiedades `contentHandling` en la Consola de administración de AWS. Debe usar la AWS CLI, CloudFormation o un SDK para establecer las propiedades `contentHandling`. En función del valor de `contentHandling` y de si el encabezado `Content-Type` de la respuesta o el encabezado `Accept` de la solicitud coinciden con una entrada de la lista `binaryMediaTypes`, API Gateway puede codificar los bytes binarios sin formato como una cadena codificada en base64, descodificar una cadena codificada en base64 en sus bytes sin formato o transferir el cuerpo sin realizar ninguna modificación. Debe configurar la API como se indica a continuación para que su API de API Gateway admita cargas binarias: + Agregue los tipos de medios binarios que desee a la lista `binaryMediaTypes` en el recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html). Si esta propiedad y la `contentHandling` propiedad no se definen, las cargas se administran como cadenas JSON codificadas en UTF-8. + Diríjase a la propiedad `contentHandling` del recurso [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). + Para que la carga de solicitud se convierta de una cadena codificada en base64 a su blob binario, establezca la propiedad en `CONVERT_TO_BINARY`. + Para que la carga de solicitud se convierta de un blob binario a una cadena codificada en base64, establezca la propiedad en `CONVERT_TO_TEXT`. + Para pasar la carga útil sin modificaciones, deje la propiedad sin definir. Para pasar una carga binaria sin modificaciones, también debe asegurarse de que `Content-Type` coincide con una de las entradas de `binaryMediaTypes` y que los [comportamientos del acceso directo](integration-passthrough-behaviors.md) están habilitados para la API. + Establezca la propiedad `contentHandling` del recurso [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html). La propiedad `contentHandling`, el encabezado `Accept` en las solicitudes de cliente y los `binaryMediaTypes` de su API combinados determinan cómo API Gateway trata las conversiones de los tipos de contenido. Para obtener información, consulte [Conversiones de tipo de contenido en API Gateway](api-gateway-payload-encodings-workflow.md). **importante** Cuando una solicitud contiene varios tipos de medios en su encabezado `Accept`, API Gateway solo respeta el primer tipo de medio `Accept`. Si no puede controlar el orden de los tipos de medios `Accept` y el tipo de medio del contenido binario no sea el primero de la lista, agregue el primer tipo de medio `Accept` en la lista `binaryMediaTypes` de la API. API Gateway gestiona todos los tipos de contenido de esta lista como binarios. Por ejemplo, para enviar un archivo JPEG utilizando un elemento `` en un navegador, el navegador puede enviar `Accept:image/webp,image/*,*/*;q=0.8` en una solicitud. Al añadir `image/webp` a la lista `binaryMediaTypes`, el punto de conexión recibe el archivo JPEG como binario. Para obtener información detallada sobre cómo API Gateway trata el texto y las cargas binarias, consulte [Conversiones de tipo de contenido en API Gateway](api-gateway-payload-encodings-workflow.md). # Conversiones de tipo de contenido en API Gateway La combinación de los `binaryMediaTypes` de su API, los encabezados de las solicitudes de cliente y la propiedad `contentHandling` de integración determinan cómo API Gateway codifica las cargas útiles. La siguiente tabla muestra cómo API Gateway convierte la carga útil de solicitud para configuraciones específicas del encabezado `Content-Type` de una solicitud, la lista `binaryMediaTypes` de un recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) y el valor de la propiedad `contentHandling` del recurso [Integración](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). | Carga de solicitud de método | Encabezado `Content-Type` de solicitud | `binaryMediaTypes` | `contentHandling` | Carga de solicitud de integración | | --- | --- | --- | --- | --- | | Datos de texto | Cualquier tipo de datos | Sin definir | Sin definir | Cadena codificada en UTF8 | | Datos de texto | Cualquier tipo de datos | Sin definir | CONVERT\$1TO\$1BINARY | Blob binario descodificado en Base64 | | Datos de texto | Cualquier tipo de datos | Sin definir | CONVERT\$1TO\$1TEXT | Cadena codificada en UTF8 | | Datos de texto | Un tipo de datos de texto | Establecida con tipos de medios coincidentes | Sin definir | Datos de texto | | Datos de texto | Un tipo de datos de texto | Establecida con tipos de medios coincidentes | CONVERT\$1TO\$1BINARY | Blob binario descodificado en Base64 | | Datos de texto | Un tipo de datos de texto | Establecida con tipos de medios coincidentes | CONVERT\$1TO\$1TEXT | Datos de texto | | Datos binarios | Un tipo de datos binarios | Establecida con tipos de medios coincidentes | Sin definir | Datos binarios | | Datos binarios | Un tipo de datos binarios | Establecida con tipos de medios coincidentes | CONVERT\$1TO\$1BINARY | Datos binarios | | Datos binarios | Un tipo de datos binarios | Establecida con tipos de medios coincidentes | CONVERT\$1TO\$1TEXT | Cadena codificada en Base64 | La siguiente tabla muestra cómo API Gateway convierte la carga útil de respuesta para configuraciones específicas del encabezado `Accept` de una solicitud, la lista `binaryMediaTypes` de un recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) y el valor de la propiedad `contentHandling` del recurso [Respuesta de integración](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html). **importante** Cuando una solicitud contiene varios tipos de medios en su encabezado `Accept`, API Gateway solo respeta el primer tipo de medio `Accept`. Si no puede controlar el orden de los tipos de medios `Accept` y el tipo de medio del contenido binario no sea el primero de la lista, agregue el primer tipo de medio `Accept` en la lista `binaryMediaTypes` de la API. API Gateway gestiona todos los tipos de contenido de esta lista como binarios. Por ejemplo, para enviar un archivo JPEG utilizando un elemento `` en un navegador, el navegador puede enviar `Accept:image/webp,image/*,*/*;q=0.8` en una solicitud. Al añadir `image/webp` a la lista `binaryMediaTypes`, el punto de conexión recibe el archivo JPEG como binario. | Carga de respuesta de integración | Encabezado `Accept` de solicitud | `binaryMediaTypes` | `contentHandling` | Carga de respuesta de método | | --- | --- | --- | --- | --- | | Datos de texto o binarios | Un tipo de texto | Sin definir | Sin definir | Cadena codificada en UTF8 | | Datos de texto o binarios | Un tipo de texto | Sin definir | CONVERT\$1TO\$1BINARY | Blob descodificado en Base64 | | Datos de texto o binarios | Un tipo de texto | Sin definir | CONVERT\$1TO\$1TEXT | Cadena codificada en UTF8 | | Datos de texto | Un tipo de texto | Establecida con tipos de medios coincidentes | Sin definir | Datos de texto | | Datos de texto | Un tipo de texto | Establecida con tipos de medios coincidentes | CONVERT\$1TO\$1BINARY | Blob descodificado en Base64 | | Datos de texto | Un tipo de texto | Establecida con tipos de medios coincidentes | CONVERT\$1TO\$1TEXT | Cadena codificada en UTF8 | | Datos de texto | Un tipo binario | Establecida con tipos de medios coincidentes | Sin definir | Blob descodificado en Base64 | | Datos de texto | Un tipo binario | Establecida con tipos de medios coincidentes | CONVERT\$1TO\$1BINARY | Blob descodificado en Base64 | | Datos de texto | Un tipo binario | Establecida con tipos de medios coincidentes | CONVERT\$1TO\$1TEXT | Cadena codificada en UTF8 | | Datos binarios | Un tipo de texto | Establecida con tipos de medios coincidentes | Sin definir | Cadena codificada en Base64 | | Datos binarios | Un tipo de texto | Establecida con tipos de medios coincidentes | CONVERT\$1TO\$1BINARY | Datos binarios | | Datos binarios | Un tipo de texto | Establecida con tipos de medios coincidentes | CONVERT\$1TO\$1TEXT | Cadena codificada en Base64 | | Datos binarios | Un tipo binario | Establecida con tipos de medios coincidentes | Sin definir | Datos binarios | | Datos binarios | Un tipo binario | Establecida con tipos de medios coincidentes | CONVERT\$1TO\$1BINARY | Datos binarios | | Datos binarios | Un tipo binario | Establecida con tipos de medios coincidentes | CONVERT\$1TO\$1TEXT | Cadena codificada en Base64 | Cuando se convierte una carga de texto en un blob binario, API Gateway asume que los datos de texto son una cadena codificada en base64 y envía los datos binarios como un blob descodificado en base64. Si la conversión produce un error, devuelve una respuesta `500`, que indica un error de configuración de la API. No tiene que proporcionar una plantilla de asignación para este tipo de conversión, pero sí debe habilitar los [comportamientos de paso a través](integration-passthrough-behaviors.md) en la API. Al convertir una carga binaria en una cadena de texto, API Gateway siempre aplica una codificación en base64 a los datos binarios. Puede definir una plantilla de asignación para este tipo de carga, pero solo puede tener acceso a la cadena codificada en base64 en la plantilla de asignación a través de `$input.body`, tal y como se muestra en el fragmento siguiente de una plantilla de asignación de ejemplo. ``` { "data": "$input.body" } ``` Para que se transfiera la carga binaria sin modificaciones, debe habilitar los [comportamientos de paso a través](integration-passthrough-behaviors.md) en la API. # Habilitar la compatibilidad con datos binarios mediante la consola de API Gateway En esta sección se explica cómo habilitar la compatibilidad con datos binarios en la consola de API Gateway. A modo de ejemplo, usaremos una API que está integrada con Amazon S3. Nos centraremos en las tareas para establecer tipos de medios compatibles y para especificar cómo debe controlarse la carga. Para obtener información detallada sobre cómo crear una API integrada con Amazon S3, consulte [Tutorial: Creación de una API de REST como proxy de Amazon S3](integrating-api-with-aws-services-s3.md). **Para habilitar la compatibilidad con datos binarios utilizando la consola de API Gateway** 1. Establezca tipos de medios binarios para la API: 1. Cree una nueva API o elija una API existente. En este ejemplo, asignaremos a la API el nombre de `FileMan`. 1. Bajo la API seleccionada, en el panel de navegación principal, seleccione **Configuración de API**. 1. En el panel **Configuración de API**, elija **Administrar tipos de medios** en la sección **Tipos de medios binarios**. 1. Seleccione **Añadir tipo de medio binario**. 1. Escriba un tipo de medio necesario (por ejemplo, **image/png**) en el campo de texto. Si es necesario, repita este paso para añadir más tipos de medios. Para admitir todos los tipos de medios binarios, especifique `*/*`. 1. Seleccione **Save changes (Guardar cambios)**. 1. Establezca cómo se administran las cargas de mensajes para el método de API: 1. Cree un nuevo recurso o elija uno existente en la API. Para este ejemplo, usaremos el recurso `/{folder}/{item}`. 1. Cree un nuevo método o elija uno existente en el recurso. Como ejemplo, usaremos el método `GET /{folder}/{item}` integrado con la acción `Object GET` en Amazon S3. 1. En **Tratamiento de contenido**, elija una opción. ![\[Configure el método GET en la consola de API Gateway.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/binary-support-content-handling-on-method-new-console.png) Elija **Passthrough (Paso a través)** si no desea convertir el cuerpo cuando el cliente y el backend acepten el mismo formato binario. Elija **Convertir en texto** para convertir el cuerpo binario en una cadena codificada en base64 cuando, por ejemplo, el backend requiera que una carga de solicitud binaria se pase como una propiedad JSON. Y elija **Convertir en binario** cuando el cliente envíe una cadena codificada en base64 y el backend requiera el formato binario original, o cuando el punto de conexión devuelva una cadena codificada en base64 y el cliente acepte únicamente la salida binaria. 1. En **Acceso directo de cuerpo de la solicitud**, elija **Cuando no hay plantillas definidas (recomendado)** para activar el comportamiento de acceso directo en el cuerpo de la solicitud. También puede elegir **Nunca**. Esto significa que la API rechazará los datos con tipos de contenido que no tengan una plantilla de mapeo. 1. Conserve el encabezado `Accept` de la solicitud entrante en la solicitud de integración. Debe hacerlo si ha establecido `contentHandling` en `passthrough` y desea invalidar esa configuración en tiempo de ejecución. ![\[Mantenga el encabezado Accept en la solicitud de integración.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/binary-support-preserve-incoming-accept-header-new-console.png) 1. Para la conversión en texto, defina una plantilla de asignación para aplicar a los datos binarios codificados en base64 el formato requerido. Este es un ejemplo de plantilla de mapeo para convertirla en texto: ``` { "operation": "thumbnail", "base64Image": "$input.body" } ``` El formato de esta plantilla de asignación depende de los requisitos de punto de conexión de la entrada. 1. Seleccione **Save**. # Habilitar la compatibilidad con datos binarios mediante la API Gateway REST API Las siguientes tareas muestran cómo habilitar la compatibilidad con datos binarios mediante llamadas a la API REST de API Gateway. **Topics** + [ ## Añadir y actualizar tipos de medios binarios compatibles en una API ](#api-gateway-payload-encodings-setup-with-api-set-encodings-map) + [ ## Configurar las conversiones de carga de solicitud ](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding) + [ ## Configurar conversiones de carga de respuesta ](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding) + [ ## Convertir datos binarios en datos de texto ](#api-gateway-payload-encodings-convert-binary-to-string) + [ ## Convertir datos de texto en una carga binaria ](#api-gateway-payload-encodings-convert-string-to-binary) + [ ## Transferir una carga binaria ](#api-gateway-payload-encodings-pass-binary-as-is) ## Añadir y actualizar tipos de medios binarios compatibles en una API Para habilitar API Gateway para que admita un nuevo tipo de medios binarios, debe agregar el tipo de medios binarios a la lista `binaryMediaTypes` del recurso `RestApi`. Por ejemplo, para que API Gateway admita imágenes JPEG, envíe una solicitud `PATCH` al recurso `RestApi`: ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/image~1jpeg" } ] } ``` La especificación del tipo MIME de `image/jpeg` que forma parte del valor de la propiedad `path` se ha incluido en una secuencia de escape: `image~1jpeg`. Para actualizar los tipos de medios binarios compatibles, sustituya o elimine el tipo de medios en la lista `binaryMediaTypes` del recurso `RestApi`. Por ejemplo, para cambiar la compatibilidad binaria de archivos JPEG a bytes sin formato, envíe una solicitud `PATCH` al recurso `RestApi`, tal y como se indica a continuación: ``` PATCH /restapis/ { "patchOperations" : [{ "op" : "replace", "path" : "/binaryMediaTypes/image~1jpeg", "value" : "application/octet-stream" }, { "op" : "remove", "path" : "/binaryMediaTypes/image~1jpeg" }] } ``` ## Configurar las conversiones de carga de solicitud Si el punto de conexión requiere una entrada binaria, establezca la propiedad `contentHandling` del recurso `Integration` en `CONVERT_TO_BINARY`. Para ello, envíe una solicitud `PATCH` de la siguiente manera: ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] } ``` ## Configurar conversiones de carga de respuesta Si el cliente acepta el resultado como un blob binario en lugar de una carga codificada en base64 devuelta por el punto de conexión, establezca la propiedad `contentHandling` del recurso `IntegrationResponse` en `CONVERT_TO_BINARY`. Para ello, envíe una solicitud `PATCH`, de la siguiente manera: ``` PATCH /restapis//resources//methods//integration/responses/ { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] } ``` ## Convertir datos binarios en datos de texto Para enviar datos binarios como una propiedad JSON de la entrada a AWS Lambda o Kinesis a través de API Gateway, haga lo siguiente: 1. Habilite la compatibilidad de carga binaria de la API añadiendo el nuevo tipo de medios binarios de `application/octet-stream` a la lista `binaryMediaTypes` de la API. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] } ``` 1. Establezca `CONVERT_TO_TEXT` en la propiedad `contentHandling` del recurso `Integration` y proporcione una plantilla de asignación para asignar la cadena codificada en base64 de los datos binarios a una propiedad JSON. En el siguiente ejemplo, la propiedad JSON es `body` y `$input.body` contiene la cadena codificada en base64. ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_TEXT" }, { "op" : "add", "path" : "/requestTemplates/application~1octet-stream", "value" : "{\"body\": \"$input.body\"}" } ] } ``` ## Convertir datos de texto en una carga binaria Supongamos que tiene una función de Lambda que devuelve un archivo de imagen como una cadena codificada en base64. Para pasar esta salida binaria al cliente a través de API Gateway, haga lo siguiente: 1. Actualice la lista `binaryMediaTypes` de la API añadiendo el tipo de medios binarios de `application/octet-stream`, si aún no está en la lista. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream", }] } ``` 1. Establezca la propiedad `contentHandling` del recurso `Integration` en `CONVERT_TO_BINARY`. No defina una plantilla de asignación. Si no define una plantilla de mapeo, API Gateway llama a la plantilla de paso a través para devolver el blob binario descodificado en base64 como el archivo de imagen al cliente. ``` PATCH /restapis//resources//methods//integration/responses/ { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" } ] } ``` ## Transferir una carga binaria Para almacenar una imagen en un bucket de Amazon S3 utilizando API Gateway, haga lo siguiente: 1. Actualice la lista `binaryMediaTypes` de la API añadiendo el tipo de medios binarios de `application/octet-stream`, si aún no está en la lista. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] } ``` 1. En la propiedad `contentHandling` del recurso `Integration`, establezca `CONVERT_TO_BINARY`. Establezca `WHEN_NO_MATCH` como el valor de la propiedad `passthroughBehavior` sin definir una plantilla de asignación. Esto permite a API Gateway invocar la plantilla de acceso directo. ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }, { "op" : "replace", "path" : "/passthroughBehaviors", "value" : "WHEN_NO_MATCH" } ] } ``` # Importación y exportación de codificaciones de contenido para API Gateway Para importar la lista `binaryMediaTypes` de un recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), use la siguiente extensión de API Gateway al archivo de definición de OpenAPI de la API. La extensión también se utiliza para exportar la configuración de la API. + [Propiedad x-amazon-apigateway-binary-media-types](api-gateway-swagger-extensions-binary-media-types.md) Para importar y exportar los valores de la propiedad `contentHandling` en un recurso `Integration` o `IntegrationResponse`, utilice las siguientes extensiones de API Gateway a las definiciones de OpenAPI: + [Objeto x-amazon-apigateway-integration](api-gateway-swagger-extensions-integration.md) + [Objeto x-amazon-apigateway-integration.response](api-gateway-swagger-extensions-integration-response.md) # Devolución de medios binarios desde una integración de proxy de Lambda en API Gateway Para devolver medios binarios desde una [integración de proxy de AWS Lambda](set-up-lambda-proxy-integrations.md), base64 codifica la respuesta de su función de Lambda. También debe [configurar los tipos de medios binarios de su API](api-gateway-payload-encodings-configure-with-console.md). Cuando configura los tipos de medios binarios de la API, esta trata ese tipo de contenido como datos binarios. El límite de tamaño de carga es 10 MB. **nota** Para utilizar un navegador web para invocar una API con esta integración de ejemplo, establezca los tipos de medios binarios de la API en `*/*`. API Gateway utiliza el primer encabezado `Accept` de los clientes para determinar si una respuesta debe devolver medios binarios. Para devolver medios binarios cuando no puede controlar el orden de los valores de encabezado `Accept`, como las solicitudes de un navegador, establezca los tipos de medios binarios de la API en `*/*` (para todos los tipos de contenido). En el siguiente ejemplo, la función de Lambda puede devolver una imagen binaria a partir de Amazon S3 o texto a los clientes. La respuesta de la función incluye un encabezado `Content-Type` para indicar al cliente el tipo de datos que devuelve. La función establece condicionalmente la propiedad `isBase64Encoded` en su respuesta, dependiendo del tipo de datos que devuelve. ------ #### [ Node.js ] ``` import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3" const client = new S3Client({region: 'us-east-2'}); export const handler = async (event) => { var randomint = function(max) { return Math.floor(Math.random() * max); } var number = randomint(2); if (number == 1){ const input = { "Bucket" : "bucket-name", "Key" : "image.png" } try { const command = new GetObjectCommand(input) const response = await client.send(command); var str = await response.Body.transformToByteArray(); } catch (err) { console.error(err); } const base64body = Buffer.from(str).toString('base64'); return { 'headers': { "Content-Type": "image/png" }, 'statusCode': 200, 'body': base64body, 'isBase64Encoded': true } } else { return { 'headers': { "Content-Type": "text/html" }, 'statusCode': 200, 'body': "

This is text

", } } } ``` ------ #### [ Python ] ``` import base64 import boto3 import json import random s3 = boto3.client('s3') def lambda_handler(event, context): number = random.randint(0,1) if number == 1: response = s3.get_object( Bucket='bucket-name', Key='image.png', ) image = response['Body'].read() return { 'headers': { "Content-Type": "image/png" }, 'statusCode': 200, 'body': base64.b64encode(image).decode('utf-8'), 'isBase64Encoded': True } else: return { 'headers': { "Content-type": "text/html" }, 'statusCode': 200, 'body': "

This is text

", } ``` ------ Para obtener más información sobre los tipos de medios binarios, consulte [Tipos de medios binarios para las API de REST en API Gateway](api-gateway-payload-encodings.md). # Acceder a archivos binarios en Amazon S3 a través de una API de API Gateway Los siguientes ejemplos muestran el archivo de OpenAPI utilizado para obtener acceso a las imágenes en Amazon S3, cómo descargar una imagen de Amazon S3 y cómo cargar una imagen en Amazon S3. **Topics** + [ ## Archivo de OpenAPI de una API de ejemplo para obtener acceso a imágenes en Amazon S3 ](#api-gateway-content-encodings-example-image-s3-swagger-file) + [ ## Descargar una imagen de Amazon S3 ](#api-gateway-content-encodings-example-download-image-from-s3) + [ ## Cargar una imagen en Amazon S3 ](#api-gateway-content-encodings-example-upload-image-to-s3) ## Archivo de OpenAPI de una API de ejemplo para obtener acceso a imágenes en Amazon S3 El siguiente archivo de OpenAPI muestra una API de ejemplo que ilustra cómo descargar un archivo de imagen de Amazon S3 y cargarlo en Amazon S3. Esta API expone los métodos `GET /s3?key={file-name}` y `PUT /s3?key={file-name}` para descargar y cargar un archivo de imagen especificado. El método `GET` devuelve el archivo de imagen como una cadena codificada en base64 como parte de una salida JSON, siguiendo la plantilla de asignación suministrada, en una respuesta 200 OK. El método `PUT` toma un blob binario sin formato como entrada y devuelve una respuesta 200 OK con una carga vacía. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "paths": { "/s3": { "get": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "GET", "type": "aws" } }, "put": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } }, "application/octet-stream": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "PUT", "type": "aws", "contentHandling": "CONVERT_TO_BINARY" } } } }, "x-amazon-apigateway-binary-media-types": [ "application/octet-stream", "image/jpeg" ], "servers": [ { "url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/v1" } } } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "host": "abcdefghi.execute-api.us-east-1.amazonaws.com", "basePath": "/v1", "schemes": [ "https" ], "paths": { "/s3": { "get": { "produces": [ "application/json" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "GET", "type": "aws" } }, "put": { "produces": [ "application/json", "application/octet-stream" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "PUT", "type": "aws", "contentHandling" : "CONVERT_TO_BINARY" } } } }, "x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"], "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ ## Descargar una imagen de Amazon S3 Para descargar un archivo de imagen (`image.jpg`) como un blob binario desde Amazon S3: ``` GET /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/octet-stream ``` Una respuesta correcta tiene un aspecto similar al siguiente: ``` 200 OK HTTP/1.1 [raw bytes] ``` Los bytes sin procesar se devuelven, ya que el encabezado `Accept` está establecido en un tipo de medio binario de `application/octet-stream` y la compatibilidad con los datos binarios está habilitada para la API. Para descargar un archivo de imagen (`image.jpg`) como una cadena codificada en base64 con formato de propiedad JSON, también puede, en Amazon S3, agregar una plantilla de respuesta a la respuesta de integración 200, como se muestra en el siguiente bloque de definición de OpenAPI que aparece en negrita: ``` "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } }, ``` La solicitud para descargar el archivo de imagen tiene un aspecto similar al siguiente: ``` GET /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json ``` Una respuesta correcta tiene un aspecto similar al siguiente: ``` 200 OK HTTP/1.1 { "image": "W3JhdyBieXRlc10=" } ``` ## Cargar una imagen en Amazon S3 Para cargar un archivo de imagen (`image.jpg`) como un blob binario en Amazon S3: ``` PUT /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/octet-stream Accept: application/json [raw bytes] ``` Una respuesta correcta tiene un aspecto similar al siguiente: ``` 200 OK HTTP/1.1 ``` Para cargar un archivo de imagen (`image.jpg`) como una cadena codificada en base64 en Amazon S3: ``` PUT /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json W3JhdyBieXRlc10= ``` La carga de entrada debe ser una cadena codificada en base64, ya que el valor del encabezado `Content-Type` está establecido en `application/json`. Una respuesta correcta tiene un aspecto similar al siguiente: ``` 200 OK HTTP/1.1 ``` # Acceder a archivos binarios en Lambda a través de una API de API Gateway El siguiente ejemplo de OpenAPI ilustra cómo acceder a un archivo binario en AWS Lambda a través de una API de API Gateway. Esta API expone los métodos `GET /lambda?key={file-name}` y `PUT /lambda?key={file-name}` para descargar y cargar un archivo de imagen especificado. El método `GET` devuelve el archivo de imagen como una cadena codificada en base64 como parte de una salida JSON, siguiendo la plantilla de asignación suministrada, en una respuesta 200 OK. El método `PUT` toma un blob binario sin formato como entrada y devuelve una respuesta 200 OK con una carga vacía. Se crea la función de Lambda a la que llama la API y esta debe devolver una cadena codificada en base64 con el encabezado `Content-Type` de `application/json`. **Topics** + [ ## Archivo de OpenAPI de una API de ejemplo para obtener acceso a imágenes en Lambda ](#api-gateway-content-encodings-example-image-lambda-swagger-file) + [ ## Descargar una imagen de Lambda ](#api-gateway-content-encodings-example-download-image-from-lambda) + [ ## Cargar una imagen en Lambda ](#api-gateway-content-encodings-example-upload-image-to-lambda) ## Archivo de OpenAPI de una API de ejemplo para obtener acceso a imágenes en Lambda El siguiente archivo de OpenAPI muestra una API de ejemplo que ilustra cómo descargar un archivo de imagen de Lambda y cargarlo en Lambda. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "paths": { "/lambda": { "get": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } } } }, "put": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } }, "application/octet-stream": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } } } } } }, "x-amazon-apigateway-binary-media-types": [ "application/octet-stream", "image/jpeg" ], "servers": [ { "url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/v1" } } } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "host": "abcdefghi.execute-api.us-east-1.amazonaws.com", "basePath": "/v1", "schemes": [ "https" ], "paths": { "/lambda": { "get": { "produces": [ "application/json" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } } } }, "put": { "produces": [ "application/json", "application/octet-stream" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "contentHandling" : "CONVERT_TO_TEXT", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } } } } } }, "x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"], "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ ## Descargar una imagen de Lambda Para descargar un archivo de imagen (`image.jpg`) como un blob binario desde Lambda: ``` GET /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/octet-stream ``` Una respuesta correcta tiene un aspecto similar al siguiente: ``` 200 OK HTTP/1.1 [raw bytes] ``` Para descargar un archivo de imagen (`image.jpg`) como una cadena codificada en base64, formateada como una propiedad JSON, desde Lambda: ``` GET /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json ``` Una respuesta correcta tiene un aspecto similar al siguiente: ``` 200 OK HTTP/1.1 { "image": "W3JhdyBieXRlc10=" } ``` ## Cargar una imagen en Lambda Para cargar un archivo de imagen (`image.jpg`) como un blob binario en Lambda: ``` PUT /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/octet-stream Accept: application/json [raw bytes] ``` Una respuesta correcta tiene un aspecto similar al siguiente: ``` 200 OK ``` Para cargar un archivo de imagen (`image.jpg`) como una cadena codificada en base64 en Lambda: ``` PUT /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json W3JhdyBieXRlc10= ``` Una respuesta correcta tiene un aspecto similar al siguiente: ``` 200 OK ``` # Invocación de las API de REST en API Gateway Para llamar a una API implementada, los clientes envían solicitudes a la URL del servicio del componente de API Gateway para la ejecución de API, denominado `execute-api`. La URL base de las API de REST tiene el siguiente formato: ``` https://api-id.execute-api.region.amazonaws.com/stage/ ``` donde *api-id* es el identificador de la API, *region* es la región de AWS y *stage* es el nombre de la etapa de la implementación de la API. **importante** Antes de poder invocar una API, debe implementarla en API Gateway. Para obtener instrucciones sobre cómo implementar una API, consulte [Implementación de las API de REST en API Gateway](how-to-deploy-api.md). **Topics** + [ ## Obtención de la URL de invocación de una API ](#apigateway-how-to-call-rest-api) + [ ## Invocación de una API ](#apigateway-call-api) + [ # Uso de la consola de API Gateway para probar un método de la API REST ](how-to-test-method.md) + [ # Uso de un SDK de Java generado por API Gateway para una API REST ](how-to-call-apigateway-generated-java-sdk.md) + [ # Uso de un SDK de Android generado por API Gateway para una API REST ](how-to-generate-sdk-android.md) + [ # Uso de un SDK de JavaScript generado por API Gateway para una API REST ](how-to-generate-sdk-javascript.md) + [ # Uso de un SDK de Ruby generado por API Gateway para una API REST ](how-to-call-sdk-ruby.md) + [ # Uso de un SDK de iOS generado por API Gateway para una API REST en Objective-C o Swift ](how-to-generate-sdk-ios.md) ## Obtención de la URL de invocación de una API Puede usar la consola, la AWS CLI o una definición de OpenAPI exportada para obtener la URL de invocación de una API. ### Obtención de la URL de invocación de una API con la consola En el siguiente procedimiento se muestra cómo obtener la URL de invocación de una API en la consola de la API de REST. **Obtención de la URL de invocación de una API con la consola de API de REST** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API implementada. 1. En el panel de navegación principal, elija **Etapa**. 1. En **Detalles de la etapa**, elija el icono de copia para copiar la URL de invocación de la API. Esta URL es para el recurso raíz de la API. ![\[Después de crear la API de REST, la consola muestra la URL de invocación de la API.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/getting-started-rest-invoke-url.png) 1. Para obtener la URL de invocación de una API para otro recurso de la API, expanda la etapa bajo el panel de navegación secundario y, a continuación, elija un método. 1. Elija el icono de copiar para copiar la URL de invocación en el nivel de recursos de la API. ![\[La URL en el nivel de recursos de la API de REST se encuentra en el panel de navegación secundario de la etapa.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/resource-level-invoke-url.png) #### Obtención de la URL de invocación de una API con la AWS CLI En el siguiente procedimiento se muestra cómo obtener la URL de invocación de una API con la AWS CLI. **Obtención de la URL de invocación de una API con la AWS CLI** 1. Utilice el siguiente comando para obtener `rest-api-id`. Este comando devuelve todos los valores `rest-api-id` de la región. Para obtener más información, consulte [get-rest-apis](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-rest-apis.html). ``` aws apigateway get-rest-apis ``` 1. Sustituya `rest-api-id` del ejemplo por su `rest-api-id`, sustituya *\$1stage-name\$1* del ejemplo por su *\$1stage-name\$1* y sustituya *\$1region\$1* por su región. ``` https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/ ``` ##### Obtención de la URL de invocación de una API mediante el archivo de definición de OpenAPI exportado de la API También puede crear la URL raíz combinando los campos `host` y `basePath` de un archivo de definición de OpenAPI exportado de la API. Para obtener instrucciones acerca de cómo exportar la API, consulte [Exportación de una API REST desde API Gateway](api-gateway-export-api.md). ## Invocación de una API Puede llamar a la API implementada mediante el navegador, curl u otras aplicaciones, como [Postman](https://www.postman.com/). Además, puede utilizar la consola de API Gateway para probar una llamada a la API. La prueba utiliza la característica `TestInvoke` de API Gateway, que permite probar la API antes de que se implemente la API. Para obtener más información, consulte [Uso de la consola de API Gateway para probar un método de la API REST](how-to-test-method.md). **nota** Los valores de los parámetros de cadenas de consulta en una URL de invocación no pueden contener `%%`. ### Invocación de una API mediante un navegador web Si la API permite el acceso anónimo, puede utilizar cualquier navegador web para invocar cualquier método `GET`. Ingrese la URL de invocación completa en la barra de dirección del navegador. Para otros métodos o para todas las llamadas que requieran autenticación, debe especificar una carga o firmar las solicitudes. Puede realizar esto en un script detrás de una página HTML o en una aplicación cliente mediante uno de los SDK de AWS. #### Invocación de una API mediante curl Puede usar una herramienta como [curl](https://curl.se/) en el terminal para llamar a la API. El siguiente comando curl de ejemplo invoca el método GET en el recurso `getUsers` de la fase `prod` de una API. ------ #### [ Linux or Macintosh ] ``` curl -X GET 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers' ``` ------ #### [ Windows ] ``` curl -X GET "https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers" ``` ------ # Uso de la consola de API Gateway para probar un método de la API REST Uso de la consola de API Gateway para probar un método de la API REST. **Topics** + [ ## Requisitos previos ](#how-to-test-method-prerequisites) + [ ## Probar un modelo con la consola de API Gateway ](#how-to-test-method-console) ## Requisitos previos + Debe especificar la configuración de los métodos que desea probar. Siga las instrucciones en [Métodos de API de REST en API Gateway](how-to-method-settings.md). ## Probar un modelo con la consola de API Gateway **importante** La prueba de métodos con la consola de API Gateway puede provocar cambios en los recursos que no se pueden deshacer. Probar un método con la consola API Gateway es lo mismo que llamar al método desde fuera de la consola de API Gateway. Por ejemplo, si utiliza la consola de API Gateway para llamar a un método que elimina recursos de una API, si la llamada al método se realiza correctamente, se eliminarán los recursos de la API. **Para probar un método** 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. En el panel **Resources (Recursos)**, elija el método que desea probar. 1. Elija la pestaña **Prueba**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña. ![\[Use la pestaña de prueba para probar la API. Se encuentra junto a la pestaña de respuesta del método.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/api-gateway-test-new-console.png) Escriba valores en cualquiera de los cuadros mostrados (como **Cadenas de consulta)**, **Encabezados** y **Cuerpo de solicitud**). La consola incluye estos valores en la solicitud de método con el formato application/json predeterminado. Si necesita especificar opciones adicionales, póngase en contacto con el propietario de la API. 1. Seleccione **Test (Probar)**. Se mostrará la siguiente información: + **Request (Solicitud)** es la ruta del recurso llamada para el método. + **Status (Estado)** es el código de estado HTTP de la respuesta. + **Latencia (ms)** es el tiempo entre la recepción de la solicitud del intermediario y la respuesta devuelta. + **Cuerpo de respuesta** es el cuerpo de la respuesta HTTP. + **Encabezados de respuesta** son los encabezados de respuesta HTTP. **sugerencia** En función del mapeo, el código de estado HTTP, el cuerpo de la respuesta y los encabezados de respuesta podrían ser diferentes de los enviados desde la función de Lambda, proxy HTTP o proxy de servicio de AWS. + Los**registros** son las entradas simuladas de Amazon CloudWatch Logs que se habrían escrito si se hubiera llamado a este método fuera de la consola de API Gateway. **nota** Aunque las entradas de CloudWatch Logs son simuladas, los resultados de la llamada al método son reales. Además de utilizar la consola de API Gateway, puede utilizar la AWS CLI o un AWS SDK para API Gateway para probar la invocación de un método. Para hacerlo a través de la AWS CLI, consulte [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html). # Uso de un SDK de Java generado por API Gateway para una API REST En esta sección se describen los pasos para utilizar un SDK de Java generado por API Gateway para una API REST mediante la API [Calculadora simple](simple-calc-lambda-api-swagger-definition.md) como ejemplo. Antes de continuar, debe completar los pasos de [Generación de SDK para las API de REST en API Gateway](how-to-generate-sdk.md). **Para instalar y utilizar un SDK de Java generado por API Gateway** 1. Extraiga el contenido del archivo .zip generado por API Gateway que ha descargado anteriormente. 1. Descargue e instale [Apache Maven](https://maven.apache.org/) (versión 3.5 o posterior). 1. Descargar e instalar [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html). 1. Establezca la variable de entorno `JAVA_HOME`. 1. Vaya a la carpeta SDK descomprimida donde se encuentra el archivo pom.xml. Esta carpeta es `generated-code` de forma predeterminada. Ejecute el comando **mvn install** para instalar los archivos de artefactos compilados en el repositorio de Maven local. Se creará una carpeta `target` con la biblioteca del SDK compilada. 1. Escriba el comando siguiente en un directorio vacío para crear un stub del proyecto cliente que llame a la API utilizando la biblioteca de SDK instalada. ``` mvn -B archetype:generate \ -DarchetypeGroupdId=org.apache.maven.archetypes \ -DgroupId=examples.aws.apig.simpleCalc.sdk.app \ -DartifactId=SimpleCalc-sdkClient ``` **nota** El separador `\` del comando anterior se ha incluido para facilitar la lectura. El comando completo debe estar en una sola línea sin el separador. Este comando crea un stub de aplicación. El stub de aplicación contiene un archivo `pom.xml` y una carpeta `src` en el directorio raíz del proyecto (*SimpleCalc-sdkClient* en el comando anterior). Inicialmente, hay dos archivos de código fuente: `src/main/java/{package-path}/App.java` y `src/test/java/{package-path}/AppTest.java`. En este ejemplo, *\$1package-path\$1* es `examples/aws/apig/simpleCalc/sdk/app`. Esta ruta del paquete se obtiene del valor de `DarchetypeGroupdId`. Puede utilizar el archivo `App.java` como una plantilla para la aplicación cliente y puede añadir otros archivos en la misma carpeta si es necesario. Puede utilizar el archivo `AppTest.java` como una plantilla de pruebas unitarias para su aplicación y puede añadir otros archivos de código de prueba en la misma carpeta de pruebas si es necesario. 1. Actualice las dependencias del paquete en el archivo `pom.xml` generado de la forma siguiente, sustituyendo las propiedades `groupId`, `artifactId`, `version` y `name`, si es necesario: ``` 4.0.0 examples.aws.apig.simpleCalc.sdk.app SimpleCalc-sdkClient jar 1.0-SNAPSHOT SimpleCalc-sdkClient http://maven.apache.org com.amazonaws aws-java-sdk-core 1.11.94 my-apig-api-examples simple-calc-sdk 1.0.0 junit junit 4.12 test commons-io commons-io 2.5 org.apache.maven.plugins maven-compiler-plugin 3.5.1 1.8 1.8 ``` **nota** Cuando una versión más reciente de un artefacto dependiente de `aws-java-sdk-core` no es compatible con la versión especificada anteriormente (`1.11.94`), debe actualizar la etiqueta `` a la nueva versión. 1. A continuación, mostramos cómo llamar a la API mediante el SDK llamando a los métodos `getABOp(GetABOpRequest req)`, `getApiRoot(GetApiRootRequest req)` y `postApiRoot(PostApiRootRequest req)` del SDK. Estos métodos se corresponden con los métodos `GET /{a}/{b}/{op}`, `GET /?a={x}&b={y}&op={operator}` y `POST /`, con una carga de solicitudes de API `{"a": x, "b": y, "op": "operator"}`, respectivamente. Actualice el archivo `App.java` como se indica a continuación: ``` package examples.aws.apig.simpleCalc.sdk.app; import java.io.IOException; import com.amazonaws.opensdk.config.ConnectionConfiguration; import com.amazonaws.opensdk.config.TimeoutConfiguration; import examples.aws.apig.simpleCalc.sdk.*; import examples.aws.apig.simpleCalc.sdk.model.*; import examples.aws.apig.simpleCalc.sdk.SimpleCalcSdk.*; public class App { SimpleCalcSdk sdkClient; public App() { initSdk(); } // The configuration settings are for illustration purposes and may not be a recommended best practice. private void initSdk() { sdkClient = SimpleCalcSdk.builder() .connectionConfiguration( new ConnectionConfiguration() .maxConnections(100) .connectionMaxIdleMillis(1000)) .timeoutConfiguration( new TimeoutConfiguration() .httpRequestTimeout(3000) .totalExecutionTimeout(10000) .socketTimeout(2000)) .build(); } // Calling shutdown is not necessary unless you want to exert explicit control of this resource. public void shutdown() { sdkClient.shutdown(); } // GetABOpResult getABOp(GetABOpRequest getABOpRequest) public Output getResultWithPathParameters(String x, String y, String operator) { operator = operator.equals("+") ? "add" : operator; operator = operator.equals("/") ? "div" : operator; GetABOpResult abopResult = sdkClient.getABOp(new GetABOpRequest().a(x).b(y).op(operator)); return abopResult.getResult().getOutput(); } public Output getResultWithQueryParameters(String a, String b, String op) { GetApiRootResult rootResult = sdkClient.getApiRoot(new GetApiRootRequest().a(a).b(b).op(op)); return rootResult.getResult().getOutput(); } public Output getResultByPostInputBody(Double x, Double y, String o) { PostApiRootResult postResult = sdkClient.postApiRoot( new PostApiRootRequest().input(new Input().a(x).b(y).op(o))); return postResult.getResult().getOutput(); } public static void main( String[] args ) { System.out.println( "Simple calc" ); // to begin App calc = new App(); // call the SimpleCalc API Output res = calc.getResultWithPathParameters("1", "2", "-"); System.out.printf("GET /1/2/-: %s\n", res.getC()); // Use the type query parameter res = calc.getResultWithQueryParameters("1", "2", "+"); System.out.printf("GET /?a=1&b=2&op=+: %s\n", res.getC()); // Call POST with an Input body. res = calc.getResultByPostInputBody(1.0, 2.0, "*"); System.out.printf("PUT /\n\n{\"a\":1, \"b\":2,\"op\":\"*\"}\n %s\n", res.getC()); } } ``` En el ejemplo anterior, los ajustes de configuración que se utilizan para crear instancias del cliente SDK tienen una finalidad ilustrativa y no constituyen necesariamente prácticas recomendadas. Además, la llamada a `sdkClient.shutdown()` es opcional, especialmente si necesita un control preciso sobre el momento en que se van a liberar los recursos. Hemos visto los principales patrones para llamar a una API utilizando un SDK de Java. Puede ampliar las instrucciones para llamar a otros métodos de API. # Uso de un SDK de Android generado por API Gateway para una API REST En esta sección, se describen los pasos para utilizar un SDK de Android generado por API Gateway para una API REST. Antes de continuar, debe haber completado los pasos de [Generación de SDK para las API de REST en API Gateway](how-to-generate-sdk.md). **nota** El SDK generado no es compatible con Android 4.4 y versiones anteriores. Para obtener más información, consulte [Notas importantes de Amazon API Gateway](api-gateway-known-issues.md). **Para instalar y utilizar un SDK de Android generado por API Gateway** 1. Extraiga el contenido del archivo .zip generado por API Gateway que ha descargado anteriormente. 1. Descargue e instale [Apache Maven](https://maven.apache.org/) (preferiblemente la versión 3.x). 1. Descargar e instalar [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html). 1. Establezca la variable de entorno `JAVA_HOME`. 1. Ejecute el comando **mvn install** para instalar los archivos de artefactos compilados en el repositorio de Maven local. Se creará una carpeta `target` con la biblioteca del SDK compilada. 1. Copie el archivo de SDK (cuyo nombre se obtiene de los elementos **Artifact Id** (ID de artefacto) y **Artifact Version** (Versión de artefacto) que especificó cuando generó el SDK, p. ej., `simple-calcsdk-1.0.0.jar`) desde la carpeta `target`, junto con todas las demás bibliotecas de la carpeta `target/lib` en la carpeta `lib` del proyecto. Si utiliza Android Studio, cree una carpeta `libs` en el módulo de la aplicación cliente y copie el archivo .jar necesario en esta carpeta. Compruebe que la sección de dependencias del archivo gradle del módulo contiene lo siguiente. ``` compile fileTree(include: ['*.jar'], dir: 'libs') compile fileTree(include: ['*.jar'], dir: 'app/libs') ``` Asegúrese de que no haya archivos .jar declarados duplicados. 1. Utilice la clase `ApiClientFactory` para inicializar el SDK generado por API Gateway. Por ejemplo: ``` ApiClientFactory factory = new ApiClientFactory(); // Create an instance of your SDK. Here, 'SimpleCalcClient.java' is the compiled java class for the SDK generated by API Gateway. final SimpleCalcClient client = factory.build(SimpleCalcClient.class); // Invoke a method: // For the 'GET /?a=1&b=2&op=+' method exposed by the API, you can invoke it by calling the following SDK method: Result output = client.rootGet("1", "2", "+"); // where the Result class of the SDK corresponds to the Result model of the API. // // For the 'GET /{a}/{b}/{op}' method exposed by the API, you can call the following SDK method to invoke the request, Result output = client.aBOpGet(a, b, c); // where a, b, c can be "1", "2", "add", respectively. // For the following API method: // POST / // host: ... // Content-Type: application/json // // { "a": 1, "b": 2, "op": "+" } // you can call invoke it by calling the rootPost method of the SDK as follows: Input body = new Input(); input.a=1; input.b=2; input.op="+"; Result output = client.rootPost(body); // where the Input class of the SDK corresponds to the Input model of the API. // Parse the result: // If the 'Result' object is { "a": 1, "b": 2, "op": "add", "c":3"}, you retrieve the result 'c') as String result=output.c; ``` 1. Para utilizar un proveedor de credenciales de Amazon Cognito para autorizar las llamadas a la API, utilice la clase `ApiClientFactory` para pasar un conjunto de credenciales de AWS mediante el SDK generado por API Gateway, tal y como se muestra en el siguiente ejemplo. ``` // Use CognitoCachingCredentialsProvider to provide AWS credentials // for the ApiClientFactory AWSCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider( context, // activity context "identityPoolId", // Cognito identity pool id Regions.US_EAST_1 // region of Cognito identity pool ); ApiClientFactory factory = new ApiClientFactory() .credentialsProvider(credentialsProvider); ``` 1. Para definir una clave de API mediante el SDK generado por API Gateway, utilice un código similar al siguiente. ``` ApiClientFactory factory = new ApiClientFactory() .apiKey("YOUR_API_KEY"); ``` # Uso de un SDK de JavaScript generado por API Gateway para una API REST En el siguiente procedimiento se muestra cómo crear un SDK de JavaScript generado por API Gateway. **nota** En estas instrucciones se presupone que ya ha completado las instrucciones de [Generación de SDK para las API de REST en API Gateway](how-to-generate-sdk.md). **importante** Si su API solo tiene métodos ANY definidos, el paquete SDK generado no contendrá un archivo `apigClient.js`, por lo que tendrá que definir los métodos ANY usted mismo. **Para instalar, iniciar e invocar un SDK de JavaScript generado por API Gateway para una API REST** 1. Extraiga el contenido del archivo .zip generado por API Gateway que ha descargado anteriormente. 1. Habilite el uso compartido de recursos de origen cruzado (CORS) para todos los métodos a los que llamará el SDK generado por API Gateway. Para obtener instrucciones, consulte [CORS para las API de REST en API Gateway](how-to-cors.md). 1. En la página web, incluya referencias a los siguientes scripts. ``` ``` 1. En el código, inicialice el SDK generado por API Gateway mediante un código similar al siguiente. ``` var apigClient = apigClientFactory.newClient(); ``` Para inicializar el SDK generado por API Gateway con credenciales de AWS, utilice un código similar al siguiente. Si utiliza las credenciales de AWS, todas las solicitudes a la API se firmarán. ``` var apigClient = apigClientFactory.newClient({ accessKey: 'ACCESS_KEY', secretKey: 'SECRET_KEY', }); ``` Para utilizar una clave de API con el SDK generado por API Gateway, pase la clave de API como parámetro al objeto `Factory` utilizando un código similar al siguiente. Si utiliza una clave de API, esta se especifica como parte del encabezado `x-api-key` y todas las solicitudes a la API se firmarán. Esto significa que debe configurar los encabezados Accept de CORS adecuados para cada solicitud. ``` var apigClient = apigClientFactory.newClient({ apiKey: 'API_KEY' }); ``` 1. Llame a los métodos de la API en API Gateway con un código similar al siguiente. Cada llamada devuelve una promesa con devoluciones de llamada de éxito y fracaso. ``` var params = { // This is where any modeled request parameters should be added. // The key is the parameter name, as it is defined in the API in API Gateway. param0: '', param1: '' }; var body = { // This is where you define the body of the request, }; var additionalParams = { // If there are any unmodeled query parameters or headers that must be // sent with the request, add them here. headers: { param0: '', param1: '' }, queryParams: { param0: '', param1: '' } }; apigClient.methodName(params, body, additionalParams) .then(function(result){ // Add success callback code here. }).catch( function(result){ // Add error callback code here. }); ``` Aquí, *methodName* se crea a partir de la ruta y el verbo HTTP del recurso de la solicitud de método. Para la API SimpleCalc, los métodos de SDK para los métodos de la API de ``` 1. GET /?a=...&b=...&op=... 2. POST / { "a": ..., "b": ..., "op": ...} 3. GET /{a}/{b}/{op} ``` los métodos del SDK correspondientes son los siguientes: ``` 1. rootGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the query parameters 2. rootPost(null, body); // where body={"a": ..., "b": ..., "op": ...} 3. aBOpGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the path parameters ``` # Uso de un SDK de Ruby generado por API Gateway para una API REST En el siguiente procedimiento se muestra cómo crear un SDK de Ruby generado por API Gateway. **nota** En estas instrucciones, se presupone que ya se ha completado el procedimiento descrito en [Generación de SDK para las API de REST en API Gateway](how-to-generate-sdk.md). **Para instalar, instanciar e invocar un SDK de Ruby generado por API Gateway para una API REST** 1. Descomprima el archivo descargado del SDK de Ruby. El código fuente del SDK generado es el siguiente. ![\[El archivo descargado del SDK de Ruby se descomprime en un módulo de Ruby\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/ruby-gem-of-generated-sdk-for-simplecalc.png) 1. Cree una gema de Ruby a partir del código fuente del SDK generado. Para ello, utilice los siguientes comandos shell en una ventana del terminal: ``` # change to /simplecalc-sdk directory cd simplecalc-sdk # build the generated gem gem build simplecalc-sdk.gemspec ``` Una vez realizada esta operación, **simplecalc-sdk-1.0.0.gem** pasa a estar disponible. 1. Instale la gema: ``` gem install simplecalc-sdk-1.0.0.gem ``` 1. Cree una aplicación cliente. Instancie e inicialice el cliente del SDK de Ruby en la aplicación: ``` require 'simplecalc-sdk' client = SimpleCalc::Client.new( http_wire_trace: true, retry_limit: 5, http_read_timeout: 50 ) ``` Si la API tiene una autorización de tipo `AWS_IAM`, puede incluir las credenciales de AWS del intermediario suministrando `accessKey` y `secretKey` durante la inicialización: ``` require 'pet-sdk' client = Pet::Client.new( http_wire_trace: true, retry_limit: 5, http_read_timeout: 50, access_key_id: 'ACCESS_KEY', secret_access_key: 'SECRET_KEY' ) ``` 1. Realice llamadas a la API a través del SDK de la aplicación. **sugerencia** Si no está familiarizado con las convenciones de llamada a métodos del SDK, puede consultar el archivo `client.rb` de la carpeta `lib` del SDK generado. La carpeta contiene documentación sobre las llamadas a cada uno de los métodos de API compatibles. Para reconocer las operaciones admitidas: ``` # to show supported operations: puts client.operation_names ``` Esto genera la siguiente llamada, que corresponde a los métodos de la API `GET /?a={.}&b={.}&op={.}`, `GET /{a}/{b}/{op}` y `POST /`, junto con una carga en el formato `{a:"…", b:"…", op:"…"}`, respectivamente: ``` [:get_api_root, :get_ab_op, :post_api_root] ``` Para invocar el método `GET /?a=1&b=2&op=+` de la API, llame al siguiente método del SDK de Ruby: ``` resp = client.get_api_root({a:"1", b:"2", op:"+"}) ``` Para invocar el método `POST /` de la API con una carga `{a: "1", b: "2", "op": "+"}`, llame al siguiente método del SDK de Ruby: ``` resp = client.post_api_root(input: {a:"1", b:"2", op:"+"}) ``` Para invocar al método `GET /1/2/+` de la API, llame al siguiente método del SDK de Ruby: ``` resp = client.get_ab_op({a:"1", b:"2", op:"+"}) ``` Las llamadas al método del SDK que se realizan correctamente devuelven la siguiente respuesta: ``` resp : { result: { input: { a: 1, b: 2, op: "+" }, output: { c: 3 } } } ``` # Uso de un SDK de iOS generado por API Gateway para una API REST en Objective-C o Swift En este tutorial, le mostraremos cómo utilizar un SDK de iOS generado por API Gateway para una API REST en una aplicación Objective-C o Swift para llamar a la API subyacente. Usaremos la [API SimpleCalc](simple-calc-lambda-api.md) como ejemplo para ilustrar los siguientes temas: + Cómo instalar los componentes del SDK para móviles de AWS necesarios en el proyecto Xcode + Cómo crear el objeto de cliente API antes de llamar a los métodos de la API + Cómo llamar a los métodos de la API a través de los métodos del SDK correspondientes en el objeto del cliente API + Cómo preparar una entrada de método y analizar el resultado utilizando las clases del modelo correspondientes del SDK **Topics** + [ ## Usar el SDK de iOS generado (Objective-C) para llamar a una API ](#how-to-use-sdk-ios-objc) + [ ## Usar un SDK de iOS generado (Swift) para llamar a la API ](#how-to-generate-sdk-ios-swift) ## Usar el SDK de iOS generado (Objective-C) para llamar a una API Antes de comenzar el siguiente procedimiento, debe completar los pasos de [Generación de SDK para las API de REST en API Gateway](how-to-generate-sdk.md) para iOS en Objective-C y descargar el archivo .zip del SDK generado. ### Instalar el SDK para móviles de AWS y un SDK de iOS generado por API Gateway en un proyecto Objective-C En el procedimiento siguiente se describe cómo instalar el SDK. **Para instalar y utilizar un SDK de iOS generado por API Gateway en Objective-C** 1. Extraiga el contenido del archivo .zip generado por API Gateway que ha descargado anteriormente. Con la [API SimpleCalc](simple-calc-lambda-api.md), puede cambiar el nombre de la carpeta del SDK descomprimido a algo similar a **sdk\$1objc\$1simple\$1calc**. En esta carpeta del SDK hay un archivo `README.md` y un archivo `Podfile`. El archivo `README.md` contiene las instrucciones para instalar y utilizar el SDK. Este tutorial proporciona información detallada sobre estas instrucciones. La instalación usa [CocoaPods](https://cocoapods.org) para importar las bibliotecas de API Gateway necesarias y otros componentes dependientes del SDK para móviles de AWS. Debe actualizar el archivo `Podfile` para importar los SDK en el proyecto Xcode de su aplicación. La carpeta del SDK descomprimida contiene también una carpeta `generated-src` que incluye el código fuente del SDK generado de la API. 1. Inicie Xcode y cree un nuevo proyecto iOS Objective-C. Anote el destino del proyecto. Lo necesitará para definirlo en el archivo `Podfile`. ![\[Encuentre el objetivo en Xcode.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-find-target.png) 1. Para importar AWS Mobile SDK for iOS en el proyecto Xcode mediante CocoaPods, haga lo siguiente: 1. Instale CocoaPods ejecutando el siguiente comando en una ventana del terminal: ``` sudo gem install cocoapods pod setup ``` 1. Copie el archivo `Podfile` de la carpeta del SDK extraído en el mismo directorio que contiene el archivo del proyecto Xcode. Sustituya el siguiente bloque: ``` target '' do pod 'AWSAPIGateway', '~> 2.4.7' end ``` por el nombre de destino de su proyecto: ``` target 'app_objc_simple_calc' do pod 'AWSAPIGateway', '~> 2.4.7' end ``` Si su proyecto Xcode ya contiene un archivo denominado `Podfile`, añada la siguiente línea de código: ``` pod 'AWSAPIGateway', '~> 2.4.7' ``` 1. Abra una ventana del terminal y ejecute el siguiente comando: ``` pod install ``` Se instalará el componente de API Gateway y otros componentes del SDK para móviles de AWS dependientes. 1. Cierre el proyecto Xcode y, a continuación, abra el archivo `.xcworkspace` para volver a iniciar Xcode. 1. Añada todos los archivos `.h` y `.m` del directorio `generated-src` del SDK extraído al proyecto Xcode. ![\[Los archivos .h y .m están en generated-src\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-add-sdk-src.png) Para importar el AWS Mobile SDK for iOS Objective-C en su proyecto descargando de forma explícita el SDK para móviles de AWS o mediante [Carthage](https://github.com/Carthage/Carthage#installing-carthage), siga las instrucciones del archivo *README.md*. Asegúrese de utilizar únicamente una de estas opciones para importar el SDK para móviles de AWS. ### Llamar a métodos de la API mediante el SDK de iOS generado por API Gateway en un proyecto Objective-C Cuando genera el SDK con el prefijo `SIMPLE_CALC` para esta [API SimpleCalc](simple-calc-lambda-api.md) con dos modelos para la entrada (`Input`) y la salida (`Result`) de los métodos, en el SDK, la clase de cliente de API resultante se convierte en `SIMPLE_CALCSimpleCalcClient` y las clases de datos correspondientes son `SIMPLE_CALCInput` y `SIMPLE_CALCResult`, respectivamente. Las solicitudes y respuestas de la API se asignan a los métodos del SDK de la siguiente manera: + La solicitud de API ``` GET /?a=...&b=...&op=... ``` se convierte en el método del SDK ``` (AWSTask *)rootGet:(NSString *)op a:(NSString *)a b:(NSString *)b ``` La propiedad `AWSTask.result` es del tipo `SIMPLE_CALCResult` si el modelo `Result` se añadió a la respuesta del método. De lo contrario, la propiedad es del tipo `NSDictionary`. + Esta solicitud de API ``` POST / { "a": "Number", "b": "Number", "op": "String" } ``` se convierte en el método del SDK ``` (AWSTask *)rootPost:(SIMPLE_CALCInput *)body ``` + La solicitud de API ``` GET /{a}/{b}/{op} ``` se convierte en el método del SDK ``` (AWSTask *)aBOpGet:(NSString *)a b:(NSString *)b op:(NSString *)op ``` El siguiente procedimiento describe cómo llamar a los métodos de la API en el código fuente de la aplicación Objective-C, por ejemplo, como parte del delegado `viewDidLoad` en un archivo `ViewController.m`. **Para llamar a la API a través del SDK de iOS generado por API Gateway** 1. Importe el archivo de encabezados de clase del cliente API para que la clase del cliente API se pueda llamar en la aplicación: ``` #import "SIMPLE_CALCSimpleCalc.h" ``` La instrucción `#import` también importa `SIMPLE_CALCInput.h` y `SIMPLE_CALCResult.h` para las dos clases de modelo. 1. Cree una instancia de la clase del cliente de API: ``` SIMPLE_CALCSimpleCalcClient *apiInstance = [SIMPLE_CALCSimpleCalcClient defaultClient]; ``` Para utilizar Amazon Cognito con la API, establezca la propiedad `defaultServiceConfiguration` en el objeto `AWSServiceManager` predeterminado, tal y como se muestra a continuación, antes de llamar al método `defaultClient` para crear el objeto del cliente API (mostrado en el ejemplo anterior): ``` AWSCognitoCredentialsProvider *creds = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1 identityPoolId:your_cognito_pool_id]; AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1 credentialsProvider:creds]; AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = configuration; ``` 1. Llame al método `GET /?a=1&b=2&op=+` para ejecutar `1+2`: ``` [[apiInstance rootGet: @"+" a:@"1" b:@"2"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) { _textField1.text = [self handleApiResponse:task]; return nil; }]; ``` donde la función auxiliar `handleApiResponse:task` formatea el resultado como una cadena que se muestra en un campo de texto (`_textField1`). ``` - (NSString *)handleApiResponse:(AWSTask *)task { if (task.error != nil) { return [NSString stringWithFormat: @"Error: %@", task.error.description]; } else if (task.result != nil && [task.result isKindOfClass:[SIMPLE_CALCResult class]]) { return [NSString stringWithFormat:@"%@ %@ %@ = %@\n",task.result.input.a, task.result.input.op, task.result.input.b, task.result.output.c]; } return nil; } ``` El resultado que se muestra es `1 + 2 = 3`. 1. Llame al método `POST /` con una carga para ejecutar `1-2`: ``` SIMPLE_CALCInput *input = [[SIMPLE_CALCInput alloc] init]; input.a = [NSNumber numberWithInt:1]; input.b = [NSNumber numberWithInt:2]; input.op = @"-"; [[apiInstance rootPost:input] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) { _textField2.text = [self handleApiResponse:task]; return nil; }]; ``` El resultado que se muestra es `1 - 2 = -1`. 1. Llame al método `GET /{a}/{b}/{op}` para ejecutar `1/2`: ``` [[apiInstance aBOpGet:@"1" b:@"2" op:@"div"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) { _textField3.text = [self handleApiResponse:task]; return nil; }]; ``` El resultado que se muestra es `1 div 2 = 0.5`. Aquí se usa `div` en lugar de `/` porque la [función de Lambda simple del backend](simple-calc-nodejs-lambda-function.md) no administra variables de ruta codificadas como URL. ## Usar un SDK de iOS generado (Swift) para llamar a la API Antes de comenzar el siguiente procedimiento, debe completar los pasos de [Generación de SDK para las API de REST en API Gateway](how-to-generate-sdk.md) para iOS en Swift y descargar el archivo .zip del SDK generado. **Topics** + [ ### Instalar el SDK para móviles de AWS y el SDK generado por API Gateway en un proyecto Swift ](#use-sdk-ios-swift-install-sdk) + [ ### Llamar a métodos de API a través del SDK de iOS generado por API Gateway en un proyecto Swift ](#use-sdk-ios-swift-call-api) ### Instalar el SDK para móviles de AWS y el SDK generado por API Gateway en un proyecto Swift En el procedimiento siguiente se describe cómo instalar el SDK. **Para instalar y utilizar un SDK de iOS generado por API Gateway en Swift** 1. Extraiga el contenido del archivo .zip generado por API Gateway que ha descargado anteriormente. Con la [API SimpleCalc](simple-calc-lambda-api.md), puede cambiar el nombre de la carpeta del SDK descomprimido a algo similar a **sdk\$1swift\$1simple\$1calc**. En esta carpeta del SDK hay un archivo `README.md` y un archivo `Podfile`. El archivo `README.md` contiene las instrucciones para instalar y utilizar el SDK. Este tutorial proporciona información detallada sobre estas instrucciones. La instalación utiliza [CocoaPods](https://cocoapods.org) para importar los componentes del SDK para móviles de AWS necesarios. Debe actualizar el archivo `Podfile` para importar los SDK en el proyecto Xcode de su aplicación Swift. La carpeta del SDK descomprimida contiene también una carpeta `generated-src` que incluye el código fuente del SDK generado de la API. 1. Inicie Xcode y cree un nuevo proyecto de iOS Swift. Anote el destino del proyecto. Lo necesitará para definirlo en el archivo `Podfile`. ![\[Encuentre el objetivo en Xcode.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-find-target.png) 1. Para importar los componentes del SDK para móviles de AWS necesarios en el proyecto Xcode mediante CocoaPods, haga lo siguiente: 1. Si no está instalado, instale CocoaPods ejecutando el siguiente comando en una ventana del terminal: ``` sudo gem install cocoapods pod setup ``` 1. Copie el archivo `Podfile` de la carpeta del SDK extraído en el mismo directorio que contiene el archivo del proyecto Xcode. Sustituya el siguiente bloque: ``` target '' do pod 'AWSAPIGateway', '~> 2.4.7' end ``` por el nombre de destino de su proyecto, tal y como se muestra a continuación: ``` target 'app_swift_simple_calc' do pod 'AWSAPIGateway', '~> 2.4.7' end ``` Si su proyecto Xcode ya contiene un archivo `Podfile` con el destino correcto, solo tiene que añadir la siguiente línea de código al bucle `do ... end`: ``` pod 'AWSAPIGateway', '~> 2.4.7' ``` 1. Abra una ventana del terminal y ejecute el siguiente comando en el directorio de la aplicación: ``` pod install ``` Se instalará el componente de API Gateway y todos los componentes del SDK para móviles de AWS dependientes en el proyecto de la aplicación. 1. Cierre el proyecto Xcode y, a continuación, abra el archivo `*.xcworkspace` para volver a iniciar Xcode. 1. Añada todos los archivos de encabezado del SDK (`.h`) y los archivos de código fuente de Swift (`.swift`) del directorio `generated-src` extraído a su proyecto Xcode. ![\[Los archivos .h y .swift están en generated-src\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-add-sdk-src.png) 1. Para habilitar las llamadas a las bibliotecas de Objective-C del SDK para móviles de AWS de su proyecto de código Swift, defina la ruta del archivo `Bridging_Header.h` en la propiedad **Objective-C Bridging Header (Encabezado Bridging de Objective-C)** en la opción **Swift Compiler - General (Compilador de Swift: general)** de la configuración de su proyecto Xcode: ![\[Establezca la ruta del archivo Bridging_Header.h en el compilador de Swift: General.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-bridging-header.png) **sugerencia** Puede escribir **bridging** en el cuadro de búsqueda de Xcode para encontrar la propiedad **Objective-C Bridging Header (Encabezado Bridging de Objective-C)**. 1. Compile el proyecto Xcode para verificar que está configurado correctamente antes de continuar. Si su Xcode utiliza una versión más reciente de Swift que la admitida por el SDK para móviles de AWS, recibirá errores del compilador de Swift. En este caso, establezca la propiedad **Use Legacy Swift Language Version (Usar versión del lenguaje Swift antigua)** en **Yes (Sí)** en la opción **Swift Compiler - Version (Compilador de Swift: versión)**: ![\[Establezca la propiedad de versión del lenguaje Swift antigua en Sí.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-legacy-swift-version.png) Para importar el SDK para móviles para iOS de AWS en Swift en su proyecto descargando explícitamente el SDK para móviles de AWS o utilizando [Carthage](https://github.com/Carthage/Carthage#installing-carthage), siga las instrucciones del archivo `README.md` incluido con el paquete del SDK. Asegúrese de utilizar únicamente una de estas opciones para importar el SDK para móviles de AWS. ### Llamar a métodos de API a través del SDK de iOS generado por API Gateway en un proyecto Swift Cuando genera el SDK con el prefijo `SIMPLE_CALC` para esta [API SimpleCalc](simple-calc-lambda-api.md) con dos modelos para describir la entrada (`Input`) y la salida (`Result`) de las solicitudes y las respuestas de la API, en el SDK, la clase de cliente de API resultante se convierte en `SIMPLE_CALCSimpleCalcClient` y las clases de datos correspondientes son `SIMPLE_CALCInput` y `SIMPLE_CALCResult`, respectivamente. Las solicitudes y respuestas de la API se asignan a los métodos del SDK de la siguiente manera: + La solicitud de API ``` GET /?a=...&b=...&op=... ``` se convierte en el método del SDK ``` public func rootGet(op: String?, a: String?, b: String?) -> AWSTask ``` La propiedad `AWSTask.result` es del tipo `SIMPLE_CALCResult` si el modelo `Result` se añadió a la respuesta del método. De lo contrario, es del tipo `NSDictionary`. + Esta solicitud de API ``` POST / { "a": "Number", "b": "Number", "op": "String" } ``` se convierte en el método del SDK ``` public func rootPost(body: SIMPLE_CALCInput) -> AWSTask ``` + La solicitud de API ``` GET /{a}/{b}/{op} ``` se convierte en el método del SDK ``` public func aBOpGet(a: String, b: String, op: String) -> AWSTask ``` El siguiente procedimiento describe cómo llamar a los métodos de la API en el código fuente de la aplicación Swift, por ejemplo, como parte del delegado `viewDidLoad()` en un archivo `ViewController.m`. **Para llamar a la API a través del SDK de iOS generado por API Gateway** 1. Cree una instancia de la clase del cliente de API: ``` let client = SIMPLE_CALCSimpleCalcClient.default() ``` Para utilizar Amazon Cognito con la API, establezca la configuración del servicio de AWS predeterminada (que se muestra a continuación) antes de obtener el método `default` (mostrado anteriormente): ``` let credentialsProvider = AWSCognitoCredentialsProvider(regionType: AWSRegionType.USEast1, identityPoolId: "my_pool_id") let configuration = AWSServiceConfiguration(region: AWSRegionType.USEast1, credentialsProvider: credentialsProvider) AWSServiceManager.defaultServiceManager().defaultServiceConfiguration = configuration ``` 1. Llame al método `GET /?a=1&b=2&op=+` para ejecutar `1+2`: ``` client.rootGet("+", a: "1", b:"2").continueWithBlock {(task: AWSTask) -> AnyObject? in self.showResult(task) return nil } ``` donde la función auxiliar `self.showResult(task)` imprime el resultado o el error en la consola; por ejemplo: ``` func showResult(task: AWSTask) { if let error = task.error { print("Error: \(error)") } else if let result = task.result { if result is SIMPLE_CALCResult { let res = result as! SIMPLE_CALCResult print(String(format:"%@ %@ %@ = %@", res.input!.a!, res.input!.op!, res.input!.b!, res.output!.c!)) } else if result is NSDictionary { let res = result as! NSDictionary print("NSDictionary: \(res)") } } } ``` En una aplicación de producción, puede mostrar el resultado o el error en un campo de texto. El resultado que se muestra es `1 + 2 = 3`. 1. Llame al método `POST /` con una carga para ejecutar `1-2`: ``` let body = SIMPLE_CALCInput() body.a=1 body.b=2 body.op="-" client.rootPost(body).continueWithBlock {(task: AWSTask) -> AnyObject? in self.showResult(task) return nil } ``` El resultado que se muestra es `1 - 2 = -1`. 1. Llame al método `GET /{a}/{b}/{op}` para ejecutar `1/2`: ``` client.aBOpGet("1", b:"2", op:"div").continueWithBlock {(task: AWSTask) -> AnyObject? in self.showResult(task) return nil } ``` El resultado que se muestra es `1 div 2 = 0.5`. Aquí se usa `div` en lugar de `/` porque la [función de Lambda simple del backend](simple-calc-nodejs-lambda-function.md) no administra variables de ruta codificadas como URL. # Desarrollo de API de REST mediante OpenAPI en API Gateway Puede utilizar API Gateway para importar una API REST desde un archivo de definición externo a API Gateway. Actualmente, API Gateway es compatible con los archivos de definición [OpenAPI v2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) y [OpenAPI v3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md), con las excepciones que se indican en [Notas importantes de Amazon API Gateway para las API REST](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis). Puede actualizar una API sobrescribiéndola con una nueva definición o puede combinar una definición con una API existente. Las opciones se especifican utilizando un parámetro de consulta `mode` en la URL de solicitud. Para ver un tutorial sobre el uso de la característica Importar API desde la consola de API Gateway, consulte [Tutorial: Crear una API de REST importando un ejemplo](api-gateway-create-api-from-example.md). **Topics** + [ # Importación de una API optimizada para bordes en API Gateway ](import-edge-optimized-api.md) + [ # Importación de una API regional en API Gateway ](import-export-api-endpoints.md) + [ # Importación de un archivo de OpenAPI para actualizar una definición de la API existente ](api-gateway-import-api-update.md) + [ # Establezca la propiedad `basePath` de OpenAPI ](api-gateway-import-api-basePath.md) + [ # Variables de AWS para la importación de OpenAPI ](import-api-aws-variables.md) + [ # Errores y advertencias al importar la API a API Gateway ](api-gateway-import-api-errors-warnings.md) + [ # Exportación de una API REST desde API Gateway ](api-gateway-export-api.md) # Importación de una API optimizada para bordes en API Gateway Puede importar un archivo de definición de OpenAPI de la API para crear una nueva API optimizada para bordes especificando el tipo de punto de conexión `EDGE` como entrada adicional, además del archivo de OpenAPI, en la operación de importación. Puede hacerlo mediante la consola de API Gateway, la AWS CLI o un SDK de AWS. Para ver un tutorial sobre el uso de la característica Importar API desde la consola de API Gateway, consulte [Tutorial: Crear una API de REST importando un ejemplo](api-gateway-create-api-from-example.md). **Topics** + [ ## Importación de una API optimizada para bordes mediante la consola de API Gateway ](#import-edge-optimized-api-with-console) + [ ## Importación de una API optimizada para bordes a través de la AWS CLI ](#import-edge-optimized-api-with-awscli) ## Importación de una API optimizada para bordes mediante la consola de API Gateway Si desea importar una API optimizada para bordes a través de la consola de API Gateway, haga lo siguiente: 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Seleccione **Crear API**. 1. En **API de REST**, elija **Importar**. 1. Copie una definición de OpenAPI de la API y péguela en el editor de código o elija **Elegir archivo** para cargar un archivo de OpenAPI de una unidad local. 1. En **Tipo de punto de conexión de la API**, seleccione **Optimizado para bordes**. 1. Elija **Crear API** para empezar a importar las definiciones de OpenAPI. ## Importación de una API optimizada para bordes a través de la AWS CLI El siguiente comando [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) permite importar una API desde un archivo de definición de OpenAPI para crear una API optimizada para bordes: ``` aws apigateway import-rest-api \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` También puede establecer explícitamente el parámetro de la cadena de consulta `endpointConfigurationTypes` en `EDGE`: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=EDGE \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importación de una API regional en API Gateway Al importar una API, puede elegir la configuración del punto de conexión regional de la API. Puede utilizar la consola de API Gateway, la AWS CLI o un SDK de AWS. Al exportar una API, la configuración del punto de conexión de la API no se incluye en las definiciones de API exportadas. Para ver un tutorial sobre el uso de la característica Importar API desde la consola de API Gateway, consulte [Tutorial: Crear una API de REST importando un ejemplo](api-gateway-create-api-from-example.md). **Topics** + [ ## Importar una API regional mediante la consola de API Gateway ](#import-regional-api-with-console) + [ ## Importación de una API regional con la AWS CLI ](#import-regional-api-with-awscli) ## Importar una API regional mediante la consola de API Gateway Para importar una API de un punto de conexión regional mediante la consola de API Gateway, haga lo siguiente: 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Seleccione **Crear API**. 1. En **API REST**, elija **Importar**. 1. Copie una definición de OpenAPI de la API y péguela en el editor de código o elija **Elegir archivo** para cargar un archivo de OpenAPI de una unidad local. 1. En **Tipo de punto de conexión de la API**, seleccione **Regional**. 1. Elija **Crear API** para empezar a importar las definiciones de OpenAPI. ## Importación de una API regional con la AWS CLI El siguiente comando [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) importa un archivo de definición de OpenAPI y establece el tipo de punto de conexión en Regional: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=REGIONAL \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importación de un archivo de OpenAPI para actualizar una definición de la API existente Puede importar las definiciones de la API únicamente para actualizar una API existente, sin cambiar la configuración del punto de enlace, así como las etapas y las variables de etapa o referencias a las claves de API. La operación de importar para actualizar puede producirse de dos modos: combinación o sobreescritura. Cuando una API (`A`) se combina con otra (`B`), la API resultante conserva las definiciones de `A` y `B` si las dos API no comparten definiciones contradictorias. Si surge un conflicto, las definiciones de método de la combinación de la API (`A`) invalida las definiciones de método correspondientes de la API combinada (`B`). Suponga, por ejemplo, que `B` ha declarado los siguientes métodos para devolver las respuestas `200` y `206`: ``` GET /a POST /a ``` y `A` declara el siguiente método para devolver las respuestas `200` y `400`: ``` GET /a ``` Cuando `A` se combina con `B`, la API resultante presenta los siguientes métodos: ``` GET /a ``` que devuelve las respuestas `200` y `400`, y ``` POST /a ``` que devuelve las respuestas `200` y `206`. Combinar una API es útil cuando ha descompuesto sus definiciones de API externas en varias partes más pequeñas y solo desea aplicar los cambios de una de esas partes a la vez. Esto podría ocurrir, por ejemplo, si varios equipos son responsables de diferentes partes de una API y han realizado cambios disponibles en diferentes partes. En este modo, los elementos de la API existente que no están específicamente definidos en la definición importada se dejan tal como están. Cuando una API (`A`) sobrescribe otra API (`B`), la API resultante adopta las definiciones de la API sobrescrita (`A`). Sobrescribir una API es útil cuando una definición de API externa contiene la definición completa de una API. En este modo, los elementos de una API existente que no están específicamente definidos en la definición importada se eliminan. Para combinar una API, envíe una solicitud `PUT` a `https://apigateway..amazonaws.com/restapis/?mode=merge`. El valor del parámetro de ruta `restapi_id` especifica la API con la que debe combinarse la definición de API proporcionada. El siguiente fragmento de código muestra un ejemplo de la solicitud `PUT` para combinar una definición de la API de OpenAPI en JSON, como la carga, con la API ya especificada en API Gateway. ``` PUT /restapis/?mode=merge Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` La operación de actualización por combinación toma dos definiciones de API completas y las combina. Para un cambio pequeño e incremental, puede usar la operación [resource update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html). Para sobrescribir una API, envíe una solicitud `PUT` a `https://apigateway..amazonaws.com/restapis/?mode=overwrite`. El parámetro de ruta `restapi_id` especifica la API que se sobrescribirá con las definiciones de API proporcionadas. El siguiente fragmento de código muestra un ejemplo de una solicitud de sobrescritura con la carga de una definición de OpenAPI con formato JSON: ``` PUT /restapis/?mode=overwrite Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` Cuando no se especifica el parámetro de consulta `mode`, se supone que se trata de una combinación. **nota** Las operaciones `PUT` son idempotentes, pero no atómicas. Eso significa que si se produce un error del sistema durante el procesamiento, la API puede acabar en mal estado. Sin embargo, si se repite la operación de forma exitosa, la API acaba en el mismo estado final que tendría si la primera operación se hubiera realizado con éxito. # Establezca la propiedad `basePath` de OpenAPI En [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md), puede utilizar la propiedad `basePath` para proporcionar una o varias partes de la ruta que preceden a cada una de las rutas definidas en la propiedad `paths`. Como API Gateway tiene varias maneras de expresar la ruta de un recurso, la característica Importar API ofrece las siguientes opciones para interpretar la propiedad `basePath` durante una importación: "ignore", "prepend" y "split". En [https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/), `basePath` ya no es una propiedad de nivel superior. En su lugar, API Gateway utiliza una [variable de servidor](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject) como una convención. La característica Import API proporciona las mismas opciones para interpretar la ruta base durante la importación. La ruta base se identifica como se indica a continuación: + Si la API no contiene ninguna variable `basePath`, la característica Import API comprueba la cadena `server.url` para ver si contiene una ruta más allá `"/"`. Si es así, esa ruta se utiliza como la base de la ruta. + Si la API contiene una única variable `basePath`, la característica Import API la utiliza como la ruta base, incluso si no se hace referencia en el `server.url`. + Si la API contiene varias variables `basePath`, la característica Import API utiliza únicamente la primera como la ruta base. ## Ignore Si el archivo de OpenAPI tiene un valor `basePath` de `/a/b/c` y la propiedad `paths` contiene `/e` y `/f`, la siguiente solicitud `POST` o `PUT`: ``` POST /restapis?mode=import&basepath=ignore ``` ``` PUT /restapis/api_id?basepath=ignore ``` produce los siguientes recursos en la API: + `/` + `/e` + `/f` El efecto consiste en tratar `basePath` como si no estuviera presente, y todos los recursos de la API declarados se sirven en relación con el host. Esto puede utilizarse, por ejemplo, cuando disponga de un nombre de dominio personalizado con una asignación de API que no incluya un valor *Base Path* ni *Stage* que haga referencia a la etapa de producción. **nota** API Gateway crea automáticamente un recurso raíz, aunque no se haya declarado explícitamente en el archivo de definición. Cuando no se especifica, `basePath` toma `ignore` como valor predeterminado. ## Anexar Si el archivo de OpenAPI tiene un valor `basePath` de `/a/b/c` y la propiedad `paths` contiene `/e` y `/f`, la siguiente solicitud `POST` o `PUT`: ``` POST /restapis?mode=import&basepath=prepend ``` ``` PUT /restapis/api_id?basepath=prepend ``` produce los siguientes recursos en la API: + `/` + `/a` + `/a/b` + `/a/b/c` + `/a/b/c/e` + `/a/b/c/f` El efecto consiste en tratar `basePath` como si especificara recursos adicionales (sin métodos) y añadiera estos recursos al conjunto de recursos declarados. Esto puede utilizarse, por ejemplo, cuando diferentes equipos sean responsables de diferentes partes de una API y `basePath` pueda hacer referencia a la ubicación de ruta de la parte de la API de cada equipo. **nota** API Gateway crea automáticamente los recursos intermedios, aunque no se hayan declarado explícitamente en la definición. ## Split Si el archivo de OpenAPI tiene un valor `basePath` de `/a/b/c` y la propiedad `paths` contiene `/e` y `/f`, la siguiente solicitud `POST` o `PUT`: ``` POST /restapis?mode=import&basepath=split ``` ``` PUT /restapis/api_id?basepath=split ``` produce los siguientes recursos en la API: + `/` + `/b` + `/b/c` + `/b/c/e` + `/b/c/f` El efecto consiste en tratar la parte de la ruta superior, `/a`, como el principio de la ruta de cada recurso y crear recursos adicionales (sin método) dentro de la propia API. Esto podría usarse, por ejemplo, cuando `a` es un nombre de etapa que desee exponer como parte de la API. # Variables de AWS para la importación de OpenAPI Puede utilizar las siguientes variables de AWS en las definiciones de OpenAPI. API Gateway resuelve las variables cuando se importa la API. Para especificar una variable, utilice `${variable-name}`. En la siguiente tabla se describen las variables de AWS disponibles. | Nombre de variable | Descripción | | --- | --- | | AWS::AccountId | El ID de cuenta de AWS que importa la API. Por ejemplo: 123456789012. | | AWS::Partition | La partición de AWS en la que se importa la API. Para las regiones estándar de AWS, la partición es aws. | | AWS::Region | La región de AWS en la que se importa la API. Por ejemplo, us-east-2. | ## Ejemplo de variables de AWS En el siguiente ejemplo, se utilizan variables de AWS para especificar una función de AWS Lambda para una integración. ------ #### [ OpenAPI 3.0 ] ``` openapi: "3.0.1" info: title: "tasks-api" version: "v1.0" paths: /: get: summary: List tasks description: Returns a list of tasks responses: 200: description: "OK" content: application/json: schema: type: array items: $ref: "#/components/schemas/Task" 500: description: "Internal Server Error" content: {} x-amazon-apigateway-integration: uri: arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations responses: default: statusCode: "200" passthroughBehavior: "when_no_match" httpMethod: "POST" contentHandling: "CONVERT_TO_TEXT" type: "aws_proxy" components: schemas: Task: type: object properties: id: type: integer name: type: string description: type: string ``` ------ # Errores y advertencias al importar la API a API Gateway Al importar el archivo de definición externo a API Gateway, API Gateway puede generar advertencias y errores. En las siguientes secciones se describen los errores y las advertencias que pueden producirse durante la importación. ## Errores durante la importación Durante la importación, se pueden generar errores por problemas graves, como un documento de OpenAPI no válido. Los errores se devuelven como excepciones (por ejemplo, `BadRequestException`) en una respuesta incorrecta. Cuando se produce un error, la nueva definición de la API se descarta y no se realiza ningún cambio en la API existente. ## Advertencias durante la importación Durante la importación, se pueden generar advertencias por problemas menores, como la falta de una referencia del modelo. Si se produce una advertencia, la operación continuará si la expresión de consulta `failonwarnings=false` se añade a la URL de la solicitud. De lo contrario, las actualizaciones se revertirán. De forma predeterminada, `failonwarnings` está establecido en `false`. En estos casos, las advertencias se devuelven como un campo en el recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) resultante. De lo contrario, las advertencias se devuelven como un mensaje en la excepción. # Exportación de una API REST desde API Gateway Una vez que haya creado y configurado una API REST en API Gateway mediante la consola de API Gateway o de otra forma, puede exportarla a un archivo de OpenAPI mediante la característica Exportar API de API Gateway, que forma parte del servicio de control de Amazon API Gateway. Para usar la API de exportación de API Gateway, debe firmar sus solicitudes de API. Para obtener más información sobre la firma de solicitudes, consulte [Firma de solicitudes de AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) en la *Guía del usuario de IAM*. Dispone de opciones para incluir las extensiones de integración de API Gateway, así como las extensiones [Postman](https://www.postman.com), en el archivo de definición de OpenAPI exportado. **nota** Al exportar la API utilizando la AWS CLI, asegúrese de incluir el parámetro de la extensión tal y como se muestra en el siguiente ejemplo, para garantizar que se incluye la extensión `x-amazon-apigateway-request-validator`: ``` aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json ``` No puede exportar una API si sus cargas no son del tipo `application/json`. Si lo intenta, obtendrá una respuesta de error en la que se indica que no se encuentran los modelos del cuerpo JSON. ## Solicitud de exportación de una API de REST Con la API Export, puede exportar una API de REST existente enviando una solicitud GET en la que se especifique la API que se va exportar como parte de las rutas URL. La URL de la solicitud debe tener el siguiente formato: ------ #### [ OpenAPI 3.0 ] ``` https:///restapis//stages//exports/oas30 ``` ------ #### [ OpenAPI 2.0 ] ``` https:///restapis//stages//exports/swagger ``` ------ Puede asociar la cadena de consulta `extensions` para especificar si desea incluir extensiones de API Gateway (con el valor `integration`) o extensiones de Postman (con el valor `postman`). Además, puede establecer el encabezado `Accept` en `application/json` o `application/yaml` para recibir la salida de la definición de la API en formato JSON o YAML, respectivamente. Para obtener más información sobre cómo enviar solicitudes GET utilizando la función Exportar API de API Gateway, consulte [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html). **nota** Si define modelos en la API, deben ser para el tipo de contenido de "application/json" para que API Gateway pueda exportar el modelo. De lo contrario, API Gateway produce una excepción con el mensaje de error "Only found non-JSON body models for ...". Los modelos deben contener propiedades o definirse como un tipo de JSONSchema determinado. ## Descarga de la definición de OpenAPI de la API de REST en JSON Para exportar y descargar una API de REST en definiciones de OpenAPI con formato JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/json ``` ------ Aquí, `` podría ser, por ejemplo, `us-east-1`. Para todas las regiones donde API Gateway está disponible, consulte [Regiones y puntos de conexión](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region). ## Descarga de la definición de OpenAPI de la API de REST en YAML Para exportar y descargar una API de REST en definiciones de OpenAPI con formato YAML: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Descarga de la definición de OpenAPI de la API de REST con extensiones Postman en JSON Para exportar y descargar una API de REST en definiciones de OpenAPI con Postman en formato JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ ## Descarga de la definición de OpenAPI de la API REST con la integración de API Gateway en YAML Para exportar y descargar una API REST en definiciones de OpenAPI con la integración de API Gateway en formato YAML: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Exportar API REST con la consola de API Gateway Después de [implementar la API REST en una etapa](set-up-deployments.md#create-deployment), puede empezar a exportar la API en la etapa a un archivo de OpenAPI mediante la consola de API Gateway. En el panel **Etapas** de la consola de API Gateway, elija **Acciones de etapa**, **Exportar**. ![\[Exportar API REST con la consola de API Gateway\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/export-new-console.png) Especifique un **Tipo de especificación de API**, **Formato** y **Extensiones** para descargar la definición de OpenAPI de la API.