# API de HTTP de API Gateway Las API de REST y las API HTTP son productos API de RESTful. Las API de REST admiten más funciones que las API HTTP, mientras que las API HTTP están diseñadas con características mínimas para que puedan ofrecerse a un precio más bajo. Para obtener más información, consulte [Elección entre las API de REST y las API de HTTP](http-api-vs-rest.md). Puede utilizar las API HTTP para enviar solicitudes a las funciones de AWS Lambda o a cualquier punto de enlace HTTP direccionable. Por ejemplo, puede crear una API HTTP que se integre con una función de Lambda en el backend. 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. Las API HTTP son compatibles con la autorización de [OpenID Connect](https://openid.net/developers/how-connect-works/) y [OAuth 2.0](https://oauth.net/2/). Vienen con soporte integrado para el uso compartido de recursos entre orígenes (CORS) y las implementaciones automáticas. Puede crear API HTTP mediante la consola de administración de AWS, la AWS CLI, las API, CloudFormation o los SDK. **Topics** + [ # Desarrollo de las API HTTP en API Gateway ](http-api-develop.md) + [ # Publicación de las API de HTTP para que los clientes la invoquen ](http-api-publish.md) + [ # Protección de sus API de HTTP en API Gateway ](http-api-protect.md) + [ # Supervisión de las API de HTTP en API Gateway ](http-api-monitor.md) + [ # Solución de problemas con las API de HTTP en API Gateway ](http-api-troubleshooting.md) # 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**. # Publicación de las API de HTTP para que los clientes la invoquen Puede utilizar etapas y nombres de dominio personalizados para publicar su API para que los clientes la invoquen. Una referencia lógica a un estado del ciclo de vida de la API (por ejemplo, `dev`, `prod`, `beta` o `v2`). Cada etapa es una referencia con nombre a una implementación de la API y está disponible para que las aplicaciones cliente la invoquen. Puede configurar diferentes integraciones y configuraciones para cada etapa de una API. Puede usar nombres de dominio personalizados para proporcionar una URL más simple e intuitiva para que los clientes invoquen su API en vez de la URL predeterminad, `https://api-id.execute-api.region.amazonaws.com/stage`. **nota** Para aumentar la seguridad de las API de API Gateway, el dominio `execute-api.{region}.amazonaws.com` se registra en la [lista de sufijos públicos (PSL)](https://publicsuffix.org/). Para mayor seguridad, recomendamos que utilice cookies con un prefijo `__Host-` en caso de que necesite configurar cookies confidenciales en el nombre de dominio predeterminado de las API de API Gateway. Esta práctica le ayudará a proteger su dominio de los intentos de falsificación de solicitudes entre sitios (CSRF). Para obtener más información, consulte la página de [configuración de cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) en la red de desarrolladores de Mozilla. **Topics** + [ # Etapas de las API HTTP en API Gateway ](http-api-stages.md) + [ # Política de seguridad de las API de HTTP en API Gateway ](http-api-ciphers.md) + [ # Nombres de dominio personalizados para las API de HTTP en API Gateway ](http-api-custom-domain-names.md) # Etapas de las API HTTP en API Gateway Una etapa de API es una referencia lógica a un estado del ciclo de vida de la API (por ejemplo, `dev`, `prod`, `beta` o `v2`). Las etapas de API se identifican por su ID de API y su nombre de etapa, y se incluyen en la URL que utiliza para invocar la API. Cada etapa es una referencia con nombre a una implementación de la API y está disponible para que las aplicaciones cliente la invoquen. Puede crear una etapa `$default` que se ofrezca desde la base de la URL de su API, por ejemplo, `https://{api_id}.execute-api.{region}.amazonaws.com/`. Utilice esta URL para invocar una etapa de la API. Una implementación es una instantánea de la configuración de la API. Después de implementar una API en una etapa, esta está disponible para que los clientes la invoquen. Debe implementar una API para que los cambios surtan efecto. Si habilita implementaciones automáticas, los cambios realizados en una API se liberarán automáticamente. # Uso de variables de etapa para las API de HTTP en API Gateway Las variables de etapa son pares clave-valor que se pueden definir para una etapa de una API HTTP. Actúan como variables de entorno y se pueden usar en la configuración de la API. Las variables de etapa no están previstas para su uso con datos confidenciales (por ejemplo, credenciales). Para transferir información confidencial a las integraciones, utilice un autorizador de AWS Lambda. Puede pasar datos confidenciales a integraciones en la salida del autorizador de Lambda. Para obtener más información, consulte [Formato de respuesta del autorizador de Lambda](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response). ## Ejemplo: Uso de una variable de etapa para personalizar el punto de conexión de integración HTTP Por ejemplo, puede definir una variable de etapa y, a continuación, establecer su valor como punto de conexión HTTP para una integración de proxy HTTP. Posteriormente, puede hacer referencia al punto de conexión mediante el nombre de variable de etapa asociada. Al hacer esto, puede usar la misma configuración de API con un punto de conexión diferente en cada etapa. Del mismo modo, puede utilizar variables de etapa para especificar una integración de funciones de AWS Lambda diferente para cada etapa de la API. Para utilizar una variable de etapa para personalizar el punto de conexión de integración HTTP, primero debe establecer el nombre y el valor de la variable de etapa (por ejemplo, `url`) con un valor de `example.com`. A continuación, configure una integración de proxy HTTP. En lugar de escribir la URL del punto de conexión, puede indicar a API Gateway que use el valor de la variable de etapa, **http://\$1\$1stageVariables.url\$1**. Este valor indica a API Gateway que sustituya la variable de etapa `${}` en el tiempo de ejecución en función de la etapa de la API. Puede hacer referencia a variables de etapa de una manera similar para especificar el nombre de una función de Lambda o el ARN de un rol de AWS. A la hora de especificar el nombre de una función de Lambda como un valor de variable de etapa, debe configurar manualmente los permisos en la función de Lambda. El siguiente comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) permite configurar el permiso de la función Lambda: ``` aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction ``` # Referencia de variables de etapa de API Gateway para las API HTTP en API Gateway Puede utilizar variables de etapa de API Gateway para las API de HTTP en los siguientes casos. ## URI de integración HTTP Puede utilizar una variable de etapa como parte de una URI de integración HTTP, tal y como se muestra en los siguientes ejemplos. + Una URI completa sin protocol – `http://${stageVariables.}` + Un dominio complet – `http://${stageVariables.}/resource/operation` + Un subdomini – `http://${stageVariables.}.example.com/resource/operation` + Una rut – `http://example.com/${stageVariables.}/bar` + Una cadena de consult – `http://example.com/foo?q=${stageVariables.}` ## Funciones de Lambda Puede utilizar una variable de etapa en lugar de un nombre o alias de integración de una función de Lambda, como se muestra en los ejemplos siguientes. + `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations` + `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations` **nota** Para utilizar una variable de etapa para una función de Lambda, la función debe estar en la misma cuenta que la API. Las variables de etapa no admiten funciones de Lambda entre cuentas. ## AWSCredenciales de integración de Puede utilizar una variable de etapa como parte de un ARN de credenciales de usuario o rol de AWS, como se muestra en el siguiente ejemplo. + `arn:aws:iam:::${stageVariables.}` # Política de seguridad de las API de HTTP en API Gateway API Gateway aplica una política de seguridad de `TLS_1_2` para todos los puntos de conexión de la API HTTP. Una *política de seguridad* es una combinación predefinida de versión mínima de TLS y conjuntos de cifrado que ofrece Amazon API Gateway. El protocolo TLS soluciona los problemas de seguridad de red como, por ejemplo, la manipulación y el acceso no autorizado entre un cliente y el servidor. Cuando sus clientes establecen un protocolo de conexión a TLS con la API a través del dominio personalizado, la política de seguridad aplica la versión de TLS y opciones del conjunto de cifrado que sus clientes pueden elegir utilizar. Esta política de seguridad acepta el tráfico de TLS 1.2 y TLS 1.3 y rechaza el tráfico de TLS 1.0. ## Protocolos y cifrados TLS compatibles para las API HTTP En la siguiente tabla se describen los protocolos TLS compatibles con las API de HTTP. | **Protocolos TLS** | **Política de seguridad de TLS\$11\$12** | | --- | --- | | TLSv1.3 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | TLSv1.2 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | En la siguiente tabla se describen los cifrados de TLS que están disponibles para la política de seguridad de TLS 1\$12 para las API de HTTP. | **Cifrados TLS** | **Política de seguridad de TLS\$11\$12** | | --- | --- | | TLS-AES-128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | TLS-AES-256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | TLS-CHACHA20-POLY1305-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | ECDHE-ECDSA-AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | ECDHE-RSA-AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | ECDHE-ECDSA-AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | ECDHE-RSA-AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | ECDHE-ECDSA-AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | ECDHE-RSA-AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | ECDHE-ECDSA-AES256-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | ECDHE-RSA-AES256-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | | AES256-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/success_icon.svg) Sí | ## Nombre del cifrado OpenSSL y RFC OpenSSL e IETF RFC 5246 utilizan nombres distintos para los mismos cifrados. Para obtener una lista de los nombres de los cifrados, consulte [Nombre del cifrado OpenSSL y RFC](apigateway-security-policies-list.md#apigateway-secure-connections-openssl-rfc-cipher-names). ## Información acerca de las API de REST y las API de WebSocket Para obtener más información sobre las API de REST y las API de WebSocket, consulte [Elección de una política de seguridad para el dominio personalizado en API Gateway](apigateway-custom-domain-tls-version.md) y [Política de seguridad de las API de WebSocket en API Gateway](websocket-api-ciphers.md). # Nombres de dominio personalizados para las API de HTTP en API Gateway Los*nombres de dominio personalizados* son direcciones URL más sencillas e intuitivas que puede proporcionar a los usuarios de la API. Después de implementar la API, usted (y sus clientes) puede invocar la API utilizando la URL base predeterminada con el siguiente formato: ``` https://api-id.execute-api.region.amazonaws.com/stage ``` donde *api-id* lo genera API Gateway, *region* es la región de AWS y *stage* lo especifica usted al implementar la API. La parte del nombre de host de la URL, `api-id.execute-api.region.amazonaws.com`, hace referencia a un punto de conexión de la API. El punto de conexión de la API predeterminado se genera aleatoriamente y no es muy descriptivo. Con los nombres de dominio personalizados, puede configurar el nombre de host de la API y elegir una ruta base (por ejemplo, `myservice`) para asignarle una URL alternativa. Por ejemplo, una URL base de la API más simple puede ser: ``` https://api.example.com/myservice ``` ## Consideraciones Las siguientes consideraciones pueden afectar el uso de un nombre de dominio personalizado. + Un nombre de dominio personalizado regional se puede asociar con las API de REST y las API de HTTP. Puede utilizar las API de API Gateway versión 2 para crear y administrar nombres de dominio de región personalizados para las API de REST. + Para la versión de TLS mínima, solo se admite TLS 1.2. + Debe crear o actualizar el registro de recursos del proveedor de DNS para asignarlo al punto de conexión de la API. Si no se realiza este mapeo, las solicitudes de API vinculadas al nombre de dominio personalizado no pueden llegar a API Gateway. + Puede admitir un número casi infinito de nombres de dominio sin exceder el límite predeterminado mediante el uso de un certificado comodín. Para obtener más información, consulte [Nombres de dominio personalizados comodín](#http-wildcard-custom-domain-names). ## Requisitos previos Los siguientes son requisitos previos para crear un nombre de dominio personalizado. ### Registrar un nombre de dominio Debe disponer de un nombre de dominio de Internet registrado para poder crear nombres de dominio personalizados para sus API. Puede registrar su nombre de dominio de Internet con [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) o un registrador de dominios de terceros de su elección. Su nombre de dominio personalizado puede ser el nombre de un subdominio o el dominio raíz (lo que recibe el nombre de “vértice de zona”) de un dominio de Internet registrado. El nombre de dominio debe seguir la especificación [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) y puede tener un máximo de 63 octetos por etiqueta y 255 octetos en total. ### Certificados para nombres de dominio personalizados Antes de configurar un nombre de dominio personalizado para una API, debe disponer de un certificado SSL/TLS listo en ACM. Si ACM no está disponible en la región de AWS donde va a crear su nombre de dominio personalizado, debe importar un certificado en API Gateway en esa región. Para importar un certificado SSL/TLS, debe proporcionar el cuerpo del certificado SSL/TLS con formato PEM, su clave privada y la cadena de certificados para el nombre de dominio personalizado. Los certificados almacenados en ACM se identifican mediante su ARN. Con los certificados emitidos por ACM no tiene que preocuparse de si se exponen datos del certificado confidenciales, como la clave privada. Para utilizar un certificado administrado por AWS para un nombre de dominio, solo tiene que hacer referencia a su ARN. Si la aplicación utiliza asignación de certificados, también conocido como asignación SSL, para asignar un certificado de ACM, es posible que la aplicación no se pueda conectar al dominio una vez que AWS renueva el certificado. Para obtener más información, consulte [Problemas de asignación de certificados](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) en la *Guía del usuario de AWS Certificate Manager*. ## Nombres de dominio personalizados comodín Con los nombres de dominio personalizados comodín, puede admitir un número casi infinito de nombres de dominio sin exceder el [límite predeterminado](limits.md). Por ejemplo, puede dar a cada uno de los clientes su propio nombre de dominio, `customername.api.example.com`. Para crear un nombre de dominio personalizado comodín, especifique un comodín (`*`) como primer subdominio de un dominio personalizado que represente todos los subdominios posibles de un dominio raíz. Por ejemplo, el nombre de dominio personalizado comodín `*.example.com` produce subdominios como `a.example.com`, `b.example.com` y `c.example.com`, que enrutan al mismo dominio. Los nombres de dominio personalizados comodín admiten configuraciones distintas de los nombres de dominio personalizados estándar de API Gateway. Por ejemplo, en una sola cuenta de AWS, puede configurar `*.example.com` y `a.example.com` para que se comporten de manera diferente. Para crear un nombre de dominio personalizado comodín, debe proporcionar un certificado emitido por ACM que se haya validado utilizando el método DNS o de validación de correo electrónico. **nota** No se puede crear un nombre de dominio personalizado comodín si una cuenta de AWS diferente ha creado un nombre de dominio personalizado que entra en conflicto con el nombre de dominio personalizado comodín. Por ejemplo, si la cuenta A ha creado `a.example.com`, la cuenta B no puede crear el nombre de dominio personalizado comodín `*.example.com`. Si la cuenta A y la cuenta B comparten un propietario, puede contactar con el [Centro de soporte de AWS](https://console.aws.amazon.com/support/home#/) para solicitar una excepción. ## Siguientes pasos para nombres de dominio personalizados Para configurar un nombre de dominio personalizado para una API de HTTP, utilice la sección API de REST de la Guía para desarrolladores de API Gateway. En primer lugar, especifique el certificado para el nombre de dominio personalizado. Para obtener más información, consulte [Preparación de certificados en AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). A continuación, cree un nombre de dominio personalizado regional. 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). # Asignación de etapas de API a un nombre de dominio personalizado para las API HTTP Las asignaciones de API se utilizan para conectar etapas de la API a un nombre de dominio personalizado. Después de crear un nombre de dominio y configurar registros DNS, se utilizan asignaciones de API para enviar tráfico a las API a través del nombre de dominio personalizado. Una asignación de API especifica una API, una etapa y, de forma opcional, una ruta que se utilizará para la asignación. Por ejemplo, puede asignar la etapa de `production` de una API a `https://api.example.com/orders`. Puede asignar etapas de API HTTP y de API de REST al mismo nombre de dominio personalizado. Antes de crear una asignación de API, debe tener una API, una etapa y un nombre de dominio personalizado. Para obtener más información sobre cómo crear un nombre de dominio personalizado, consulte [Configuración de un nombre de dominio personalizado regional en API Gateway](apigateway-regional-api-custom-domain-create.md). ## Enrutamiento de solicitudes de la API Puede configurar asignaciones de API con varios niveles; por ejemplo `orders/v1/items` y `orders/v2/items`. En el caso de las asignaciones de API con varios niveles, API Gateway enruta las solicitudes a la asignación de API con la ruta coincidente más larga. API Gateway solo considera las rutas configuradas para las asignaciones de API, y no las rutas de la API, para seleccionar la API que se va a invocar. Si ninguna ruta coincide con la solicitud, API Gateway envía la solicitud a la API que ha asignado a la ruta vacía `(none)`. En el caso de los nombres de dominio personalizados que utilizan asignaciones de API con varios niveles, API Gateway enruta las solicitudes a la asignación de API con el prefijo coincidente más largo. Por ejemplo, pensemos en un nombre de dominio personalizado `https://api.example.com` con las siguientes asignaciones de API: 1. `(none)` asignado a la API 1. 1. `orders` asignado a la API 2. 1. `orders/v1/items` asignado a la API 3. 1. `orders/v2/items` asignado a la API 4. 1. `orders/v2/items/categories` asignado a la API 5. | Solicitud | API seleccionada | Explicación | | --- | --- | --- | | `https://api.example.com/orders` | `API 2` | La solicitud coincide exactamente con esta asignación de API. | | `https://api.example.com/orders/v1/items` | `API 3` | La solicitud coincide exactamente con esta asignación de API. | | `https://api.example.com/orders/v2/items` | `API 4` | La solicitud coincide exactamente con esta asignación de API. | | `https://api.example.com/orders/v1/items/123` | `API 3` | API Gateway elige la asignación con la ruta de coincidencia más larga. El `123` al final de la solicitud no afecta a la selección. | | `https://api.example.com/orders/v2/items/categories/5` | `API 5` | API Gateway elige la asignación con la ruta de coincidencia más larga. | | `https://api.example.com/customers` | `API 1` | API Gateway utiliza la asignación vacía como un catch-all. | | `https://api.example.com/ordersandmore` | `API 2` | API Gateway elige la asignación con el prefijo de coincidencia más largo. En el caso de un nombre de dominio personalizado configurado con asignaciones de un solo nivel, por ejemplo, solo `https://api.example.com/orders` y `https://api.example.com/`, API Gateway elegiría `API 1`, ya que no hay una ruta que coincida con `ordersandmore`. | ## Restricciones + En el caso de una asignación de API, el nombre de dominio personalizado y las API asignadas deben pertenecer a la misma cuenta de AWS. + Las asignaciones de API deben contener solo letras, números y los siguientes caracteres: `$-_.+!*'()/`. + La longitud máxima de la ruta en una asignación de API es de 300 caracteres. + Puede tener 200 asignaciones de API con varios niveles para cada nombre de dominio. Este límite no incluye la asignación de la API con niveles únicos, como `/prod`. + Solo puede asignar API HTTP a un nombre de dominio regional personalizado con la política de seguridad de TLS 1.2. + No puede asignar las API de WebSocket al mismo nombre de dominio personalizado que una API HTTP o API REST. + Si crea una asignación de API con varios niveles, API Gateway convierte todos los nombres de encabezado a minúsculas. ## Creación de una asignación de API Para crear una asignación de API, primero debe crear un nombre de dominio personalizado, una API y una etapa. Para obtener información sobre cómo crear un nombre de dominio personalizado, consulte [Configuración de un nombre de dominio personalizado regional en API Gateway](apigateway-regional-api-custom-domain-create.md). Para ver ejemplos de las plantillas de AWS Serverless Application Model que crean todos los recursos, consulte [Sessions With SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) en GitHub. ------ #### [ Consola de administración de AWS ] **Para crear una asignación de 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 **Nombres de dominio personalizados**. 1. Seleccione un nombre de dominio personalizado que ya haya creado. 1. Elija **Asignaciones de API**. 1. Elija **Configurar asignaciones de API**. 1. Seleccione **Agregar nueva asignación**. 1. Introduzca una **API**, una **Etapa** y, de forma opcional, una **Ruta**. 1. Seleccione **Save**. ------ #### [ AWS CLI ] El siguiente comando [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) permite crear una asignación de API. En este ejemplo, API Gateway envía solicitudes a `api.example.com/v1/orders` a la API y a la etapa especificadas. ``` aws apigatewayv2 create-api-mapping \ --domain-name api.example.com \ --api-mapping-key v1/orders \ --api-id a1b2c3d4 \ --stage test ``` ------ #### [ CloudFormation ] En el siguiente ejemplo de CloudFormation, se crea una asignación de API. ``` MyApiMapping: Type: 'AWS::ApiGatewayV2::ApiMapping' Properties: DomainName: api.example.com ApiMappingKey: 'orders/v2/items' ApiId: !Ref MyApi Stage: !Ref MyStage ``` ------ # Deshabilitación del punto de conexión predeterminado para las API HTTP De forma predeterminada, los clientes pueden invocar su API mediante el punto de conexión `execute-api` que API Gateway genera para ella. Para asegurarse de que los clientes solo puedan acceder a su API mediante un nombre de dominio personalizado, deshabilite el punto de conexión predeterminado `execute-api`. Cuando deshabilita el punto de conexión predeterminado, esto afecta a todas las etapas de una API. El siguiente procedimiento muestra cómo deshabilitar el punto de conexión predeterminado para una API HTTP. ------ #### [ Consola de administración de AWS ] 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. Elija el ID de la API para abrir la página **Detalles de la API**. 1. En **Detalles de la API**, elija **Editar**. 1. En **Punto de conexión predeterminado**, elija **Deshabilitar**. 1. Seleccione **Guardar**. Si activa las implementaciones automáticas para la etapa, no necesita volver a implementar la API con el fin de que el cambio surta efecto. De lo contrario, tendrá que volver a implementar la API. 1. (Opcional) Elija **Implementar** y, a continuación, vuelva a implementar la API o cree una nueva etapa para que el cambio surta efecto. ------ #### [ AWS CLI ] El siguiente comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) deshabilita el punto de conexión predeterminado de una API HTTP. ``` aws apigatewayv2 update-api \ --api-id abcdef123 \ --disable-execute-api-endpoint ``` Tras deshabilitar el punto de conexión predeterminado, debe implementar la API para que el cambio surta efecto, salvo que se hayan habilitado las implementaciones automáticas. El siguiente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) crea una implementación: ``` aws apigatewayv2 create-deployment \ --api-id abcdef123 \ --stage-name dev ``` ------ # Tipos de direcciones IP para nombres de dominio personalizados para API HTTP Al crear una API, se especifica el tipo de direcciones IP que puede invocar el dominio. Puede elegir IPv4 para resolver las direcciones IPv4 para invocar el dominio o puede elegir pila doble para permitir que las direcciones IPv4 e IPv6 invoquen el dominio. 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). ## 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 los nombres de dominio personalizados de API Gateway es IPv4. + El nombre de dominio personalizado no necesita tener el mismo tipo de dirección IP para todas las API asignadas a él. 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 un nombre de dominio personalizado Puede cambiar el tipo de dirección IP actualizando la configuración de punto de conexión del dominio. Puede actualizar la configuración de punto de conexión del dominio mediante el uso de la Consola de administración de AWS, la AWS CLI, CloudFormation, o un AWS SDK. ------ #### [ Consola de administración de AWS ] **Cambio del tipo de dirección IP de un nombre de dominio personalizado** 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 un nombre de dominio personalizado público. 1. Elija la **Configuración de punto de conexión**. 1. Para tipo de dirección IP, seleccione **IPv4** o **Pila doble**. 1. Seleccione **Save**. ------ #### [ AWS CLI ] El siguiente comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) actualiza una API para que tenga un tipo de dirección IP de pila doble: ``` aws apigatewayv2 update-domain-name \ --domain-name dualstack.example.com \ --domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack ``` El resultado será similar al siguiente: ``` { "ApiMappingSelectionExpression": "$request.basepath", "DomainName": "dualstack.example.com", "DomainNameConfigurations": [ { "ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com", "CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc", "DomainNameStatus": "AVAILABLE", "EndpointType": "REGIONAL", "HostedZoneId": "Z3LQWSYCGH4ADY", "SecurityPolicy": "TLS_1_2", "IpAddressType": "dualstack" } ], "Tags": {} } ``` ------ # Protección de sus API de HTTP en API Gateway API Gateway proporciona una serie de formas de proteger su API de ciertas amenazas, como usuarios malintencionados o picos de tráfico. Puede proteger su API mediante estrategias como establecer objetivos de limitación y habilitar TLS mutuo. En esta sección puede aprender cómo habilitar estas capacidades mediante API Gateway. **Topics** + [ # Limitación de las solicitudes a sus API HTTP para mejorar el rendimiento en API Gateway ](http-api-throttling.md) + [ # Cómo habilitar la autenticación TLS mutua para sus API de HTTP en API Gateway ](http-api-mutual-tls.md) # Limitación de las solicitudes a sus API HTTP para mejorar el rendimiento en API Gateway Puede configurar la limitación de las API para evitar que se vean desbordadas por un número excesivo de solicitudes. La limitación se aplica como medida compensatoria y se debe considerar como un valor objetivo, más que como un límite de solicitudes garantizado. API Gateway limita las solicitudes a la API utilizando el algoritmo de bucket de tokens, donde un token cuenta por una solicitud. En concreto, API Gateway examina el ratio de solicitudes y una ráfaga de envíos de solicitudes para todas las API de su cuenta, por región. En el algoritmo de bucket de tokens, una ráfaga puede permitir que se sobrepasen los límites predefinidos, pero también hay otros factores que pueden hacer que se sobrepasen los límites en algunos casos. Cuando los envíos de solicitudes superan los límites de ratio de solicitudes en estado estable y de ráfaga, API Gateway comienza a limitar las solicitudes. Los clientes pueden recibir respuestas de error `429 Too Many Requests` en este momento. Tras capturar estas excepciones, el cliente puede reenviar las solicitudes que han producido un error de forma que limite el ratio. Como desarrollador de la API, puede configurar los límites objetivos para las etapas o rutas individuales de la API con el fin de mejorar el rendimiento general de todas las API de su cuenta. ## Limitación de nivel de cuenta por región De forma predeterminada, API Gateway limita las solicitudes de estado constante por segundo (RPS) en todas las API de una cuenta de AWS, por región. También limita la ráfaga (es decir, el tamaño máximo del bucket) en todas las API dentro de una cuenta de AWS, por región. En API Gateway, el límite de ráfaga representa el número máximo de envíos de solicitudes simultáneas que API Gateway; abordará antes de devolver respuestas de error `429 Too Many Requests`. Para obtener más información sobre las cuotas de limitación, consulte [Cuotas de Amazon API Gateway](limits.md). Los límites por cuenta se aplican a todas las API de una cuenta en una región determinada. El límite de ratio de nivel de cuenta se puede aumentar previa solicitud. Los límites más altos son posibles con API que tienen tiempos de espera más cortos y cargas útiles más pequeñas. Para solicitar un aumento de los límites de limitación de nivel de cuenta por región, contacte con el [Centro de soporte de AWS](https://console.aws.amazon.com/support/home#/). Para obtener más información, consulte [Cuotas de Amazon API Gateway](limits.md). Tenga en cuenta que estos límites no pueden ser superiores a los límites de limitación de AWS. ## Limitación de nivel de ruta Puede definir la limitación de nivel de ruta para invalidar los límites de limitación de las solicitudes de nivel de cuenta de una determinada etapa o de las rutas individuales de la API. Los límites de limitación de rutas predeterminados no pueden superar los límites de ratio a nivel de cuenta. Puede configurar la limitación de nivel de ruta mediante la AWS CLI. El siguiente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) permite configurar la limitación de nivel de ruta para la etapa y la ruta especificadas de una API. ``` aws apigatewayv2 update-stage \ --api-id a1b2c3d4 \ --stage-name dev \ --route-settings '{"GET /pets":{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}' ``` # Cómo habilitar la autenticación TLS mutua para sus API de HTTP en API Gateway La autenticación TLS mutua requiere la autenticación bidireccional entre el cliente y el servidor. Con la TLS mutua, los clientes deben presentar certificados X.509 para verificar su identidad y acceder a su API. La TLS mutua es un requisito frecuente para el Internet de las cosas (IoT) y las aplicaciones entre empresas. Puede utilizar TLS mutua junto con otras [operaciones de autorización y autenticación](apigateway-control-access-to-api.md) compatibles con API Gateway. API Gateway reenvía los certificados que los clientes proporcionan a los autorizadores de Lambda y a las integraciones del backend. **importante** De forma predeterminada, los clientes pueden invocar su API mediante el punto de conexión `execute-api` que API Gateway genera para su API. Para asegurarse de que los clientes solo puedan acceder a su API mediante un nombre de dominio personalizado con la TLS mutua, deshabilite el punto de conexión `execute-api` predeterminado. Para obtener más información, consulte [Deshabilitación del punto de conexión predeterminado para las API HTTP](http-api-disable-default-endpoint.md). ## Requisitos previos de la TLS mutua Para configurar la TLS mutua necesita lo siguiente: + Un nombre de dominio personalizado + Al menos un certificado configurado en AWS Certificate Manager para el nombre de dominio personalizado + Un almacén de confianza configurado y cargado en Amazon S3 ### Nombres de dominio personalizados Para habilitar la TLS mutua para una API HTTP, debe configurar un nombre de dominio personalizado para la API. Puede habilitar la TLS mutua para un nombre de dominio personalizado y, a continuación, proporcionar el nombre de dominio personalizado a los clientes. Para acceder a una API mediante un nombre de dominio personalizado que tenga habilitada la TLS mutua, los clientes deben presentar certificados en los que confíe en las solicitudes de API. Dispone de más información en [Nombres de dominio personalizados para las API de HTTP en API Gateway](http-api-custom-domain-names.md). ### Uso de certificados emitidos por AWS Certificate Manager Puede solicitar un certificado de confianza pública directamente desde ACM o importar certificados públicos o autofirmados. Para configurar un certificado en ACM, vaya a [ACM](https://console.aws.amazon.com/acm/). Si desea importar un certificado, siga leyendo en la siguiente sección. ### Uso de un certificado importado o de AWS Private Certificate Authority Para utilizar un certificado importado en ACM o un certificado de AWS Private Certificate Authority con TLS mutua, API Gateway necesita un `ownershipVerificationCertificate` emitido por ACM. Este certificado de propiedad solo se utiliza para comprobar que dispone de permisos para utilizar el nombre de dominio. No se utiliza en el protocolo de enlace TLS. Si todavía no tiene un `ownershipVerificationCertificate`, vaya a [https://console.aws.amazon.com/acm/](https://console.aws.amazon.com/acm/) para configurarlo. Este certificado deberá mantener su validez durante toda la vida útil del nombre de dominio. Si un certificado caduca y falla la renovación automática, se bloquearán todas las actualizaciones del nombre de dominio. Tendrá que actualizar el `ownershipVerificationCertificateArn` con un `ownershipVerificationCertificate` válido para poder realizar otros cambios. El `ownershipVerificationCertificate` no se puede utilizar como certificado de servidor para otro dominio de TLS mutua en API Gateway. Si un certificado se vuelve a importar directamente en ACM, el emisor debe ser el mismo. ### Configuración del almacén de confianza Los almacenes de confianza son archivos de texto cuya extensión es `.pem`. Son una lista de certificados de confianza procedentes de entidades de certificación. Para utilizar la TLS mutua, cree un almacén de confianza de certificados X.509 en los que confíe para acceder a su API. En el almacén de confianza debe incluir la cadena de confianza completa, desde el certificado de entidad de certificación emisora hasta el certificado de entidad de certificación raíz. API Gateway acepta certificados de cliente emitidos por cualquier entidad de certificación presente en la cadena de confianza. Los certificados pueden ser de autoridades de certificación públicas o privadas. Los certificados pueden tener una longitud máxima de cadena de cuatro. También puede proporcionar certificados autofirmados. Se admiten los siguientes algoritmos hash en el almacén de confianza: + SHA-256 o más seguro + RSA-2048 o más seguro + ECDSA-256 o más seguro API Gateway valida una serie de propiedades de certificado. Puede utilizar autorizadores de Lambda para realizar comprobaciones adicionales cuando un cliente invoque una API, tales como verificar si se ha revocado un certificado. API Gateway valida las siguientes propiedades: | Validación | Descripción | | --- | --- | | Sintaxis X.509 | El certificado debe cumplir los requisitos de sintaxis X.509. | | Integridad | El contenido del certificado no debe haberse alterado con respecto al firmado por la entidad de certificación del almacén de confianza. | | Validez | El período de validez del certificado debe ser actual. | | Encadenamiento de nombres/encadenamiento de claves | Los nombres y asuntos de los certificados deben formar una cadena ininterrumpida. Los certificados pueden tener una longitud máxima de cadena de cuatro. | ### Carga del almacén de confianza a un bucket de Amazon S3 en un solo archivo **Example certificates.pem** ``` -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- ... ``` El siguiente comando [cp](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html) de la AWS CLI permite cargar `certificates.pem` en el bucket de Amazon S3. ``` aws s3 cp certificates.pem s3://bucket-name ``` ## Configuración de la TLS mutua para un nombre de dominio personalizado Para configurar la TLS mutua para una API HTTP, debe utilizar un nombre de dominio personalizado regional para la API, y la versión mínima de TLS debe ser la 1.2. Para obtener más información sobre cómo crear y configurar un nombre de dominio personalizado, consulte [Configuración de un nombre de dominio personalizado regional en API Gateway](apigateway-regional-api-custom-domain-create.md). **nota** La TLS mutua no es compatible con las API privadas. Después de cargar su almacén de confianza en Amazon S3, puede configurar su nombre de dominio personalizado para que utilice TLS mutua. El siguiente comando [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html) permite crear un nombre de dominio personalizado con TLS mutua: ``` aws apigatewayv2 create-domain-name \ --domain-name api.example.com \ --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \ --mutual-tls-authentication TruststoreUri=s3://bucket-name/key-name ``` Después de crear el nombre de dominio, debe configurar los registros DNS y los mapeos de ruta base para las operaciones de la API. 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). ## Invocar una API mediante un nombre de dominio personalizado que requiere la TLS mutua Para invocar una API con la TLS mutua habilitada, los clientes deben presentar un certificado de confianza en la solicitud de la API. Cuando un cliente intenta invocar la API, API Gateway busca el emisor del certificado del cliente en el almacén de confianza. Para que API Gateway atienda la solicitud, en el almacén de confianza deben constar el emisor del certificado y la cadena de confianza completa hasta el certificado de entidad de certificación raíz. El siguiente ejemplo de comando `curl` envía una solicitud a `api.example.com,` que incluye `my-cert.pem` en la solicitud. `my-key.key` es la clave privada del certificado. ``` curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com ``` Su API solo se invoca si su almacén de confianza confía en el certificado. Las siguientes condiciones provocarán que API Gateway no pueda completar el protocolo de enlace TLS y deniegue la solicitud con un código de estado `403`. Si el certificado: + no es de confianza + ha caducado + no utiliza un algoritmo compatible **nota** API Gateway no comprueba si se ha revocado un certificado. ## Actualización de su almacén de confianza Para actualizar los certificados del almacén de confianza, cargue un nuevo paquete de certificados en Amazon S3. Después, puede actualizar el nombre de dominio personalizado para que utilice el certificado actualizado. Utilice el [control de versiones de Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) para mantener varias versiones de su almacén de confianza. Cuando actualiza el nombre de dominio personalizado para utilizar una nueva versión del almacén de confianza, API Gateway devuelve advertencias si los certificados no son válidos. API Gateway produce advertencias de certificado solo cuando actualiza el nombre de dominio. API Gateway no le notifica si caduca un certificado cargado anteriormente. El siguiente comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) permite actualizar un nombre de dominio personalizado para utilizar una nueva versión del almacén de confianza. ``` aws apigatewayv2 update-domain-name \ --domain-name api.example.com \ --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \ --mutual-tls-authentication TruststoreVersion='abcdef123' ``` ## Deshabilitar la TLS mutua Para deshabilitar la TLS mutua para un nombre de dominio personalizado, elimine el almacén de confianza del nombre de dominio personalizado, como se muestra en el siguiente comando. El siguiente comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) permite actualizar un nombre de dominio personalizado para eliminar de él el almacén de confianza: ``` aws apigatewayv2 update-domain-name \ --domain-name api.example.com \ --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \ --mutual-tls-authentication TruststoreUri='' ``` ## Solución de problemas de TLS mutuo para su API de HTTP A continuación se proporcionan consejos para solucionar errores y problemas que puedan surgir al activar TLS mutuo. ### Solución de problemas de advertencias de certificados Cuando se crea un nombre de dominio personalizado con TLS mutua, API Gateway devuelve advertencias si los certificados del almacén de confianza no son válidos. Esto también puede ocurrir cuando se actualiza un nombre de dominio personalizado para que utilice un nuevo almacén de confianza. Las advertencias indican el problema con el certificado y el asunto del certificado que produjo la advertencia. La TLS mutua aún está habilitada en la API, pero es posible que algunos clientes no puedan acceder a su API. Debe descodificar los certificados del almacén de confianza para identificar cuál de ellos ha producido la advertencia. Puede utilizar herramientas como `openssl` para descodificar los certificados e identificar sus asuntos. El siguiente comando muestra el contenido de un certificado, incluido su asunto: ``` openssl x509 -in certificate.crt -text -noout ``` Actualice o elimine los certificados que produjeron advertencias y, a continuación, cargue un nuevo almacén de confianza en Amazon S3. Después de cargar el nuevo almacén de confianza, actualice el nombre de dominio personalizado para que utilice ese nuevo almacén de confianza. ### Solución de problemas por conflictos de nombres de dominio El error `"The certificate subject conflicts with an existing certificate from a different issuer."` significa que varias entidades de certificación han emitido un certificado para este dominio. Para cada asunto del certificado, solo puede haber un emisor en API Gateway para dominios de TLS mutua. Tendrá que obtener todos los certificados para ese asunto a través de un solo emisor. Si el problema se debe a un certificado que no está bajo su control pero puede demostrar la propiedad del nombre de dominio, [contacte con Soporte](https://console.aws.amazon.com/support/cases#/create) para abrir un ticket. ### Solución de problemas por mensajes de estado de nombres de dominio `PENDING_CERTIFICATE_REIMPORT`: esto significa que ha vuelto a importar un certificado en ACM y ha fallado la validación porque el nuevo certificado tiene un SAN (nombre alternativo de sujeto) que no está cubierto por el `ownershipVerificationCertificate`, o bien porque el asunto o los SAN del certificado no cubren el nombre de dominio. Es posible que haya algo que esté configurado incorrectamente o que se haya importado un certificado no válido. Debe volver a importar un certificado válido en ACM. Para obtener más información sobre la validación, consulte [Validación de la propiedad de dominios](https://docs.aws.amazon.com/acm/latest/userguide/domain-ownership-validation.html). `PENDING_OWNERSHIP_VERIFICATION`: esto significa que el certificado verificado previamente ha caducado y ACM no lo ha podido renovar automáticamente. Tendrá que renovar el certificado o solicitar otro nuevo. Dispone de más información sobre la renovación de certificados en la guía [Solución de problemas de renovación de certificados administrados de ACM](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-renewal.html). # Supervisión de las API de HTTP en API Gateway Puede utilizar las métricas de CloudWatch y CloudWatch Logs para monitorear las API HTTP. Al combinar registros y métricas, puede registrar errores y monitorear el rendimiento de su API. **nota** API Gateway podría no generar registros y métricas en los siguientes casos: Errores 413: Entidad de solicitud demasiado grande Errores 429: Demasiadas Solicitudes Errores de la serie 400 de solicitudes enviadas a un dominio personalizado que no tiene asignación de API Errores de la serie 500 causados por errores internos **Topics** + [ # Supervisión de las métricas de CloudWatch para las API de HTTP en API Gateway ](http-api-metrics.md) + [ # Configuración del registro de API HTTP en API Gateway ](http-api-logging.md) # Supervisión de las métricas de CloudWatch para las API de HTTP en API Gateway Puede monitorear la ejecución de la API mediante CloudWatch, que recopila y procesa datos sin formato de API Gateway en métricas legibles casi en tiempo real. Estas estadísticas se registran durante un periodo de 15 meses, para que pueda obtener acceso a información de historial y obtener una mejor perspectiva acerca del desempeño de su aplicación web o servicio. De forma predeterminada, los datos de las métricas de API Gateway se envían automáticamente a CloudWatch en períodos de un minuto. Para supervisar sus métricas, cree un panel de CloudWatch para la API. Para obtener más información sobre cómo crear un panel de CloudWatch, consulte [Creación de un panel de CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create_dashboard.html) en la *Guía del usuario de Amazon CloudWatch*. Para obtener más información, consulte [¿Qué es Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) en la *guía del usuario de Amazon Cloudwatch*. Las siguientes métricas son compatibles con las API HTTP. También puede habilitar métricas detalladas para escribir métricas en el nivel de ruta en Amazon CloudWatch. | Métrica | Descripción | | --- | --- | | 4xx | El número de errores del cliente capturados en un periodo determinado. | | 5xx | El número de errores del servidor capturados en un periodo determinado. | | Recuento | El número total de solicitudes de API en un periodo de tiempo determinado. | | IntegrationLatency | Es el tiempo entre que API Gateway transmite una solicitud al backend y se recibe una respuesta del backend. | | Latency (Latencia) | El tiempo entre que API Gateway recibe una solicitud de un cliente y devuelve una respuesta al cliente. La latencia incluye la latencia de la integración y otra carga de API Gateway. | | Datos procesados | La cantidad de datos procesados en bytes. | Puede usar las dimensiones de la tabla siguiente para filtrar las métricas de API Gateway. | Dimensión | Descripción | | --- | --- | | ApiId | Filtra las métricas de API Gateway para una API con el ID de API especificado. | | ApiId, Stage | Filtra las métricas de API Gateway para una etapa de API cuyos ID de API y de etapa se hayan especificado. | | ApiId, método, recurso, etapa | Filtra las métricas de API Gateway para un método de API con el ID de API, el ID de etapa, la ruta de recursos y el ID de enrutamiento específicos. API Gateway no enviará estas métricas a menos que haya habilitado explícitamente las métricas detalladas de CloudWatch. Puede hacerlo mediante una llamada a la acción [UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html) de la API de REST de API Gateway V2 para actualizar la propiedad `detailedMetricsEnabled` en `true`. También puede llamar al comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) AWS CLI para actualizar la propiedad `DetailedMetricsEnabled` a `true`. Si activa estas métricas, se le cobrarán cargos adicionales en su cuenta. Para obtener más información sobre precios, consulte [Precios de Amazon CloudWatch](https://aws.amazon.com/cloudwatch/pricing/). | # Configuración del registro de API HTTP en API Gateway Puede activar el registro para escribir registros en CloudWatch Logs. Puede utilizar [variables de registro](http-api-logging-variables.md) para personalizar el contenido de los registros. Para aumentar la seguridad, le recomendamos que escriba los registros en Registros de CloudWatch para todas las etapas de la API HTTP. Es probable que deba hacerlo para asegurar el cumplimiento de 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*. Para activar el registro para una API HTTP, tendrá que hacer lo siguiente. 1. Asegúrese de que el usuario tenga los permisos necesarios para activar el registro. 1. Cree un grupo de registros de Registros de CloudWatch. 1. Proporcione el ARN del grupo de registros de Registros de CloudWatch para una etapa de la API. ## Permisos para activar el registro Para activar el registro para una API, el usuario debe tener los siguientes permisos. **Example** **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:GetLogEvents", "logs:FilterLogEvents" ], "Resource": "arn:aws:logs:us-east-2:123456789012:log-group:*" }, { "Effect": "Allow", "Action": [ "logs:CreateLogDelivery", "logs:PutResourcePolicy", "logs:UpdateLogDelivery", "logs:DeleteLogDelivery", "logs:CreateLogGroup", "logs:DescribeResourcePolicies", "logs:GetLogDelivery", "logs:ListLogDeliveries" ], "Resource": "*" } ] } ``` ## Crear un grupo de registro y activar el registro para las API HTTP Puede crear un grupo de registro y activar el registro de acceso mediante Consola de administración de AWS o AWS CLI. ------ #### [ Consola de administración de AWS ] 1. Cree un grupo de registros. Para obtener información acerca de cómo crear un grupo de registro mediante la consola, consulte [Crear un grupo de registro en la Guía del usuario de Registros de Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html). 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 la pestaña **Monitor** (Monitorear), en el panel de navegación principal, elija **Logging** (Registro). 1. Seleccione una etapa para activar el registro y elija **Select** (Seleccionar). 1. Elija **Edit** (Editar) para activar el registro de acceso. 1. Active el **Access logging** (Registro de acceso), ingrese un registro de CloudWatch y seleccione un formato de registro. 1. Seleccione **Save**. ------ #### [ AWS CLI ] El siguiente comando [create-log-group](https://docs.aws.amazon.com/cli/latest/reference/logs/create-log-group.html) permite crear un grupo de registro: ``` aws logs create-log-group --log-group-name my-log-group ``` Necesita el nombre de recurso de Amazon (ARN) del grupo de registro para activar el registro. El formato del ARN es arn:aws:logs:*región*:*id de cuenta*:grupo de registro:*nombre del grupo de registro*. El siguiente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) activa el registro para la etapa `$default` de una API HTTP. ``` aws apigatewayv2 update-stage --api-id abcdef \ --stage-name '$default' \ --access-log-settings '{"DestinationArn": "arn:aws:logs:region:account-id:log-group:log-group-name", "Format": "$context.identity.sourceIp - - [$context.requestTime] \"$context.httpMethod $context.routeKey $context.protocol\" $context.status $context.responseLength $context.requestId"}' ``` ------ ## Ejemplo de formatos de registro La consola de API Gateway incluye algunos ejemplos de los formatos de registro de acceso habituales, los cuales se detallan a continuación. + `CLF` ([Common Log Format](https://httpd.apache.org/docs/current/logs.html#common)): ``` $context.identity.sourceIp - - [$context.requestTime] "$context.httpMethod $context.routeKey $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId ``` + `JSON`: ``` { "requestId":"$context.requestId", "ip": "$context.identity.sourceIp", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod","routeKey":"$context.routeKey", "status":"$context.status","protocol":"$context.protocol", "responseLength":"$context.responseLength", "extendedRequestId": "$context.extendedRequestId" } ``` + `XML`: ``` $context.identity.sourceIp $context.requestTime $context.httpMethod $context.routeKey $context.status $context.protocol $context.responseLength $context.extendedRequestId ``` + `CSV` (valores separados por comas): ``` $context.identity.sourceIp,$context.requestTime,$context.httpMethod,$context.routeKey,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId ``` # Personalización de registros de acceso de las API de HTTP Puede utilizar las siguientes variables para personalizar los registros de acceso de las API HTTP. Para obtener más información acerca de los registros de acceso para las API HTTP, consulte [Configuración del registro de API HTTP en API Gateway](http-api-logging.md). | 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 reclamaciones devueltas por el JSON Web Token (JWT) una vez que se ha autenticado correctamente al intermediario del método, como `$context.authorizer.claims.username`. 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). La llamada a `$context.authorizer.claims` devuelve null. | | \$1context.authorizer.error | El mensaje de error devuelto por un autorizador. | | \$1context.authorizer.property | El valor del par clave-valor especificado de la asignación `context` devuelto de una función de autorizador de Lambda para 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 `1` y la llamada a `$context.authorizer.boolKey` devuelve `true`. | | \$1context.awsEndpointRequestId | El ID de la solicitud del punto de enlace de AWS desde el encabezado `x-amz-request-id` o `x-amzn-requestId`. | | \$1context.awsEndpointRequestId2 | El ID de la solicitud del punto de enlace de AWS desde el encabezado `x-amz-id-2`. | | \$1context.customDomain.basePathMatched | La ruta de un mapeo de la API con la que coincidió una solicitud entrante. Aplicable cuando un cliente utiliza un nombre de dominio personalizado para acceder a una API. Por ejemplo, si un cliente envía una solicitud a `https://api.example.com/v1/orders/1234` y la solicitud empareja el mapeo de la API con la ruta `v1/orders`, el valor es `v1/orders`. Para obtener más información, consulte [Asignación de etapas de API a un nombre de dominio personalizado para las API HTTP](http-api-mappings.md). | | \$1context.dataProcessed | La cantidad de datos procesados en bytes. | | \$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. | | \$1context.error.messageString | El valor entrecomillado de \$1context.error.message, es decir, "\$1context.error.message". | | \$1context.error.responseType | Un tipo de `GatewayResponse`. 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.extendedRequestId | Es igual que \$1context.requestId. | | \$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. Compatible con rutas que utilizan la autorización de IAM. | | \$1context.identity.caller | El identificador principal del intermediario que firmó la solicitud. Compatible con rutas 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). Compatible con rutas que utilizan la autorización de IAM. | | \$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. | | \$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. | | \$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. | | \$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. | | \$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. | | \$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. | | \$1context.identity.sourceIp | La dirección IP de origen de la conexión TCP inmediata que realiza la solicitud al punto de enlace de API Gateway. | | \$1context.identity.user | El identificador principal del usuario que se autorizará a acceder al recurso. Compatible con rutas 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. Compatible con rutas que utilizan la autorización de IAM. 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.integration.error | El mensaje de error devuelto por una integración. Es igual que \$1context.integrationErrorMessage. | | \$1context.integration.integrationStatus | Para la integración de proxy de Lambda, el código de estado que se devuelve desde AWS Lambda, y no desde el código de función de Lambda del backend. | | \$1context.integration.latency | La latencia de integración en ms. Es igual que \$1context.integrationLatency. | | \$1context.integration.requestId | El ID de solicitud del punto de conexión de AWS. Es igual que \$1context.awsEndpointRequestId. | | \$1context.integration.status | El código de estado devuelto por una integración. Para integraciones de proxy de Lambda, este es el código de estado que devuelve su código de la función de Lambda. | | \$1context.integrationErrorMessage | Una cadena que contiene un mensaje de error de integración. | | \$1context.integrationLatency | La latencia de integración en ms. | | \$1context.integrationStatus | Para la integración de proxy de Lambda, este parámetro representa el código de estado que se devuelve desde AWS Lambda, y no desde la función de Lambda del backend. | | \$1context.path | Ruta de acceso de la solicitud. Por ejemplo, /\$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 | El ID que API Gateway asigna a la solicitud de API. | | \$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). | | \$1context.responseLatency | La latencia de respuesta en ms. | | \$1context.responseLength | La duración de la carga de respuesta en bytes. | | \$1context.routeKey | La clave de ruta de la solicitud de la API, por ejemplo, `/pets`. | | \$1context.stage | La etapa de implementación de la solicitud de la API (por ejemplo, `beta` o `prod`). | | \$1context.status | El estado de respuesta de método. | # Solución de problemas con las API de HTTP en API Gateway Los siguientes temas le proporcionan consejos para solucionar errores y problemas que puedan surgir al utilizar API HTTP. **Topics** + [ # Solución de problemas con las integraciones de Lambda para API HTTP ](http-api-troubleshooting-lambda.md) + [ # Solución de problemas con los autorizadores JWT de la API HTTP ](http-api-troubleshooting-jwt.md) # Solución de problemas con las integraciones de Lambda para API HTTP A continuación se proporcionan consejos para solucionar errores y problemas que puedan surgir al utilizar [AWS LambdaIntegraciones de ](http-api-develop-integrations-lambda.md) con API HTTP. ## Problema: mi API con una integración de Lambda devuelve `{"message":"Internal Server Error"}` Para solucionar el error interno del servidor, agregue la [variable de registro](http-api-logging-variables.md) `$context.integrationErrorMessage` al formato de registro y vea sus registros de API HTTP. Para ello, haga lo siguiente: **Para crear un grupo de registros a través de la Consola de administración de AWS** 1. Abra la consola de CloudWatch en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Elija **Log groups (Grupos de registros)**. 1. Elija **Create log group (Crear grupo de registros)**. 1. Escriba un nombre de grupo de registros y, a continuación, elija **Create (Crear)**. 1. Anote el nombre de recurso de Amazon (ARN) de su grupo de registros. El formato ARN es arn:aws:logs: *region*: *account-id*:log-group:*log-group-name*. Necesita el ARN del grupo de registros para habilitar el registro de acceso a su API HTTP. **Para agregar la variable de registro `$context.integrationErrorMessage`** 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 su API HTTP. 1. En **Monitorización**, elija **Registro**. 1. Seleccione una etapa de su API. 1. Elija **Edit (Editar)** y, a continuación, habilite el registro de acceso. 1. En **Log destination (Destino del registro)**, introduzca el ARN del grupo de registros que creó en el paso anterior. 1. En **Formato de registro**, elija **CLF**. API Gateway crea un formato de registro de ejemplo. 1. Agregue `$context.integrationErrorMessage` al final del formato de registro. 1. Seleccione **Guardar**. **Para ver los registros de la API** 1. Generación de registros. Utilice un navegador o `curl` para invocar su API. ``` $curl https://api-id.execute-api.us-west-2.amazonaws.com/route ``` 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 su API HTTP. 1. En **Monitorización**, elija **Registro**. 1. Seleccione la etapa de la API para la cual habilitó el registro. 1. Elija **View logs in CloudWatch (Ver registros en CloudWatch)**. 1. Elija la última secuencia de registro para ver sus registros de API HTTP. 1. Su entrada de registro debe tener un aspecto similar a este: ![\[Entrada de registro de CloudWatch Logs que muestra el mensaje de error de integración de Lambda.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/troubleshoot-http-api-logs.png) Dado que agregamos `$context.integrationErrorMessage` al formato de registro, vemos un mensaje de error en nuestros registros que resume el problema. Los registros pueden incluir un mensaje de error diferente que indica que hay un problema con el código de función de Lambda. En ese caso, verifique su código de función de Lambda y compruebe que su función de Lambda devuelva una respuesta en el [formato necesario](http-api-develop-integrations-lambda.md#http-api-develop-integrations-lambda.response). Si los registros no incluyen un mensaje de error, agregue `$context.error.message` y `$context.error.responseType` al formato de registro para obtener más información que le ayude a solucionar problemas. En este caso, los registros muestran que API Gateway no tenía los permisos necesarios para invocar la función de Lambda. Cuando crea una integración de Lambda en la consola de API Gateway, API Gateway configura automáticamente los permisos para invocar la función de Lambda. Cuando crea una integración de Lambda mediante la AWS CLI, CloudFormation o un SDK, debe conceder permisos para que API Gateway pueda invocar la función. Los siguientes comandos [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) conceden permiso para diferentes rutas de API HTTP para invocar una función de Lambda. **Example Ejemplo: para la etapa `$default` y la ruta `$default` de una API HTTP** ``` aws lambda add-permission \ --function-name my-function \ --statement-id apigateway-invoke-permissions \ --action lambda:InvokeFunction \ --principal apigateway.amazonaws.com \ --source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/\$default/\$default" ``` **Example Ejemplo: para la etapa `prod` y la ruta `test` de una API HTTP** ``` aws lambda add-permission \ --function-name my-function \ --statement-id apigateway-invoke-permissions \ --action lambda:InvokeFunction \ --principal apigateway.amazonaws.com \ --source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/prod/*/test" ``` [Confirme la política de la función](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html) en la pestaña **Permisos** de la consola de Lambda. Intente volver a invocar su API. Debería ver la respuesta de su función de Lambda. # Solución de problemas con los autorizadores JWT de la API HTTP A continuación se le proporcionan consejos para solucionar errores y problemas que puedan surgir al utilizar los autorizadores de JSON Web Token (JWT) con API HTTP. ## Problema: mi API devuelve `401 {"message":"Unauthorized"}` Compruebe el encabezado `www-authenticate` en la respuesta de la API. El siguiente comando utiliza `curl` para enviar una solicitud a una API con un autorizador de JWT que utiliza `$request.header.Authorization` como su origen de identidad. ``` $curl -v -H "Authorization: token" https://api-id.execute-api.us-west-2.amazonaws.com/route ``` La respuesta de la API incluye un encabezado `www-authenticate`. ``` ... < HTTP/1.1 401 Unauthorized < Date: Wed, 13 May 2020 04:07:30 GMT < Content-Length: 26 < Connection: keep-alive < www-authenticate: Bearer scope="" error="invalid_token" error_description="the token does not have a valid audience" < apigw-requestid: Mc7UVioPPHcEKPA= < * Connection #0 to host api-id.execute-api.us-west-2.amazonaws.com left intact {"message":"Unauthorized"}} ``` En este caso, el encabezado `www-authenticate` muestra que el token no se emitió para un destinatario válido. Para que API Gateway autorice una solicitud, la reclamación `aud` o `client_id` de JWT debe coincidir con una de las entradas de destinatario 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`. También puede decodificar un JWT y comprobar que coincida con el emisor, el destinatario y los ámbitos que requiere su API. El sitio web [jwt.io](https://jwt.io/) puede depurar JWT en el navegador. OpenID Foundation mantiene una [lista de bibliotecas para trabajar con JWT](https://openid.net/developers/jwt-jws-jwe-jwk-and-jwa-implementations/). Para obtener más información acerca de los autorizadores de JWT, consulte [Control del acceso a API HTTP con autorizadores de JWT en API Gateway](http-api-jwt-authorizer.md).