# Desarrollo de las API HTTP en API Gateway En esta sección se proporciona información detallada acerca de las capacidades de API Gateway que necesitará para desarrollar las API de API Gateway. A medida que se desarrolla la API de API Gateway, se decide sobre una serie de características de la API. Estas características dependen del uso de la API. Por ejemplo, es posible que quiera permitir solo a ciertos clientes llamar a la API o puede que quiera que esté disponible para todos. Quizás desee que una llamada a la API ejecute una función de Lambda, haga una consulta a la base de datos o llame a una aplicación. **Topics** + [Creación de una API de HTTP](#http-api-examples) + [Creación de rutas para las API de HTTP en API Gateway](http-api-develop-routes.md) + [Tipos de direcciones IP para las API HTTP en API Gateway](http-api-ip-address-type.md) + [Control y administración del acceso a las API HTTP en API Gateway](http-api-access-control.md) + [Creación de integraciones para las API de HTTP en API Gateway](http-api-develop-integrations.md) + [Configuración de CORS de las API de HTTP en API Gateway](http-api-cors.md) + [Transformación de las solicitudes y respuestas de API para las API HTTP en API Gateway](http-api-parameter-mapping.md) + [Uso de definiciones de OpenAPI para las API HTTP en API Gateway](http-api-open-api.md) ## Creación de una API de HTTP Para crear una API funcional, debe contar al menos con una ruta, una integración, una etapa y una implementación. En los siguientes ejemplos se muestra cómo crear una API con una integración de AWS Lambda o HTTP, una ruta y una etapa predeterminada configurada para implementar automáticamente los cambios. En esta guía, se supone que ya está familiarizado con API Gateway y Lambda. Para obtener una guía más detallada, consulte [Introducción a API Gateway](getting-started.md). **Topics** + [Crear una API HTTP mediante la Consola de administración de AWS](#apigateway-http-api-create.console) + [Crear una API HTTP mediante la AWS CLI](#http-api-examples.cli.quick-create) ### Crear una API HTTP mediante la Consola de administración de AWS 1. Abra la [consola de API Gateway](https://console.aws.amazon.com/apigateway). 1. Seleccione **Create API (Crear API)**. 1. En **HTTP API (API HTTP)**, elija **Build (Compilación)**. 1. Elija **Add integration (Añadir integración)** y, a continuación, elija una función de AWS Lambda o escriba un punto de conexión HTTP. 1. En **Name (Nombre)**, escriba un nombre para la API. 1. Elija **Review and create (Revisar y crear)**. 1. Seleccione **Create (Crear)**. La API ya está lista para su invocación. Puede probar la API escribiendo su URL de invocación en un navegador o con Curl. ``` curl https://api-id.execute-api.us-east-2.amazonaws.com ``` ### Crear una API HTTP mediante la AWS CLI Puede utilizar la creación rápida para crear una API con una integración de Lambda o HTTP, una ruta de método catch-all predeterminada y una etapa predeterminada configurada para implementar automáticamente los cambios. El siguiente comando [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) utiliza la creación rápida para crear una API que se integra con una función de Lambda en el backend. **nota** Para invocar una integración de Lambda, API Gateway debe tener los permisos necesarios. Puede utilizar una política basada en recursos o un rol de IAM para conceder a la API Gateway permisos para invocar una función de Lambda. Para obtener más información, consulte [Permisos de AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html) en la *Guía del desarrollador de AWS Lambda*. **Example** ``` aws apigatewayv2 create-api --name my-api --protocol-type HTTP --target arn:aws:lambda:us-east-2:123456789012:function:function-name ``` La API ya está lista para su invocación. Puede probar la API escribiendo su URL de invocación en un navegador o con Curl. ``` curl https://api-id.execute-api.us-east-2.amazonaws.com ``` # Creación de rutas para las API de HTTP en API Gateway Las rutas dirigen las solicitudes entrantes de la API a los recursos de backend. Las rutas constan de dos partes: un método HTTP y una ruta de recurso, por ejemplo, `GET /pets`. Puede definir métodos HTTP específicos para su ruta. O bien, puede utilizar el método `ANY` para que coincida con todos los métodos que no haya definido para un recurso. Puede crear una ruta `$default` que actúe como método catch-all para las solicitudes que no coincidan con ninguna otra ruta. **nota** API Gateway descodifica los parámetros de solicitud codificados con URL antes de pasarlos a las integraciones de backend. ## Trabajar con variables de ruta Puede utilizar variables de ruta en rutas de API HTTP. Por ejemplo, la ruta `GET /pets/{petID}` captura una solicitud `GET` que un cliente envía a `https://api-id.execute-api.us-east-2.amazonaws.com/pets/6`. Una *variable de ruta ambiciosa* captura todos los recursos secundarios de una ruta. Para crear una variable de ruta ambiciosa, agregue `+` al nombre de la variable, por ejemplo, `{proxy+}`. La variable de ruta expansiva debe estar al final de la ruta del recurso. ## Trabajar con parámetros de cadena de consulta De forma predeterminada, API Gateway envía parámetros de cadena de consulta a su integración de backend si se incluyen en una solicitud a una API HTTP. Por ejemplo, cuando un cliente envía una solicitud a `https://api-id.execute-api.us-east-2.amazonaws.com/pets?id=4&type=dog`, los parámetros de cadena de consulta `?id=4&type=dog` se envían a su integración. ## Trabajar con la ruta `$default` La ruta `$default` captura solicitudes que no coinciden explícitamente con otras rutas en su API. Cuando la ruta `$default` recibe una solicitud, API Gateway envía la ruta de solicitud completa a la integración. Por ejemplo, puede crear una API con solo una ruta `$default` e integrarla en el método `ANY` con el punto de enlace HTTP `https://petstore-demo-endpoint.execute-api.com`. Cuando envía una solicitud a `https://api-id.execute-api.us-east-2.amazonaws.com/store/checkout`, API Gateway envía una solicitud a `https://petstore-demo-endpoint.execute-api.com/store/checkout`. Para obtener más información acerca de las integraciones de HTTP, consulte [Uso de integraciones de proxy de HTTP para las API de HTTP](http-api-develop-integrations-http.md). ## Enrutamiento de solicitudes de la API Cuando un cliente envía una solicitud de la API, API Gateway primero determina hacia qué [etapa](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-stages.html) dirigir la solicitud. Si la solicitud coincide explícitamente con una etapa, API Gateway envía la solicitud a esa etapa. Si ninguna etapa coincide completamente con la solicitud, API Gateway envía la solicitud a la etapa `$default`. Si no hay ninguna etapa `$default`, la API devuelve `{"message":"Not Found"}` y no genera registros de CloudWatch. Después de seleccionar una etapa, API Gateway selecciona una ruta. API Gateway selecciona la ruta con la coincidencia más específica y aplica las siguientes prioridades: 1. Coincidencia completa para una ruta y método. 1. Haga coincidir una ruta y un método con una variable de ruta ambiciosa (`{proxy+}`). 1. La ruta `$default`. Si ninguna ruta coincide con una solicitud, API Gateway devuelve `{"message":"Not Found"}` al cliente. Por ejemplo, piense en una API con una etapa `$default` y las siguientes rutas de ejemplo: 1. `GET /pets/dog/1` 1. `GET /pets/dog/{id}` 1. `GET /pets/{proxy+}` 1. `ANY /{proxy+}` 1. `$default` En la siguiente tabla se resume la forma en que API Gateway enruta las solicitudes a las rutas de ejemplo. | Solicitud | Ruta seleccionada | Explicación | | --- | --- | --- | | `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/1` | `GET /pets/dog/1` | La solicitud coincide completamente con esta ruta estática. | | `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/2` | `GET /pets/dog/{id}` | La solicitud coincide completamente con esta ruta. | | `GET https://api-id.execute-api.region.amazonaws.com/pets/cat/1` | `GET /pets/{proxy+}` | La solicitud no coincide completamente con una ruta. La ruta con un método `GET` y una variable de ruta ambiciosa captura esta solicitud. | | `POST https://api-id.execute-api.region.amazonaws.com/test/5` | `ANY /{proxy+}` | El método `ANY` coincide con todos los métodos que no ha definido para una ruta. Las rutas con variables de ruta ambiciosas tienen mayor prioridad que la ruta `$default`. | # Tipos de direcciones IP para las API HTTP 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. Es posible que desee configurar 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). ## 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 las API HTTP es IPv4. + 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. + 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. ## Cambio del tipo de dirección IP de una API HTTP 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. ------ #### [ Consola de administración de AWS ] **Cambio del tipo de dirección IP de una API 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 HTTP. 1. Para la **configuración de la API**, elija **Editar**. 1. Para tipo de dirección IP, seleccione **IPv4** o **Pila doble**. 1. Seleccione **Save**. El cambio en la configuración de la API se aplicará de forma inmediata. ------ #### [ AWS CLI ] El siguiente comando [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) actualiza una API para que tenga un tipo de dirección IP de pila doble: ``` aws apigatewayv2 update-api \ --api-id abcd1234 \ --ip-address-type dualstack ``` El resultado será similar al siguiente: ``` { "ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com", "ApiId": "abcd1234", "ApiKeySelectionExpression": "$request.header.x-api-key", "CreatedDate": "2025-02-04T22:20:20+00:00", "DisableExecuteApiEndpoint": false, "Name": "My-HTTP-API", "ProtocolType": "HTTP", "RouteSelectionExpression": "$request.method $request.path", "Tags": {}, "NotificationUris": [], "IpAddressType": "dualstack" } ``` ------ # Control y administración del acceso a las API HTTP en API Gateway API Gateway admite varios mecanismos para controlar y administrar el acceso a la API HTTP: + Los **autorizadores de Lambda** utilizan las funciones de Lambda para controlar el acceso a las API. Para obtener más información, consulte [Control del acceso a las API de HTTP con autorizadores de AWS Lambda](http-api-lambda-authorizer.md). + **Los autorizadores de JWT** utilizan tokens web JSON para controlar el acceso a las API. Para obtener más información, consulte [Control del acceso a API HTTP con autorizadores de JWT en API Gateway](http-api-jwt-authorizer.md). + **Los roles y las políticas estándar de AWS IAM** ofrecen controles de acceso flexibles y robustos. 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 las API de HTTP con autorización de IAM en API Gateway](http-api-access-control-iam.md). Para aumentar la seguridad, le recomendamos que configure un autorizador para todas las rutas de su API HTTP. Es probable que deba hacerlo para asegurar el cumplimiento con diversos marcos normativos. Para obtener más información, consulte [Controles de Amazon API Gateway](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) en la *Guía del usuario de AWS Security Hub*. # Control del acceso a las API de HTTP con autorizadores de AWS Lambda El autorizador de Lambda se utiliza para emplear una función de Lambda para controlar el acceso a una API HTTP. Después, cuando un cliente llama a dicha API, API Gateway invoca la función de Lambda. API Gateway utiliza la respuesta de su función de Lambda para determinar si el cliente puede acceder a la API. ## Versión de formato de carga La versión del formato de carga del autorizador especifica el formato de los datos que API Gateway envía a un autorizador de Lambda y cómo API Gateway interpreta la respuesta de Lambda. Si no especifica una versión de formato de carga, la Consola de administración de AWS utiliza la versión más reciente de forma predeterminada. Si crea un autorizador de Lambda mediante la AWS CLI, CloudFormation o un SDK, debe especificar una `authorizerPayloadFormatVersion`. Los valores admitidos son `1.0` y `2.0`. Si necesita compatibilidad con las API de REST, utilice la versión `1.0`. Los siguientes ejemplos muestran la estructura de cada versión de formato de carga. ------ #### [ 2.0 ] ``` { "version": "2.0", "type": "REQUEST", "routeArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request", "identitySource": ["user1", "123"], "routeKey": "$default", "rawPath": "/my/path", "rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value", "cookies": ["cookie1", "cookie2"], "headers": { "header1": "value1", "header2": "value2" }, "queryStringParameters": { "parameter1": "value1,value2", "parameter2": "value" }, "requestContext": { "accountId": "123456789012", "apiId": "api-id", "authentication": { "clientCert": { "clientCertPem": "CERT_CONTENT", "subjectDN": "www.example.com", "issuerDN": "Example issuer", "serialNumber": "1", "validity": { "notBefore": "May 28 12:30:02 2019 GMT", "notAfter": "Aug 5 09:36:04 2021 GMT" } } }, "domainName": "id.execute-api.us-east-1.amazonaws.com", "domainPrefix": "id", "http": { "method": "POST", "path": "/my/path", "protocol": "HTTP/1.1", "sourceIp": "IP", "userAgent": "agent" }, "requestId": "id", "routeKey": "$default", "stage": "$default", "time": "12/Mar/2020:19:03:58 +0000", "timeEpoch": 1583348638390 }, "pathParameters": { "parameter1": "value1" }, "stageVariables": { "stageVariable1": "value1", "stageVariable2": "value2" } } ``` ------ #### [ 1.0 ] ``` { "version": "1.0", "type": "REQUEST", "methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request", "identitySource": "user1,123", "authorizationToken": "user1,123", "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" } } ``` ------ ## Formato de respuesta del autorizador de Lambda La versión del formato de carga también determina la estructura de la respuesta que debe devolver de su función de Lambda. ### Respuesta de función de Lambda para el formato 1.0 Si elige la versión de formato `1.0`, los autorizadores de Lambda deben devolver una política de IAM que permita o deniegue el acceso a su ruta de la API. Puede utilizar la sintaxis de política de IAM estándar en la política. Para obtener algunos ejemplos de políticas de IAM, consulte [Controlar el acceso para invocar una API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). Puede transmitir propiedades de contexto a integraciones o registros de acceso de Lambda mediante `$context.authorizer.property`. El objeto `context` es opcional y `claims` es un marcador de posición reservado y no se puede utilizar como objeto de contexto. Para obtener más información, consulte [Personalización de registros de acceso de las API de HTTP](http-api-logging-variables.md). **Example** **** ``` { "principalId": "abcdef", "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": { "exampleKey": "exampleValue" } } ``` ### Respuesta de función de Lambda para el formato 2.0 Si elige la versión de formato `2.0`, puede devolver un valor booleano o una política de IAM que utilice la sintaxis de la política de IAM estándar de la función de Lambda. Para devolver un valor booleano, habilite respuestas simples para el autorizador. Los siguientes ejemplos muestran el formato que debe utilizar para codificar la devolución de la función de Lambda. El objeto `context` es opcional. Puede transmitir propiedades de contexto a integraciones o registros de acceso de Lambda mediante `$context.authorizer.property`. Para obtener más información, consulte [Personalización de registros de acceso de las API de HTTP](http-api-logging-variables.md). ------ #### [ Simple response ] ``` { "isAuthorized": true/false, "context": { "exampleKey": "exampleValue" } } ``` ------ #### [ IAM policy ] **** ``` { "principalId": "abcdef", "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": { "exampleKey": "exampleValue" } } ``` ------ ## Ejemplo de funciones de autorizador de Lambda El siguiente ejemplo de funciones de Lambda Node.js muestran los formatos de respuesta necesarios que debe devolver desde la función de Lambda para la versión del formato de carga `2.0`. ------ #### [ Simple response - Node.js ] ``` export const handler = async(event) => { let response = { "isAuthorized": false, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": true, "arrayKey": ["value1", "value2"], "mapKey": {"value1": "value2"} } }; if (event.headers.authorization === "secretToken") { console.log("allowed"); response = { "isAuthorized": true, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": true, "arrayKey": ["value1", "value2"], "mapKey": {"value1": "value2"} } }; } return response; }; ``` ------ #### [ Simple response - Python ] ``` import json def lambda_handler(event, context): response = { "isAuthorized": False, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": True, "arrayKey": ["value1", "value2"], "mapKey": {"value1": "value2"} } } try: if (event["headers"]["authorization"] == "secretToken"): response = { "isAuthorized": True, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": True, "arrayKey": ["value1", "value2"], "mapKey": {"value1": "value2"} } } print('allowed') return response else: print('denied') return response except BaseException: print('denied') return response ``` ------ #### [ IAM policy - Node.js ] ``` export const handler = async(event) => { if (event.headers.authorization == "secretToken") { console.log("allowed"); return { "principalId": "abcdef", // The principal user identification associated with the token sent by the client. "policyDocument": { "Version": "2012-10-17", "Statement": [{ "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": event.routeArn }] }, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": true, "arrayKey": ["value1", "value2"], "mapKey": { "value1": "value2" } } }; } else { console.log("denied"); return { "principalId": "abcdef", // The principal user identification associated with the token sent by the client. "policyDocument": { "Version": "2012-10-17", "Statement": [{ "Action": "execute-api:Invoke", "Effect": "Deny", "Resource": event.routeArn }] }, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": true, "arrayKey": ["value1", "value2"], "mapKey": { "value1": "value2" } } }; } }; ``` ------ #### [ IAM policy - Python ] ``` import json def lambda_handler(event, context): response = { # The principal user identification associated with the token sent by # the client. "principalId": "abcdef", "policyDocument": { "Version": "2012-10-17", "Statement": [{ "Action": "execute-api:Invoke", "Effect": "Deny", "Resource": event["routeArn"] }] }, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": True, "arrayKey": ["value1", "value2"], "mapKey": {"value1": "value2"} } } try: if (event["headers"]["authorization"] == "secretToken"): response = { # The principal user identification associated with the token # sent by the client. "principalId": "abcdef", "policyDocument": { "Version": "2012-10-17", "Statement": [{ "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": event["routeArn"] }] }, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": True, "arrayKey": ["value1", "value2"], "mapKey": {"value1": "value2"} } } print('allowed') return response else: print('denied') return response except BaseException: print('denied') return response ``` ------ ## Fuentes de identidad Opcionalmente, puede especificar orígenes de identidad para un autorizador de Lambda. Los orígenes de identidad especifican la ubicación de los datos necesarios para autorizar una solicitud. Por ejemplo, puede especificar valores de cabecera o cadena de consulta como orígenes de identidad. Si especifica orígenes de identidad, los clientes deben incluirlos en la solicitud. Si la solicitud del cliente no incluye los orígenes de identidad, API Gateway no invoca el autorizador de Lambda y el cliente recibe un error `401`. En la siguiente tabla se describen los orígenes de identidad admitidos para un autorizador de Lambda. | **Tipo** | **Ejemplo** | **Notas** | | --- | --- | --- | | Valor del encabezado | \$1request.header.name | Los nombres del encabezado no distinguen entre mayúsculas y minúsculas. | | Valor de la cadena de consulta | \$1request.querystring.name | Los nombres de las cadenas de consulta distinguen mayúsculas y minúsculas. | | Variable de contexto | \$1contexto.variableName | El valor de una [variable de contexto](http-api-logging-variables.md) compatible. | | Variable de etapa | \$1stageVariables.variableName | El valor de una [variable de etapa](http-api-stages.stage-variables.md). | También puede devolver directamente ` {"errorMessage" : "Unauthorized"}` desde la función de Lambda para devolver un error `401` a los clientes. Si devuelve directamente un error `401` desde la función de Lambda a los clientes, no especifique ninguna fuente de identidad al crear el autorizador de Lambda. ## Almacenamiento en caché de las respuestas de los autorizadores Para habilitar el almacenamiento en caché de un autorizador de Lambda debe especificar un [authorizerResultTtlInSeconds](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers.html#apis-apiid-authorizers-prop-createauthorizerinput-authorizerresultttlinseconds). Cuando el almacenamiento en caché está habilitado para un autorizador, API Gateway utiliza los orígenes de identidad del autorizador como clave de caché. Si un cliente especifica los mismos parámetros en orígenes de identidad dentro del TTL configurado, API Gateway utiliza el resultado del autorizador almacenado en caché, en lugar de invocar su función de Lambda. Para habilitar el almacenamiento en caché, el autorizador debe tener al menos un origen de identidad. Si habilita respuestas simples para un autorizador, la respuesta del autorizador permite o deniega completamente todas las solicitudes de la API que coincidan con los valores de origen de identidad almacenados en caché. Para obtener permisos pormenorizados, desactive las respuestas simples y devuelva una política de IAM. En función del autorizador, es posible que la política de IAM necesite controlar el acceso a múltiples. De forma predeterminada, API Gateway utiliza la respuesta del autorizador almacenada en caché para todas las rutas de una API que utiliza el autorizador. Para almacenar en caché las respuestas por ruta, agregue `$context.routeKey` a las fuentes de identidad del autorizador. ## Crear un autorizador de Lambda Al crear un autorizador de Lambda, se especifica la función de Lambda que utilizará API Gateway. Debe conceder permiso de API Gateway para invocar la función de Lambda mediante la política de recursos de la función o un rol de IAM. El siguiente comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) permite crear un autorizador de Lambda: ``` aws apigatewayv2 create-authorizer \ --api-id abcdef123 \ --authorizer-type REQUEST \ --identity-source '$request.header.Authorization' \ --name lambda-authorizer \ --authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-function/invocations' \ --authorizer-payload-format-version '2.0' \ --enable-simple-responses ``` El siguiente comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) permite actualizar la política de recursos de la función de Lambda para conceder a API Gateway permiso para invocar la función. Si API Gateway no tiene permiso para invocar la función, los clientes reciben un `500 Internal Server Error`. ``` aws lambda add-permission \ --function-name my-authorizer-function \ --statement-id apigateway-invoke-permissions-abc123 \ --action lambda:InvokeFunction \ --principal apigateway.amazonaws.com \ --source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/authorizers/authorizer-id" ``` Una vez se haya creado un autorizador y concedido permiso a API Gateway para invocarlo, actualice la ruta para poder utilizarlo. El siguiente comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) permite agregar el autorizador de Lambda a la ruta. Si el autorizador de Lambda utiliza el almacenamiento en caché de la política, asegúrese de actualizar la política para controlar el acceso de la ruta adicional. ``` aws apigatewayv2 update-route \ --api-id abcdef123 \ --route-id abc123 \ --authorization-type CUSTOM \ --authorizer-id def123 ``` ## Resolución de problemas de los autorizadores de Lambda Si API Gateway no puede invocar su autorizador de Lambda, o su autorizador de Lambda devuelve una respuesta en un formato no válido, los clientes recibirán un `500 Internal Server Error`. Para solucionar errores, [habilite el registro de acceso](http-api-logging.md) en la etapa de la API. Incluya la variable de registro `$context.authorizer.error` en su formato de registro. Si los registros indican que API Gateway no tiene permiso para invocar la función, actualice la política de recursos de la función o proporcione un rol de IAM para conceder permiso a API Gateway para invocar el autorizador. Si los registros indican que la función de Lambda devuelve una respuesta no válida, compruebe que la función de Lambda devuelve una respuesta en el [formato requerido](#http-api-lambda-authorizer.payload-format-response). # Control del acceso a API HTTP con autorizadores de JWT en API Gateway Puede utilizar tokens web JSON (JWT) como parte de los marcos [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html) y [OAuth 2.0](https://oauth.net/2/) para restringir el acceso de clientes a las API. Si configura un autorizador de JWT para una ruta de la API, API Gateway valida los JWT que los clientes envían con solicitudes de la API. API Gateway permite o deniega las solicitudes en función de la validación del token y, opcionalmente, de los ámbitos del token. Si configura ámbitos para una ruta, el token debe incluir al menos uno de los ámbitos de la ruta. Puede configurar distintos autorizadores para cada ruta de una API o utilizar el mismo autorizador para varias rutas. **nota** No existe ningún mecanismo estándar para diferenciar los tokens de acceso de JWT de otros tipos de JWT, como los tokens de ID de OpenID Connect. A menos que necesite tokens de ID para la autorización de la API, le recomendamos que configure las rutas para que soliciten los ámbitos de la autorización. También puede configurar los autorizadores de JWT para que soliciten los emisores o los destinatarios que utiliza el proveedor de identidades solo al emitir tokens de acceso de JWT. ## Autorización de solicitudes de API con un autorizador de JWT API Gateway utiliza el siguiente flujo de trabajo general para autorizar solicitudes a rutas configuradas para utilizar un autorizador de JWT. 1. Comprueba si [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource) contiene un token. `identitySource` puede incluir solo el token o el token con el prefijo `Bearer`. 1. Descodifique el token. 1. Compruebe el algoritmo y la firma del token tilizando la clave pública obtenida del del emiso `jwks_uri`. Actualmente solo se admiten algoritmos basados en RSA. API Gateway puede almacenar en caché la clave pública durante dos horas. Al rotar las claves, se recomienda dejar un período de gracia durante el cual tanto la clave antigua como la nueva sean válidas. 1. Valide las reclamaciones. API Gateway evalúa las siguientes reclamaciones de token: + [https://datatracker.ietf.org/doc/html/rfc7517#section-4.5](https://datatracker.ietf.org/doc/html/rfc7517#section-4.5): el token debe tener una reclamación de encabezado que coincida con la clave de `jwks_uri` que firmó el token. + [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1): debe coincidir con el [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) configurado para el autorizador. + [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3) o `client_id`: deben coincidir con una de las entradas de [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) configuradas para el autorizador. API Gateway valida `client_id` solo si `aud` no está presente. Cuando `aud` y `client_id` están presentes, API Gateway evalúa `aud`. + [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4): debe ser posterior a la hora actual en UTC. + [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5): debe ser anterior a la hora actual en UTC. + [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6): debe ser anterior a la hora actual en UTC. + [https://datatracker.ietf.org/doc/html/rfc6749#section-3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) o `scp`: el token debe incluir al menos uno de los ámbitos de los [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes) de la ruta. Si falla alguno de estos pasos, API Gateway deniega la solicitud de la API. Después de validar el JWT, API Gateway transfiere las reclamaciones del token a la integración de la ruta de la API. Los recursos de backend, como las funciones de Lambda, pueden acceder a las reclamaciones de JWT. Por ejemplo, si el JWT incluye una reclamación de identidad `emailID`, esta estará disponible para una integración de Lambda en `$event.requestContext.authorizer.jwt.claims.emailID`. Para obtener más información acerca de la carga que API Gateway envía a las integraciones de Lambda, consulte [Creación de integraciones de proxy de AWS Lambda para las API de HTTP en API Gateway](http-api-develop-integrations-lambda.md). ## Crear un autorizador de JWT Antes de crear un autorizador de JWT, debe registrar una aplicación cliente con un proveedor de identidad. También debe haber creado una API HTTP. Para obtener ejemplos de creación de una API HTTP, consulte [Creación de una API de HTTP](http-api-develop.md#http-api-examples). ### Creación de un autorizador de JWT a través de la consola Los siguientes pasos muestran cómo crear un autorizador de JWT mediante la consola. **Creación de un autorizador de JWT a través de la consola** 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 HTTP. 1. En el panel de navegación principal, elija **Autorización**. 1. Elija la pestaña **Administrar autorizadores**. 1. Seleccione **Crear**. 1. Para **Tipo de autorizador**, elija **JWT**. 1. Configure el autorizador de JWT y especifique un **Origen de identidad** que defina el origen del token. 1. Seleccione **Crear**. #### Creación de un autorizador de JWT con la AWS CLI El siguiente comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) crea un autorizador de JWT. Para `jwt-configuration`, especifique la `Audience` y el `Issuer` del proveedor de identidades. Si utiliza Amazon Cognito como proveedor de identidades, `IssuerUrl` es `https://cognito-idp.us-east-2.amazonaws.com/userPoolID`. ``` aws apigatewayv2 create-authorizer \ --name authorizer-name \ --api-id api-id \ --authorizer-type JWT \ --identity-source '$request.header.Authorization' \ --jwt-configuration Audience=audience,Issuer=IssuerUrl ``` ##### Creación de un autorizador de JWT a través de AWS CloudFormation La siguiente plantilla de CloudFormation crea una API HTTP con un autorizador de JWT que usa Amazon Cognito como proveedor de identidades. El resultado de la plantilla de CloudFormation es una URL de una interfaz de usuario alojada de Amazon Cognito en la que los clientes pueden registrarse e iniciar sesión para recibir un JWT. Cuando un cliente inicia sesión, se le redirige a la API HTTP con un token de acceso en la URL. Para invocar la API con el token de acceso, cambie `#` en la URL por `?` para usar el token como un parámetro de cadena de consulta. ##### Plantilla de CloudFormation de ejemplo ``` AWSTemplateFormatVersion: '2010-09-09' Description: | Example HTTP API with a JWT authorizer. This template includes an Amazon Cognito user pool as the issuer for the JWT authorizer and an Amazon Cognito app client as the audience for the authorizer. The outputs include a URL for an Amazon Cognito hosted UI where clients can sign up and sign in to receive a JWT. After a client signs in, the client is redirected to your HTTP API with an access token in the URL. To invoke the API with the access token, change the '#' in the URL to a '?' to use the token as a query string parameter. Resources: MyAPI: Type: AWS::ApiGatewayV2::Api Properties: Description: Example HTTP API Name: api-with-auth ProtocolType: HTTP Target: !GetAtt MyLambdaFunction.Arn DefaultRouteOverrides: Type: AWS::ApiGatewayV2::ApiGatewayManagedOverrides Properties: ApiId: !Ref MyAPI Route: AuthorizationType: JWT AuthorizerId: !Ref JWTAuthorizer JWTAuthorizer: Type: AWS::ApiGatewayV2::Authorizer Properties: ApiId: !Ref MyAPI AuthorizerType: JWT IdentitySource: - '$request.querystring.access_token' JwtConfiguration: Audience: - !Ref AppClient Issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool} Name: test-jwt-authorizer MyLambdaFunction: Type: AWS::Lambda::Function Properties: Runtime: nodejs18.x Role: !GetAtt FunctionExecutionRole.Arn Handler: index.handler Code: ZipFile: | exports.handler = async (event) => { const response = { statusCode: 200, body: JSON.stringify('Hello from the ' + event.routeKey + ' route!'), }; return response; }; APIInvokeLambdaPermission: Type: AWS::Lambda::Permission Properties: FunctionName: !Ref MyLambdaFunction Action: lambda:InvokeFunction Principal: apigateway.amazonaws.com SourceArn: !Sub arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:${MyAPI}/$default/$default FunctionExecutionRole: Type: AWS::IAM::Role Properties: AssumeRolePolicyDocument: Version: '2012-10-17 ' Statement: - Effect: Allow Principal: Service: - lambda.amazonaws.com Action: - 'sts:AssumeRole' ManagedPolicyArns: - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole UserPool: Type: AWS::Cognito::UserPool Properties: UserPoolName: http-api-user-pool AutoVerifiedAttributes: - email Schema: - Name: name AttributeDataType: String Mutable: true Required: true - Name: email AttributeDataType: String Mutable: false Required: true AppClient: Type: AWS::Cognito::UserPoolClient Properties: AllowedOAuthFlows: - implicit AllowedOAuthScopes: - aws.cognito.signin.user.admin - email - openid - profile AllowedOAuthFlowsUserPoolClient: true ClientName: api-app-client CallbackURLs: - !Sub https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com ExplicitAuthFlows: - ALLOW_USER_PASSWORD_AUTH - ALLOW_REFRESH_TOKEN_AUTH UserPoolId: !Ref UserPool SupportedIdentityProviders: - COGNITO HostedUI: Type: AWS::Cognito::UserPoolDomain Properties: Domain: !Join - '-' - - !Ref MyAPI - !Ref AppClient UserPoolId: !Ref UserPool Outputs: SignupURL: Value: !Sub https://${HostedUI}.auth.${AWS::Region}.amazoncognito.com/login?client_id=${AppClient}&response_type=token&scope=email+profile&redirect_uri=https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com ``` ## Actualización de una ruta para utilizar un autorizador de JWT Puede usar la consola, la AWS CLI, o un AWS SDK para actualizar una ruta y usar un autorizador de JWT. ### Actualización de una ruta para utilizar un autorizador de JWT a través de la consola Los siguientes pasos muestran cómo actualizar una ruta para usar un autorizador de JWT mediante la consola. **Creación de un autorizador de JWT a través de la consola** 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 HTTP. 1. En el panel de navegación principal, elija **Autorización**. 1. Elija un método y, a continuación, seleccione el autorizador del menú desplegable y elija **Asociar autorizador**. #### Actualización de una ruta para utilizar un autorizador de JWT a través de la AWS CLI El siguiente comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) actualiza una ruta para que utilice un autorizador de JWT. ``` aws apigatewayv2 update-route \ --api-id api-id \ --route-id route-id \ --authorization-type JWT \ --authorizer-id authorizer-id \ --authorization-scopes user.email ``` # Control del acceso a las API de HTTP con autorización de IAM en API Gateway Puede habilitar la autorización de IAM para rutas de API HTTP. Cuando la autorización de IAM está habilitada, los clientes deben utilizar [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) para firmar las solicitudes con credenciales de AWS. API Gateway invoca la ruta de su API solo si el cliente dispone del permiso `execute-api` para la ruta. La autorización de IAM para las API HTTP es similar a la de las [API de REST](api-gateway-control-access-using-iam-policies-to-invoke-api.md). **nota** Actualmente, las políticas de recursos no se admiten para las API HTTP. Para obtener ejemplos de políticas de IAM que otorgan a los clientes el permiso para invocar las API, consulte [Controlar el acceso para invocar una API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). ## Habilitación de la autorización de IAM para una ruta El siguiente comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) habilita la autorización de IAM para una ruta de API HTTP. ``` aws apigatewayv2 update-route \ --api-id abc123 \ --route-id abcdef \ --authorization-type AWS_IAM ``` # Creación de integraciones para las API de HTTP en API Gateway Las *integraciones* conectan una ruta a los recursos de backend. Las API HTTP admiten integraciones de proxy de Lambda, servicio de AWS y proxy de HTTP. Por ejemplo, puede configurar una solicitud `POST` para la ruta `/signup` de la API para que se integre con una función de Lambda que se encarga del registro de clientes. **Topics** + [Creación de integraciones de proxy de AWS Lambda para las API de HTTP en API Gateway](http-api-develop-integrations-lambda.md) + [Uso de integraciones de proxy de HTTP para las API de HTTP](http-api-develop-integrations-http.md) + [Creación de integraciones de servicio de AWS para las API de HTTP en API Gateway](http-api-develop-integrations-aws-services.md) + [Creación de integraciones privadas para API HTTP en API Gateway](http-api-develop-integrations-private.md) # Creación de integraciones de proxy de AWS Lambda para las API de HTTP en API Gateway Una integración de proxy de Lambda le permite integrar una ruta de API con una función de Lambda. Cuando un cliente llama a la API, API Gateway envía la solicitud a la función de Lambda y devuelve la respuesta de la función al cliente. Para obtener ejemplos de creación de una API HTTP, consulte [Creación de una API de HTTP](http-api-develop.md#http-api-examples). ## Versión de formato de carga La versión del formato de carga especifica el formato del evento que API Gateway envía a una integración de Lambda y cómo API Gateway interpreta la respuesta de Lambda. Si no especifica una versión de formato de carga, la Consola de administración de AWS utiliza la versión más reciente de forma predeterminada. Si crea una integración de Lambda utilizando la AWS CLI, CloudFormation o un SDK, debe especificar una `payloadFormatVersion`. Los valores admitidos son `1.0` y `2.0`. Para obtener más información sobre cómo establecer `payloadFormatVersion`, consulte [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html). Para obtener más información sobre cómo determinar la `payloadFormatVersion` de una integración existente, consulte [get-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-integration.html). ### Diferencias de formato de carga En la siguiente lista, se muestran las diferencias entre las versiones del formato de carga `1.0` y `2.0`: + El formato `2.0` no tiene campos `multiValueHeaders` o `multiValueQueryStringParameters`. Los encabezados duplicados se combinan con comas y se incluyen en el campo `headers`. Las cadenas de consulta duplicadas se combinan con comas y se incluyen en el campo `queryStringParameters`. + El formato `2.0` tiene `rawPath`. Si utiliza una asignación de API para conectar su escenario a un nombre de dominio personalizado, `rawPath` no proporcionará el valor de asignación de la API. Use el formato `1.0` y `path` para acceder a la asignación de la API para su nombre de dominio personalizado. + El formato `2.0` incluye un nuevo campo `cookies`. Todos los encabezados de cookies en la solicitud se combinan con comas y se agregan al campo `cookies`. En la respuesta al cliente, cada cookie se convierte en un encabezado `set-cookie`. ### Estructura de formato de carga Los siguientes ejemplos muestran la estructura de cada versión de formato de carga. Todos los nombres de encabezado están en minúsculas. ------ #### [ 2.0 ] ``` { "version": "2.0", "routeKey": "$default", "rawPath": "/my/path", "rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value", "cookies": [ "cookie1", "cookie2" ], "headers": { "header1": "value1", "header2": "value1,value2" }, "queryStringParameters": { "parameter1": "value1,value2", "parameter2": "value" }, "requestContext": { "accountId": "123456789012", "apiId": "api-id", "authentication": { "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" } } }, "authorizer": { "jwt": { "claims": { "claim1": "value1", "claim2": "value2" }, "scopes": [ "scope1", "scope2" ] } }, "domainName": "id.execute-api.us-east-1.amazonaws.com", "domainPrefix": "id", "http": { "method": "POST", "path": "/my/path", "protocol": "HTTP/1.1", "sourceIp": "192.0.2.1", "userAgent": "agent" }, "requestId": "id", "routeKey": "$default", "stage": "$default", "time": "12/Mar/2020:19:03:58 +0000", "timeEpoch": 1583348638390 }, "body": "Hello from Lambda", "pathParameters": { "parameter1": "value1" }, "isBase64Encoded": false, "stageVariables": { "stageVariable1": "value1", "stageVariable2": "value2" } } ``` ------ #### [ 1.0 ] ``` { "version": "1.0", "resource": "/my/path", "path": "/my/path", "httpMethod": "GET", "headers": { "header1": "value1", "header2": "value2" }, "multiValueHeaders": { "header1": [ "value1" ], "header2": [ "value1", "value2" ] }, "queryStringParameters": { "parameter1": "value1", "parameter2": "value" }, "multiValueQueryStringParameters": { "parameter1": [ "value1", "value2" ], "parameter2": [ "value" ] }, "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": "192.0.2.1", "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 } ``` ------ ## Formato de respuesta de función de Lambda La versión del formato de carga determina la estructura de la respuesta que debe devolver su función de Lambda. ### Respuesta de función de Lambda para el formato 1.0 Con la versión de formato `1.0`, las integraciones de Lambda deben devolver una respuesta en el siguiente formato JSON: **Example** ``` { "isBase64Encoded": true|false, "statusCode": httpStatusCode, "headers": { "headername": "headervalue", ... }, "multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... }, "body": "..." } ``` ### Respuesta de función de Lambda para el formato 2.0 Con la versión de formato `2.0`, API Gateway puede inferir el formato de respuesta por usted. API Gateway hace las siguientes suposiciones si su función de Lambda devuelve JSON válido y no devuelve un `statusCode`: + `isBase64Encoded` es `false`. + `statusCode` es `200`. + `content-type` es `application/json`. + `body` es la respuesta de la función. Los siguientes ejemplos muestran el resultado de una función de Lambda y la interpretación de API Gateway. | Salida de función de Lambda | Interpretación de API Gateway | | --- | --- | | 
"Hello from Lambda!"
| 
{
  "isBase64Encoded": false,
  "statusCode": 200,
  "body": "Hello from Lambda!",
  "headers": {
    "content-type": "application/json"
  }
}
| | 
{ "message": "Hello from Lambda!" }
| 
{
  "isBase64Encoded": false,
  "statusCode": 200,
  "body": "{ \"message\": \"Hello from Lambda!\" }",
  "headers": {
    "content-type": "application/json"
  }
}
| Para personalizar la respuesta, su función de Lambda debe devolver una respuesta con el siguiente formato. ``` { "cookies" : ["cookie1", "cookie2"], "isBase64Encoded": true|false, "statusCode": httpStatusCode, "headers": { "headername": "headervalue", ... }, "body": "Hello from Lambda!" } ``` # Uso de integraciones de proxy de HTTP para las API de HTTP Una integración de proxy HTTP le permite conectar una ruta de API a un punto de enlace HTTP enrutable públicamente. Con este tipo de integración, API Gateway pasa toda la solicitud y respuesta entre el frontend y el backend. Para crear una integración de proxy HTTP, proporcione la dirección URL de un punto de enlace HTTP direccionable públicamente. ## Integración de proxy HTTP con variables de ruta Puede utilizar variables de ruta en rutas de API HTTP. Por ejemplo, la ruta `/pets/{petID}` captura solicitudes a `/pets/6`. Puede hacer referencia a variables de ruta en el URI de integración para enviar el contenido de la variable a una integración. Un ejemplo es: `/pets/extendedpath/{petID}`. Puede usar variables de ruta ambiciosas para capturar todos los recursos secundarios de una ruta. Para crear una variable de ruta ambiciosa, agregue `+` al nombre de la variable, por ejemplo, `{proxy+}`. Para configurar una ruta con una integración de proxy HTTP que capte todas las solicitudes, cree una ruta API con una variable de ruta ambiciosa (por ejemplo, `/parent/{proxy+}`). Integre la ruta con un punto de enlace HTTP (por ejemplo, `https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}`) en el método `ANY`. La variable de ruta expansiva debe estar al final de la ruta del recurso. # Creación de integraciones de servicio de AWS para las API de HTTP en API Gateway Puede integrar su API HTTP en los servicios de AWS usando *integraciones de primera clase*. La integración de primera clase conecta una ruta de API HTTP a una API de servicio de AWS. Cuando un cliente invoca una ruta respaldada por una integración de primera clase, API Gateway invoca una API de servicio de AWS por usted. Por ejemplo, puede utilizar integraciones de primera clase para enviar un mensaje a una cola de Amazon Simple Queue Service o para iniciar una máquina de estado de AWS Step Functions. Para ver las acciones de servicio compatibles, consulte [Referencia del subtipo de integración](http-api-develop-integrations-aws-services-reference.md). ## Asignar parámetros de solicitud Las integraciones de primera clase tienen parámetros obligatorios y opcionales. Debe configurar todos los parámetros que son obligatorios para crear una integración. Puede utilizar valores estáticos o parámetros de asignación que se evalúan dinámicamente en el tiempo de ejecución. Para obtener una lista completa de las integraciones y parámetros admitidos, consulte [Referencia del subtipo de integración](http-api-develop-integrations-aws-services-reference.md). En la siguiente tabla, se describen los parámetros de solicitud de asignación admitidos. | Tipo | Ejemplo | Notas | | --- | --- | --- | | Valor del encabezado | \$1request.header.name | Los nombres del encabezado no distinguen entre mayúsculas y minúsculas. API Gateway combina varios valores de encabezado con comas, por ejemplo, "header1": "value1,value2". | | Valor de la cadena de consulta | \$1request.querystring.name | Los nombres de las cadenas de consulta distinguen mayúsculas y minúsculas. API Gateway combina varios valores con comas, por ejemplo, "querystring1": "Value1,Value2". | | Parámetro de ruta | \$1request.path.name | El valor de un parámetro de ruta en la solicitud. Por ejemplo, si la ruta es /pets/\$1petId\$1, puede asignar el parámetro petId de la solicitud con \$1request.path.petId. | | Solicitar acceso directo del cuerpo | \$1request.body | API Gateway transfiere todo el cuerpo de la solicitud directamente. | | Cuerpo de la solicitud | \$1request.body.name | Una [expresión de ruta de acceso JSON](https://goessner.net/articles/JsonPath/index.html#e2). El descenso recursivo (\$1request.body..name) y las expresiones de filtro (?(expression)) no son compatibles. Cuando se especifica una ruta JSON, API Gateway trunca el cuerpo de la solicitud en 100 KB y, a continuación, aplica la expresión de selección. Para enviar cargas de más de 100 KB, especifique `$request.body`. | | Variable de contexto | \$1contexto.variableName | El valor de una [variable de contexto](http-api-logging-variables.md) compatible. | | Variable de etapa | \$1stageVariables.variableName | El valor de una [variable de etapa](http-api-stages.stage-variables.md). | | Valor estático | string | Un valor constante. | ## Crear una integración de primera clase Antes de crear una integración de primera clase, debe crear un rol de IAM que conceda a API Gateway permisos para invocar la acción de servicio de AWS en la que se está integrando. Para obtener más información, consulte [Creación de un rol para un servicio de AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html). Para crear una integración de primera clase, elija una acción de servicio de AWS admitido, como `SQS-SendMessage`, configure los parámetros de la solicitud y proporcione un rol que conceda a API Gateway permisos para invocar la API de servicio de AWS integrada. Dependiendo del subtipo de integración, se requieren diferentes parámetros de solicitud. Para obtener más información, consulte [Referencia del subtipo de integración](http-api-develop-integrations-aws-services-reference.md). El siguiente comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) permite crear una integración que envía un mensaje de Amazon SQS. ``` aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-subtype SQS-SendMessage \ --integration-type AWS_PROXY \ --payload-format-version 1.0 \ --credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \ --request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}' ``` ## Creación de una integración de primera clase con CloudFormation El siguiente ejemplo muestra un fragmento de CloudFormation que crea una ruta de `/{source}/{detailType}` con una integración de primera clase con Amazon EventBridge. El parámetro `Source` se asigna al parámetro de ruta `{source}`, el `DetailType` se asigna al parámetro de ruta `{DetailType}` y el parámetro `Detail` se asigna al cuerpo de la solicitud. El fragmento no muestra el bus de eventos ni el rol de IAM que otorga permisos a API Gateway para invocar la acción `PutEvents`. ``` Route: Type: AWS::ApiGatewayV2::Route Properties: ApiId: !Ref HttpApi AuthorizationType: None RouteKey: 'POST /{source}/{detailType}' Target: !Join - / - - integrations - !Ref Integration Integration: Type: AWS::ApiGatewayV2::Integration Properties: ApiId: !Ref HttpApi IntegrationType: AWS_PROXY IntegrationSubtype: EventBridge-PutEvents CredentialsArn: !GetAtt EventBridgeRole.Arn RequestParameters: Source: $request.path.source DetailType: $request.path.detailType Detail: $request.body EventBusName: !GetAtt EventBus.Arn PayloadFormatVersion: "1.0" ``` # Referencia del subtipo de integración Los siguientes [subtipos de integración](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationsubtype) son compatibles con las API HTTP. **Topics** + [EventBridge-PutEvents 1.0](#EventBridge-PutEvents) + [SQS-SendMessage 1.0](#SQS-SendMessage) + [SQS-ReceiveMessage 1.0](#SQS-ReceiveMessage) + [SQS-DeleteMessage 1.0](#SQS-DeleteMessage) + [SQS-PurgeQueue 1.0](#SQS-PurgeQueue) + [AppConfig-GetConfiguration 1.0](#AppConfig-GetConfiguration) + [Kinesis-PutRecord 1.0](#Kinesis-PutRecord) + [StepFunctions-StartExecution 1.0](#StepFunctions-StartExecution) + [StepFunctions: StartSyncExecution 1.0](#StepFunctions-StartSyncExecution) + [StepFunctions-StopExecution 1.0](#StepFunctions-StopExecution) ## EventBridge-PutEvents 1.0 Envía eventos personalizados a Amazon EventBridge para que puedan ajustarse a las reglas. | Parámetro | Obligatorio | | --- | --- | | Detalle | True | | DetailType | True | | Fuente | True | | Time | Falso | | EventBusName | Falso | | Recursos | Falso | | Región | Falso | | TraceHeader | Falso | Para obtener más información, consulte [PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html) en la *Referencia de la API de Amazon EventBridge*. ## SQS-SendMessage 1.0 Entrega un mensaje a la cola especificada. | Parámetro | Obligatorio | | --- | --- | | QueueUrl | True | | MessageBody | True | | DelaySeconds | Falso | | MessageAttributes | Falso | | MessageDeduplicationId | Falso | | MessageGroupId | Falso | | MessageSystemAttributes | Falso | | Región | Falso | Para obtener más información, consulte [SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) en la *Referencia de la API de Amazon Simple Queue Service*. ## SQS-ReceiveMessage 1.0 Recupera uno o varios mensajes (hasta 10) de la cola especificada. | Parámetro | Obligatorio | | --- | --- | | QueueUrl | True | | AttributeNames | Falso | | MaxNumberOfMessages | Falso | | MessageAttributeNames | Falso | | ReceiveRequestAttemptId | Falso | | VisibilityTimeout | Falso | | WaitTimeSeconds | Falso | | Región | Falso | Para obtener más información, consulte [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) en la *Referencia de la API de Amazon Simple Queue Service*. ## SQS-DeleteMessage 1.0 Elimina el mensaje especificado de la cola especificada. | Parámetro | Obligatorio | | --- | --- | | ReceiptHandle | True | | QueueUrl | True | | Región | Falso | Para obtener más información, consulte [DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html) en la *Referencia de la API de Amazon Simple Queue Service*. ## SQS-PurgeQueue 1.0 Elimina todos los mensajes de la cola especificada. | Parámetro | Obligatorio | | --- | --- | | QueueUrl | True | | Región | Falso | Para obtener más información, consulte [PurgeQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_PurgeQueue.html) en la *Referencia de la API de Amazon Simple Queue Service*. ## AppConfig-GetConfiguration 1.0 Recibe información acerca de una configuración. | Parámetro | Obligatorio | | --- | --- | | Aplicación | True | | Entorno | True | | Configuración | True | | ClientId | True | | ClientConfigurationVersion | Falso | | Región | Falso | Para obtener más información, consulte [GetConfiguration](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html) en la *Referencia de la API de AWS AppConfig*. ## Kinesis-PutRecord 1.0 Escribe un único registro de datos en un flujo de datos de Amazon Kinesis. | Parámetro | Obligatorio | | --- | --- | | StreamName | True | | Datos | True | | PartitionKey | True | | SequenceNumberForOrdering | Falso | | ExplicitHashKey | Falso | | Región | Falso | Para obtener más información, consulte [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html) en la *Referencia de la API de Amazon Kinesis Data Streams*. ## StepFunctions-StartExecution 1.0 Comienza la ejecución de la máquina de estado. | Parámetro | Obligatorio | | --- | --- | | StateMachineArn | True | | Nombre | Falso | | Input | Falso | | Región | Falso | Para obtener más información, consulte [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) en la *Referencia de la API de AWS Step Functions*. ## StepFunctions: StartSyncExecution 1.0 Comienza la ejecución de la máquina de estado sincrónico. | Parámetro | Obligatorio | | --- | --- | | StateMachineArn | True | | Nombre | Falso | | Input | Falso | | Región | Falso | | TraceHeader | Falso | Para obtener más información, consulte [StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html) en la *Referencia de la API de AWS Step Functions*. ## StepFunctions-StopExecution 1.0 Detiene una ejecución. | Parámetro | Obligatorio | | --- | --- | | ExecutionArn | True | | Causa | Falso | | Error | Falso | | Región | Falso | Para obtener más información, consulte [StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html) en la *Referencia de la API de AWS Step Functions*. # Creación de integraciones privadas para API HTTP en API Gateway Las integraciones privadas le permiten crear integraciones de API con recursos privados en una VPC, como equilibradores de carga de aplicaciones o aplicaciones basadas en contenedores de Amazon ECS. Puede exponer sus recursos en una VPC para que los clientes de fuera de la VPC tengan acceso mediante integraciones privadas. Puede controlar el acceso a la API mediante cualquiera de los [ métodos de autorización](http-api-access-control.md) admitidos por API Gateway. **nota** Para crear una integración privada, primero debe crear un enlace de la VPC. Los enlaces de VPC V2 ahora son compatibles con las API HTTP y de REST. Para obtener más información acerca de los enlaces de VPC V2, consulte [Configuración de enlaces de VPC V2 en API Gateway](apigateway-vpc-links-v2.md). Después de crear un enlace de VPC V2, puede configurar integraciones privadas que se conecten al equilibrador de carga de aplicación, a un equilibrador de carga de red o a recursos registrados con un servicio de AWS Cloud Map. ## 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 o el servicio de AWS Cloud Map, el enlace de VPC y la API HTTP. + De forma predeterminada, el tráfico de integración privada utiliza el protocolo HTTP. Para usar HTTPS, especifique una [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html). Para elloConsola de administración de AWS, mediante la , al crear la integración privada, elija **Configuración avanzada** y, a continuación, indique un nombre de servidor seguro. + En el caso de las integraciones privadas, API Gateway incluye la parte de [etapa](http-api-stages.md) del punto de conexión de la API en la solicitud a sus recursos de backend. Por ejemplo, una solicitud a la etapa `test` de una API incluye `test/route-path` en la solicitud a su integración privada. Para eliminar el nombre de etapa de la solicitud a los recursos de backend, utilice [Asignación de parámetros](http-api-parameter-mapping.md) para sobrescribir la ruta de solicitud en `$request.path`. ## Creación de una integración privada mediante un equilibrador de carga de aplicación o un equilibrador de carga de red Antes de crear una integración privada, debe crear un enlace de VPC V2. Para obtener más información acerca de los enlaces de VPC V2, consulte [Configuración de enlaces de VPC V2 en API Gateway](apigateway-vpc-links-v2.md). 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 la VPC que se va a utilizar y proporcione el ARN del agente de escucha del equilibrador de carga. El siguiente comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) permite crear una integración privada que se conecte a un equilibrador de carga mediante un enlace de la VPC. ``` aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \ --integration-method GET --connection-type VPC_LINK \ --connection-id VPC-link-ID \ --integration-uri arn:aws:elasticloadbalancing:us-east-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/0467ef3c8400ae65 --payload-format-version 1.0 ``` ## Creación de una integración privada mediante la detección de servicios de AWS Cloud Map Antes de crear una integración privada, debe crear un enlace de VPC V2. Para obtener más información acerca de los enlaces de la VPC, consulte [Configuración de enlaces de VPC V2 en API Gateway](apigateway-vpc-links-v2.md). En el caso de las integraciones con AWS Cloud Map, API Gateway utiliza `DiscoverInstances` para identificar recursos. Puede utilizar parámetros de consulta para orientar recursos específicos. Los atributos de los recursos registrados deben incluir direcciones IP y puertos. API Gateway distribuye las solicitudes entre los recursos en buen estado que se devuelven desde `DiscoverInstances`. Para obtener más información, consulte [DiscoverInstances](https://docs.aws.amazon.com/cloud-map/latest/api/API_DiscoverInstances.html) en la Referencia de la API de AWS Cloud Map. **nota** Si utiliza Amazon ECS para rellenar entradas en AWS Cloud Map, debe configurar su tarea de Amazon ECS para utilizar registros de SRV con Amazon ECS Service Discovery o active Amazon ECS Service Connect. Para obtener más información, consulte [Servicios de interconexión](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/interconnecting-services.html) en la Guía para desarrolladores de Amazon Elastic Container Service. Para crear una integración privada con AWS Cloud Map, cree una integración de proxy HTTP, especifique el enlace de la VPC que desea utilizar y proporcione el ARN del servicio de AWS Cloud Map. El siguiente comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) permite crear una integración privada que utilice la detección de servicios de AWS Cloud Map para identificar recursos: ``` aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \ --integration-method GET --connection-type VPC_LINK \ --connection-id VPC-link-ID \ --integration-uri arn:aws:servicediscovery:us-east-2:123456789012:service/srv-id?stage=prod&deployment=green_deployment --payload-format-version 1.0 ``` # Configuración de CORS de las API de HTTP en API Gateway El [uso compartido de recursos entre orígenes (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) es una característica de seguridad del navegador que restringe las solicitudes HTTP que se inician desde secuencias de comandos que se ejecutan en el navegador. 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. Para obtener más información, consulte [¿Qué es el CORS?](https://aws.amazon.com/what-is/cross-origin-resource-sharing/) Por lo general, se necesita CORS para crear aplicaciones web que acceden a las API alojadas en un dominio u origen distinto. Puede habilitar CORS para permitir las solicitudes a la API desde una aplicación web alojada en un dominio distinto. Por ejemplo, si la API está alojada en `https://{api_id}.execute-api.{region}.amazonaws.com/` y desea llamar a la API desde una aplicación web alojada en `example.com`, la API debe ser compatible con CORS. Si configura CORS para una API, API Gateway envía automáticamente una respuesta a las solicitudes OPTIONS preliminares, incluso si no hay ninguna ruta OPTIONS configurada para la API. En una solicitud de CORS, API Gateway agrega los encabezados de CORS configurados a la respuesta de una integración. **nota** Si configura CORS para una API, API Gateway ignora los encabezados de CORS devueltos por su integración de backend. Puede especificar los siguientes parámetros en una configuración de CORS. Para agregar estos parámetros mediante la consola de API HTTP de API Gateway, seleccione **Agregar** después de ingresar el valor. | Encabezados de CORS | Propiedad de configuración de CORS | Valores de ejemplo | | --- | --- | --- | | Access-Control-Allow-Origin | allowOrigins | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/http-api-cors.html) | | Access-Control-Allow-Credentials | allowCredentials | true | | Access-Control-Expose-Headers | exposeHeaders | date, x-api-id, \$1 | | Access-Control-Max-Age | maxAge | 300 | | Access-Control-Allow-Methods | allowMethods | GET, POST, DELETE, \$1 | | Access-Control-Allow-Headers | allowHeaders | authorization, \$1 | Para devolver encabezados de CORS, la solicitud debe contener un encabezado `origin`. Para el método `OPTIONS`, la solicitud debe contener los encabezados `origin` y `Access-Control-Request-Method`. Es posible que la configuración de CORS sea similar a lo siguiente: ![\[Configuración de CORS para las API HTTP\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/http-cors-console.png) ## Configuración de CORS para una API HTTP con una ruta `$default` y un autorizador Puede habilitar CORS y configurar la autorización para cualquier ruta de una API HTTP. Cuando habilita CORS y la autorización para la [ruta `$default`](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html#http-api-develop-routes.default), hay que tener en cuenta algunas consideraciones especiales. La ruta `$default` captura las solicitudes de todos los métodos y rutas que no haya definido explícitamente, incluidas las solicitudes `OPTIONS`. Para admitir las solicitudes de `OPTIONS` no autorizadas, agregue una ruta de `OPTIONS /{proxy+}` a la API que no requiera autorización y asocie una integración a la ruta. La ruta `OPTIONS /{proxy+}` tiene mayor prioridad que la ruta `$default`. Como resultado, permite a los clientes enviar solicitudes `OPTIONS` a su API sin autorización. Para obtener más información acerca de las prioridades de enrutamiento, consulte [Enrutamiento de solicitudes de la API](http-api-develop-routes.md#http-api-develop-routes.evaluation). ## Configuración de CORS para una API HTTP mediante la AWS CLI El siguiente comando [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) permite habilitar las solicitudes de CORS procedentes de `https://www.example.com`: **Example** ``` aws apigatewayv2 update-api --api-id api-id --cors-configuration AllowOrigins="https://www.example.com" ``` Para obtener más información, consulte [CORS](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid.html#apis-apiid-model-cors) en la Referencia de la API de Amazon API Gateway Versión 2. # Transformación de las solicitudes y respuestas de API para las API HTTP en API Gateway Puede modificar las solicitudes API de los clientes antes de que lleguen a sus integraciones de backend. También puede cambiar la respuesta de las integraciones antes de que API Gateway devuelva la respuesta a los clientes. La *asignación de parámetros* sirve para modificar las solicitudes y respuestas de API para las API HTTP. Para utilizar la asignación de parámetros, especifique los parámetros de solicitud o respuesta de API que se van a modificar e indique cómo modificarlos. ## Transformación de solicitudes de API Los parámetros de solicitud se utilizan para cambiar las solicitudes antes de que lleguen a sus integraciones de backend. Puede modificar encabezados, cadenas de consulta o la ruta de la solicitud. Los parámetros de solicitud son una asignación de tipo valor-clave. La clave identifica la ubicación del parámetro de solicitud que se va a cambiar y cómo cambiarlo. El valor especifica los datos nuevos para el parámetro. En la siguiente tabla se muestran las claves admitidas. | Tipo | Sintaxis | | --- | --- | | Encabezado | append\$1overwrite\$1remove:header.headername | | Cadena de consulta | append\$1overwrite\$1remove:querystring.querystring-name | | Ruta | overwrite:path | En la siguiente tabla se muestran los valores admitidos que se pueden asignar a los parámetros. | Tipo | Sintaxis | Notas | | --- | --- | --- | | Valor del encabezado | \$1request.header.name o \$1\$1request.header.name\$1 | Los nombres de encabezado no distinguen entre mayúsculas y minúsculas. API Gateway combina varios valores de encabezado con comas, por ejemplo, "header1": "value1,value2". Algunos encabezados están reservados. Para obtener más información, consulte [Encabezados reservados](#http-api-mapping-reserved-headers). | | Valor de la cadena de consulta | \$1request.querystring.name o \$1\$1request.querystring.name\$1 | Los nombres de cadenas de consulta distinguen entre mayúsculas y minúsculas. API Gateway combina varios valores con comas; por ejemplo, "querystring1" "Value1,Value2". | | Cuerpo de la solicitud | \$1request.body.name o \$1\$1request.body.name\$1 | Una expresión de ruta JSON. El descenso recursivo (\$1request.body..name) y las expresiones de filtro (?(expression)) no son compatibles. Cuando se especifica una ruta JSON, API Gateway trunca el cuerpo de la solicitud en 100 KB y, a continuación, aplica la expresión de selección. Para enviar cargas de más de 100 KB, especifique `$request.body`. | | Ruta de solicitud | \$1request.path o \$1\$1request.path\$1 | La ruta de la solicitud, sin el nombre de la etapa. | | Parámetro de ruta | \$1request.path.name o \$1\$1request.path.name\$1 | El valor de un parámetro de ruta en la solicitud. Por ejemplo, si la ruta es /pets/\$1petId\$1, puede asignar el parámetro petId de la solicitud a \$1request.path.petId. | | Variable de contexto | \$1context.variableName o \$1\$1context.variableName\$1 | El valor de una [variable de contexto](http-api-logging-variables.md). Solo se admiten los caracteres especiales `.` y `_`. | | Variable de etapa | \$1stageVariables.variableName o \$1\$1stageVariables.variableName\$1 | El valor de una [variable de etapa](http-api-stages.stage-variables.md). | | Valor estático | string | Un valor constante. | **nota** Para utilizar distintas variables en una expresión de selección, incluya la variable entre corchetes. Por ejemplo, `${request.path.name} ${request.path.id}`. ## Transformación de respuestas de API Los parámetros de respuesta se utilizan para transformar la respuesta HTTP de una integración de backend antes de devolver la respuesta a los clientes. Puede modificar los encabezados o el código de estado de una respuesta antes de que API Gateway devuelva la respuesta a los clientes. Los parámetros de respuesta se configuran para cada código de estado que devuelve la integración. Los parámetros de respuesta son una asignación de tipo valor-clave. La clave identifica la ubicación del parámetro de solicitud que se va a cambiar y cómo cambiarlo. El valor especifica los datos nuevos para el parámetro. En la siguiente tabla se muestran las claves admitidas. | Tipo | Sintaxis | | --- | --- | | Encabezado | append\$1overwrite\$1remove:header.headername | | Código de estado | overwrite:statuscode | En la siguiente tabla se muestran los valores admitidos que se pueden asignar a los parámetros. | Tipo | Sintaxis | Notas | | --- | --- | --- | | Valor del encabezado | \$1response.header.name o \$1\$1response.header.name\$1 | Los nombres de encabezado no distinguen entre mayúsculas y minúsculas. API Gateway combina varios valores de encabezado con comas, por ejemplo, "header1": "value1,value2". Algunos encabezados están reservados. Para obtener más información, consulte [Encabezados reservados](#http-api-mapping-reserved-headers). | | Cuerpo de respuesta | \$1response.body.name o \$1\$1response.body.name\$1 | Una expresión de ruta JSON. El descenso recursivo (\$1response.body..name) y las expresiones de filtro (?(expression)) no son compatibles. Cuando se especifica una ruta JSON, API Gateway trunca el cuerpo de la respuesta en 100 KB y, a continuación, aplica la expresión de selección. Para enviar cargas de más de 100 KB, especifique `$response.body`. | | Variable de contexto | \$1context.variableName o \$1\$1context.variableName\$1 | El valor de una [variable de contexto](http-api-logging-variables.md) compatible. | | Variable de etapa | \$1stageVariables.variableName o \$1\$1stageVariables.variableName\$1 | El valor de una [variable de etapa](http-api-stages.stage-variables.md). | | Valor estático | string | Un valor constante. | **nota** Para utilizar distintas variables en una expresión de selección, incluya la variable entre corchetes. Por ejemplo, `${request.path.name} ${request.path.id}`. ## Encabezados reservados Los siguientes encabezados están reservados. No puede configurar asignaciones de solicitud o respuesta para estos encabezados. + access-control-\$1 + apigw-\$1 + Autorización + Conexión + Content-Encoding + Longitud del contenido + Content-Location + Forwarded + Keep-Alive + Origen + Proxy-Authenticate + Proxy-Authorization + TE + Trailers + Transfer-Encoding + Upgrade + x-amz-\$1 + x-amzn-\$1 + X-Forwarded-For + X-Forwarded-Host + X-Forwarded-Proto + Via ## Ejemplos En los siguientes ejemplos de la AWS CLI, se configuran asignaciones de parámetros. Para obtener plantillas de CloudFormation de ejemplo, consulte [GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates). ### Adición de un encabezado a una solicitud de API El siguiente comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) permite crear un encabezado denominado `header1` a una solicitud de API antes de que llegue a su integración de backend. API Gateway rellena el encabezado con el ID de solicitud. ``` aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-type HTTP_PROXY \ --payload-format-version 1.0 \ --integration-uri 'https://api.example.com' \ --integration-method ANY \ --request-parameters '{ "append:header.header1": "$context.requestId" }' ``` ### Cambio de nombre de un encabezado de solicitud El siguiente comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) permite cambiar el nombre de encabezado de una solicitud de `header1` a `header2`: ``` aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-type HTTP_PROXY \ --payload-format-version 1.0 \ --integration-uri 'https://api.example.com' \ --integration-method ANY \ --request-parameters '{ "append:header.header2": "$request.header.header1", "remove:header.header1": "''"}' ``` ### Cambio de la respuesta de una integración El siguiente comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) permite configurar los parámetros de respuesta de una integración. Cuando las integraciones devuelven un código de estado 500, API Gateway cambia el código de estado a 403 y agrega `header1`1 a la respuesta. Cuando la integración devuelve un código de estado 404, API Gateway agrega un `error` encabezado a la respuesta. ``` aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-type HTTP_PROXY \ --payload-format-version 1.0 \ --integration-uri 'https://api.example.com' \ --integration-method ANY \ --response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"} }' ``` ### Eliminación de asignaciones de parámetros configuradas El siguiente comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) permite eliminar parámetros de solicitud configurados previamente para `append:header.header1`. También elimina los parámetros de respuesta configurados previamente para un código de estado 200. ``` aws apigatewayv2 update-integration \ --api-id abcdef123 \ --integration-id hijk456 \ --request-parameters '{"append:header.header1" : ""}' \ --response-parameters '{"200" : {}}' ``` # Uso de definiciones de OpenAPI para las API HTTP en API Gateway Para definir su API HTTP, puede utilizar un archivo de definición de OpenAPI 3.0. A continuación, puede importar la definición a API Gateway para crear una API. Para obtener más información sobre las extensiones de API Gateway para OpenAPI, consulte [Extensiones de OpenAPI para API Gateway](api-gateway-swagger-extensions.md). ## Importación de una API HTTP Para crear una API HTTP, puede importar un archivo de definición de OpenAPI 3.0. Para migrar desde una API de REST a una API HTTP, puede exportar la API de REST como un archivo de definición de OpenAPI 3.0. A continuación, importe la definición de la API como una API HTTP. Para obtener más información acerca de cómo exportar una API de REST, consulte [Exportación de una API REST desde API Gateway](api-gateway-export-api.md). **nota** Las API HTTP admiten las mismas variables de AWS que las API REST. Para obtener más información, consulte [Variables de AWS para la importación de OpenAPI](import-api-aws-variables.md). ### Importar información de validación Al importar una API, API Gateway proporciona tres categorías de información de validación. **Información** Una propiedad es válida de acuerdo con la especificación de OpenAPI, pero dicha propiedad no es compatible con las API HTTP. Por ejemplo, el siguiente fragmento de OpenAPI 3.0 genera información en la importación porque las API HTTP no son compatibles con la validación de solicitudes. API Gateway ignora los campos `requestBody` y `schema`. ``` "paths": { "/": { "get": { "x-amazon-apigateway-integration": { "type": "AWS_PROXY", "httpMethod": "POST", "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld", "payloadFormatVersion": "1.0" }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body" } } } } } } ... }, "components": { "schemas": { "Body": { "type": "object", "properties": { "key": { "type": "string" } } } ... } ... } ``` **Advertencia** Una propiedad o estructura no es válida de acuerdo con la especificación de OpenAPI, pero no bloquea la creación de API. Puede especificar si API Gateway debe hacer caso omiso de estas advertencias y seguir creando la API o dejar de crear la API según las advertencias. El siguiente documento de OpenAPI 3.0 genera advertencias en la importación porque las API HTTP solo son compatibles con integraciones de proxy de Lambda y proxy de HTTP. ``` "x-amazon-apigateway-integration": { "type": "AWS", "httpMethod": "POST", "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld", "payloadFormatVersion": "1.0" } ``` **Error** La especificación OpenAPI no es válida o es incorrecta. API Gateway no puede crear ningún recurso a partir del documento con formato incorrecto. Debe corregir los errores y, a continuación, intentarlo de nuevo. La siguiente definición de API genera errores en la importación porque las API HTTP solo son compatibles con la especificación de OpenAPI 3.0. ``` { "swagger": "2.0.0", "info": { "title": "My API", "description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo", "version": "1.0" } ... } ``` Como otro ejemplo, mientras que OpenAPI permite a los usuarios definir una API con varios requisitos de seguridad asociados a una operación en particular, API Gateway no admite esto. Cada operación solo puede tener una autorización de IAM, un autorizador de Lambda o un autorizador JWT. Cuando se intenta modelar varios requisitos de seguridad, se produce un error. ### Importación de una API con la AWS CLI El siguiente comando [import-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/import-api.html) permite importar el archivo de definición de OpenAPI 3.0 `api-definition.json` como una API HTTP. **Example** ``` aws apigatewayv2 import-api --body file://api-definition.json ``` **Example** Puede importar el siguiente ejemplo de definición de OpenAPI 3.0 para crear una API HTTP. ``` { "openapi": "3.0.1", "info": { "title": "Example Pet Store", "description": "A Pet Store API.", "version": "1.0" }, "paths": { "/pets": { "get": { "operationId": "GET HTTP", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pets" } } } } }, "x-amazon-apigateway-integration": { "type": "HTTP_PROXY", "httpMethod": "GET", "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets", "payloadFormatVersion": 1.0 } }, "post": { "operationId": "Create Pet", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPet" } } }, "required": true }, "responses": { "200": { "description": "200 response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPetResponse" } } } } }, "x-amazon-apigateway-integration": { "type": "HTTP_PROXY", "httpMethod": "POST", "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets", "payloadFormatVersion": 1.0 } } }, "/pets/{petId}": { "get": { "operationId": "Get Pet", "parameters": [ { "name": "petId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } } }, "x-amazon-apigateway-integration": { "type": "HTTP_PROXY", "httpMethod": "GET", "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets/{petId}", "payloadFormatVersion": 1.0 } } } }, "x-amazon-apigateway-cors": { "allowOrigins": [ "*" ], "allowMethods": [ "GET", "OPTIONS", "POST" ], "allowHeaders": [ "x-amzm-header", "x-apigateway-header", "x-api-key", "authorization", "x-amz-date", "content-type" ] }, "components": { "schemas": { "Pets": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } }, "Empty": { "type": "object" }, "NewPetResponse": { "type": "object", "properties": { "pet": { "$ref": "#/components/schemas/Pet" }, "message": { "type": "string" } } }, "Pet": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "price": { "type": "number" } } }, "NewPet": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/PetType" }, "price": { "type": "number" } } }, "PetType": { "type": "string", "enum": [ "dog", "cat", "fish", "bird", "gecko" ] } } } } ``` # Exportación de API HTTP desde API Gateway Después de crear una API HTTP, puede exportar una definición de OpenAPI 3.0 de su API desde API Gateway. Puede elegir una etapa que exportar o exportar la configuración más reciente de su API. También puede importar una definición de API exportada a API Gateway para crear otra API idéntica. Para obtener más información sobre la importación de definiciones de API, consulte [Importación de una API HTTP](http-api-open-api.md#http-api-import). ## Exportación de la definición de OpenAPI 3.0 de una etapa mediante AWS CLI El siguiente comando [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) permite exportar una definición de OpenAPI de una etapa de API denominada `prod` a un archivo YAML denominado `stage-definition.yaml`. El archivo de definición exportado incluye [extensiones de API Gateway](api-gateway-swagger-extensions.md) de forma predeterminada. ``` aws apigatewayv2 export-api \ --api-id api-id \ --output-type YAML \ --specification OAS30 \ --stage-name prod \ stage-definition.yaml ``` ## Exportación de una definición de OpenAPI 3.0 de los últimos cambios de la API mediante AWS CLI El siguiente comando [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) permite exportar la definición de OpenAPI de una API HTTP a un archivo JSON denominado `latest-api-definition.json`. Dado que el comando no especifica una etapa, API Gateway exporta la configuración más reciente de la API, con independencia de si se ha implementado o no en una etapa. El archivo de definición exportado no incluye [extensiones de API Gateway](api-gateway-swagger-extensions.md). ``` aws apigatewayv2 export-api \ --api-id api-id \ --output-type JSON \ --specification OAS30 \ --no-include-extensions \ latest-api-definition.json ``` Para obtener más información, consulte [ExportAPI](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#apis-apiid-exports-specification-http-methods) en la *Referencia de la API de Amazon API Gateway Versión 2*. ## Exportación de una definición de OpenAPI 3.0 mediante la consola de API Gateway El procedimiento siguiente describe cómo exportar una definición de OpenAPI de una API HTTP. **Para exportar una definición de OpenAPI 3.0 con 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 HTTP. 1. En el panel de navegación principal, en **Desarrollar**, elija **Exportar**. 1. Seleccione una de las siguientes opciones para exportar la API: ![\[Opciones de exportación para las API HTTP.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/export-http-api.png) 1. En **Origen**, seleccione un origen para la definición de OpenAPI 3.0. Puede elegir una etapa que exportar o exportar la configuración más reciente de la API. 1. Active **Incluir extensiones de API Gateway** para incluir las [extensiones de API Gateway](api-gateway-swagger-extensions.md). 1. En **Formato de salida**, seleccione un formato de salida. 1. Elija **Descargar**.