# Extensiones de OpenAPI para API Gateway
Las extensiones de API Gateway admiten la autorización específica de AWS y las integraciones de API específicas de API Gateway para las API REST y las API HTTP. En esta sección, describimos las extensiones de API Gateway para la especificación de OpenAPI.
**sugerencia**
Para comprender cómo se utilizan las extensiones de API Gateway en una aplicación, puede utilizar la consola API Gateway para crear una API REST o API HTTP y exportarla a un archivo de definición de OpenAPI. Para obtener más información sobre cómo exportar una API, consulte [Exportación de una API REST desde API Gateway](api-gateway-export-api.md) y [Exportación de API HTTP desde API Gateway](http-api-export.md).
**Topics**
+ [Objeto x-amazon-apigateway-any-method](api-gateway-swagger-extensions-any-method.md)
+ [Objeto x-amazon-apigateway-cors](api-gateway-swagger-extensions-cors-configuration.md)
+ [Propiedad x-amazon-apigateway-api-key-source](api-gateway-swagger-extensions-api-key-source.md)
+ [Objeto de x-amazon-apigateway-auth](api-gateway-swagger-extensions-auth.md)
+ [Objeto x-amazon-apigateway-authorizer](api-gateway-swagger-extensions-authorizer.md)
+ [Propiedad x-amazon-apigateway-authtype](api-gateway-swagger-extensions-authtype.md)
+ [Propiedad x-amazon-apigateway-binary-media-types](api-gateway-swagger-extensions-binary-media-types.md)
+ [Objeto x-amazon-apigateway-documentation](api-gateway-swagger-extensions-documentation.md)
+ [x-amazon-apigateway-endpoint-access-mode](openapi-extensions-endpoint-access-mode.md)
+ [Objeto x-amazon-apigateway-endpoint-configuration](api-gateway-swagger-extensions-endpoint-configuration.md)
+ [Objeto x-amazon-apigateway-gateway-responses](api-gateway-swagger-extensions-gateway-responses.md)
+ [Objeto x-amazon-apigateway-gateway-responses.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md)
+ [Objeto x-amazon-apigateway-gateway-responses.responseParameters](api-gateway-swagger-extensions-gateway-responses.responseParameters.md)
+ [Objeto x-amazon-apigateway-gateway-responses.responseTemplates](api-gateway-swagger-extensions-gateway-responses.responseTemplates.md)
+ [x-amazon-apigateway-importexport-version](api-gateway-extensions-importexport-version.md)
+ [Objeto x-amazon-apigateway-integration](api-gateway-swagger-extensions-integration.md)
+ [Objeto x-amazon-apigateway-integrations](api-gateway-extensions-integrations.md)
+ [Objeto x-amazon-apigateway-integration.requestTemplates](api-gateway-swagger-extensions-integration-requestTemplates.md)
+ [Objeto x-amazon-apigateway-integration.requestParameters](api-gateway-swagger-extensions-integration-requestParameters.md)
+ [Objeto x-amazon-apigateway-integration.responses](api-gateway-swagger-extensions-integration-responses.md)
+ [Objeto x-amazon-apigateway-integration.response](api-gateway-swagger-extensions-integration-response.md)
+ [Objeto x-amazon-apigateway-integration.responseTemplates](api-gateway-swagger-extensions-integration-responseTemplates.md)
+ [Objeto x-amazon-apigateway-integration.responseParameters](api-gateway-swagger-extensions-integration-responseParameters.md)
+ [Objeto x-amazon-apigateway-integration.tlsConfig](api-gateway-extensions-integration-tls-config.md)
+ [x-amazon-apigateway-minimum-compression-size](api-gateway-openapi-minimum-compression-size.md)
+ [x-amazon-apigateway-policy](openapi-extensions-policy.md)
+ [Propiedad x-amazon-apigateway-request-validator](api-gateway-swagger-extensions-request-validator.md)
+ [Objeto x-amazon-apigateway-request-validators](api-gateway-swagger-extensions-request-validators.md)
+ [Objeto x-amazon-apigateway-request-validators.requestValidator](api-gateway-swagger-extensions-request-validators.requestValidator.md)
+ [x-amazon-apigateway-security-policy](openapi-extensions-security-policy.md)
+ [Propiedad x-amazon-apigateway-tag-value](api-gateway-openapi-extensions-x-amazon-apigateway-tag-value.md)
# Objeto x-amazon-apigateway-any-method
[Especifica el objeto Operation de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object) para el método catch-all `ANY` de API Gateway en un [objeto Path Item de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#path-item-object). Este objeto puede existir junto con otros objetos Operation y capturar cualquier método HTTP que no se haya declarado de forma explícita.
En la siguiente tabla se muestran las propiedades ampliadas por API Gateway. Para el resto de las propiedades del objeto Operation de OpenAPI, consulte la especificación de OpenAPI.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| isDefaultRoute | Boolean | Especifica si una ruta es la ruta \$1default. Solo se admite para API HTTP. Para obtener más información, consulte [Creación de rutas para las API de HTTP en API Gateway](http-api-develop-routes.md). |
| x-amazon-apigateway-integration | [Objeto x-amazon-apigateway-integration](api-gateway-swagger-extensions-integration.md) | Especifica la integración del método con el backend. Se trata de una propiedad extendida del objeto [Operation de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object). La integración puede ser del tipo AWS, AWS\$1PROXY, HTTP, HTTP\$1PROXY o MOCK. |
## Ejemplos de x-amazon-apigateway-any-method
En el siguiente ejemplo se integra el método `ANY` en un recurso de proxy, `{proxy+}`, con una función de Lambda, `TestSimpleProxy`.
```
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:TestSimpleProxy/invocations",
"httpMethod": "POST",
"type": "aws_proxy"
}
```
En el ejemplo siguiente se crea una ruta `$default` para una API HTTP que se integra con una función de Lambda, `HelloWorld`.
```
"/$default": {
"x-amazon-apigateway-any-method": {
"isDefaultRoute": true,
"x-amazon-apigateway-integration": {
"type": "AWS_PROXY",
"httpMethod": "POST",
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations",
"timeoutInMillis": 1000,
"connectionType": "INTERNET",
"payloadFormatVersion": 1.0
}
}
}
```
# Objeto x-amazon-apigateway-cors
Especifica la configuración de uso compartido de recursos entre orígenes (CORS) para una API HTTP. La extensión se aplica a la estructura de OpenAPI en el nivel raíz. Para obtener más información, consulte [Configuración de CORS de las API de HTTP en API Gateway](http-api-cors.md).
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| allowOrigins | Array | Especifica los orígenes permitidos. |
| allowCredentials | Boolean | Especifica si las credenciales están incluidas en la solicitud de CORS. |
| exposeHeaders | Array | Especifica los encabezados que se exponen. |
| maxAge | Integer | Especifica el número de segundos durante los que el navegador debe almacenar en caché los resultados de la solicitud preliminar. |
| allowMethods | Array | Especifica los métodos HTTP permitidos. |
| allowHeaders | Array | Especifica los encabezados permitidos. |
## Ejemplo de x-amazon-apigateway-cors
A continuación, se muestra un ejemplo de configuración de CORS para una API HTTP.
```
"x-amazon-apigateway-cors": {
"allowOrigins": [
"https://www.example.com"
],
"allowCredentials": true,
"exposeHeaders": [
"x-apigateway-header",
"x-amz-date",
"content-type"
],
"maxAge": 3600,
"allowMethods": [
"GET",
"OPTIONS",
"POST"
],
"allowHeaders": [
"x-apigateway-header",
"x-amz-date",
"content-type"
]
}
```
# Propiedad x-amazon-apigateway-api-key-source
Especifique el origen del que va a provenir la clave de la API para limitar los métodos de API que solicitan claves. Esta propiedad de nivel de API es de tipo `String`. Para obtener más información sobre cómo configurar un método para exigir una clave de API, consulte [Configuración de un método para usar claves de API con una definición de OpenAPI](api-key-usage-plan-oas.md).
Especifique el origen de la clave de la API en las solicitudes. Los valores válidos son:
+ `HEADER` para recibir la clave de la API desde el encabezado `X-API-Key` de una solicitud.
+ `AUTHORIZER` para recibir la clave de la API de `UsageIdentifierKey` desde un autorizador de Lambda (que anteriormente se denominaba autorizador personalizado).
## Ejemplo de x-amazon-apigateway-api-key-source
En el siguiente ejemplo, el encabezado `X-API-Key` se establece como origen de las claves de la API.
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"title" : "Test1"
},
"schemes" : [ "https" ],
"basePath" : "/import",
"x-amazon-apigateway-api-key-source" : "HEADER",
.
.
.
}
```
------
#### [ OpenAPI 3.0.1 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Test1"
},
"servers" : [ {
"url" : "/{basePath}",
"variables" : {
"basePath" : {
"default" : "import"
}
}
} ],
"x-amazon-apigateway-api-key-source" : "HEADER",
.
.
.
}
```
------
# Objeto de x-amazon-apigateway-auth
Define un tipo de autorización que se aplicará para la autorización de invocaciones de métodos en API Gateway.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| type | string | Especifica el tipo de autorización. Especifique "NONE" para acceso abierto. Especifique "AWS\$1IAM" para usar permisos de IAM. En los valores, no se distingue entre mayúsculas y minúsculas. |
## Ejemplo de x-amazon-apigateway-auth
En el ejemplo siguiente se establece el tipo de autorización de un método de API.
------
#### [ OpenAPI 3.0.1 ]
```
{
"openapi": "3.0.1",
"info": {
"title": "openapi3",
"version": "1.0"
},
"paths": {
"/protected-by-iam": {
"get": {
"x-amazon-apigateway-auth": {
"type": "AWS_IAM"
}
}
}
}
}
```
------
# Objeto x-amazon-apigateway-authorizer
Define un autorizador de Lambda, el grupo de usuarios de Amazon Cognito o autorizador de JWT que se debe aplicar a la autorización de invocaciones de método en API Gateway. Esta extensión se aplica a la definición de seguridad en [OpenAPI 2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#security-definitions-object) y [OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#security-scheme-object).
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| type | string | El tipo del autorizador. Esta propiedad es obligatoria. Para las API REST, especifique `token` para un autorizador con la identidad del intermediario incrustada en un authorization token. Especifique `request` para un autorizador con la identidad del intermediario incluida en los parámetros de solicitud. Especifique `cognito_user_pools` para un autorizador que utilice un grupo de usuarios de Amazon Cognito para controlar el acceso a la API. Para API HTTP, especifique `request` para un autorizador de Lambda con la identidad del intermediario incluida en los parámetros de solicitud. Especifique `jwt` para un autorizador de JWT. |
| authorizerUri | string | El identificador uniforme de recursos (URI) de la función de Lambda del autorizador. La sintaxis es la siguiente: "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:auth_function_name/invocations"
|
| authorizerCredentials | string | Las credenciales necesarias para invocar el autorizador, si existen, en forma de ARN de un rol de ejecución de IAM. Por ejemplo, "arn:aws:iam::*id-cuenta*:*rol\$1de\$1IAM*". |
| authorizerPayloadFormatVersion | string | Para las API HTTP, especifica el formato de los datos que API Gateway envía a un autorizador Lambda y cómo API Gateway interpreta la respuesta de Lambda. Para obtener más información, consulte [Versión de formato de carga](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format). |
| enableSimpleResponses | Boolean | Para API HTTP, especifica si un autorizador de `request` devuelve un valor booleano o una política de IAM. Solo se admite para autorizadores con una `authorizerPayloadFormatVersion` de `2.0`. Si está habilitada, la función del autorizador de Lambda devuelve un valor booleano. Para obtener más información, consulte [Respuesta de función de Lambda para el formato 2.0](http-api-lambda-authorizer.md#http-api-lambda-authorizer.v2). |
| identitySource | string | Lista separada por comas de las expresiones de mapeo de los parámetros de solicitud como en la fuente de identidad. Aplicable solo para el autorizador del tipo `request` y `jwt`. |
| jwtConfiguration | Object | Especifica el emisor y los destinatarios de un autorizador de JWT. Para obtener más información, consulte [JWTConfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) en la Referencia de la API de API Gateway versión 2. Solo se admite para API HTTP. |
| identityValidationExpression | string | Una expresión regular para validar el token y la identidad de entrada. Por ejemplo, "^ x- [a-z]\$1". Compatible solo para autorizadores `TOKEN` para API de REST. |
| authorizerResultTtlInSeconds | string | Número de segundos durante los que se almacena en caché el resultado del autorizador. |
| providerARNs | Matriz de string | Una lista de los ARN de grupos de usuarios de Amazon Cognito para `COGNITO_USER_POOLS`. |
## Ejemplos de x-amazon-apigateway-authorizer para API REST
El siguiente ejemplo de definiciones de seguridad de OpenAPI especifica un autorizador de Lambda del tipo "token" denominado `test-authorizer`.
```
"securityDefinitions" : {
"test-authorizer" : {
"type" : "apiKey", // Required and the value must be "apiKey" for an API Gateway API.
"name" : "Authorization", // The name of the header containing the authorization token.
"in" : "header", // Required and the value must be "header" for an API Gateway API.
"x-amazon-apigateway-authtype" : "custom", // Specifies the authorization mechanism for the client.
"x-amazon-apigateway-authorizer" : { // An API Gateway Lambda authorizer definition
"type" : "token", // Required property and the value must "token"
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:function-name/invocations",
"authorizerCredentials" : "arn:aws:iam::account-id:role",
"identityValidationExpression" : "^x-[a-z]+",
"authorizerResultTtlInSeconds" : 60
}
}
}
```
El siguiente fragmento del objeto de operación de OpenAPI establece el método `GET /http` para utilizar el autorizador de Lambda precedente.
```
"/http" : {
"get" : {
"responses" : { },
"security" : [ {
"test-authorizer" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"httpMethod" : "GET",
"uri" : "http://api.example.com"
}
}
}
```
El siguiente ejemplo de definiciones de seguridad de OpenAPI especifica un autorizador de Lambda del tipo "request" con un único parámetro de encabezado (`auth`) como fuente de identidad. El elemento `securityDefinitions` se denomina `request_authorizer_single_header`.
```
"securityDefinitions": {
"request_authorizer_single_header" : {
"type" : "apiKey",
"name" : "auth", // The name of a single header or query parameter as the identity source.
"in" : "header", // The location of the single identity source request parameter. The valid value is "header" or "query"
"x-amazon-apigateway-authtype" : "custom",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "method.request.header.auth", // Request parameter mapping expression of the identity source. In this example, it is the 'auth' header.
"authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
"authorizerResultTtlInSeconds" : 300
}
}
}
```
El siguiente ejemplo de definiciones de seguridad de OpenAPI especifica un autorizador de Lambda del tipo "request" con un encabezado (`HeaderAuth1`) y un parámetro de cadena de consulta `QueryString1` como fuentes de identidad.
```
"securityDefinitions": {
"request_authorizer_header_query" : {
"type" : "apiKey",
"name" : "Unused", // Must be "Unused" for multiple identity sources or non header or query type of request parameters.
"in" : "header", // Must be "header" for multiple identity sources or non header or query type of request parameters.
"x-amazon-apigateway-authtype" : "custom",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "method.request.header.HeaderAuth1, method.request.querystring.QueryString1", // Request parameter mapping expressions of the identity sources.
"authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
"authorizerResultTtlInSeconds" : 300
}
}
}
```
El siguiente ejemplo de definiciones de seguridad de OpenAPI especifica un autorizador de Lambda de API Gateway del tipo "request" con una única variable de etapa (`stage`) como fuente de identidad.
```
"securityDefinitions": {
"request_authorizer_single_stagevar" : {
"type" : "apiKey",
"name" : "Unused", // Must be "Unused", for multiple identity sources or non header or query type of request parameters.
"in" : "header", // Must be "header", for multiple identity sources or non header or query type of request parameters.
"x-amazon-apigateway-authtype" : "custom",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "stageVariables.stage", // Request parameter mapping expression of the identity source. In this example, it is the stage variable.
"authorizerCredentials" : "arn:aws:iam::123456789012:role/AWSepIntegTest-CS-LambdaRole",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:APIGateway-Request-Authorizer:vtwo/invocations",
"authorizerResultTtlInSeconds" : 300
}
}
}
```
En el siguiente ejemplo de definición de seguridad de OpenAPI se especifica un grupo de usuarios de Amazon Cognito como autorizador.
```
"securityDefinitions": {
"cognito-pool": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "cognito_user_pools",
"x-amazon-apigateway-authorizer": {
"type": "cognito_user_pools",
"providerARNs": [
"arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-east-1_ABC123"
]
}
}
```
En el siguiente fragmento de objeto de operación de OpenAPI se establece `GET /http` para utilizar el grupo de usuarios anterior de Amazon Cognito como autorizador, sin ámbitos personalizados.
```
"/http" : {
"get" : {
"responses" : { },
"security" : [ {
"cognito-pool" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"httpMethod" : "GET",
"uri" : "http://api.example.com"
}
}
}
```
## Ejemplos de x-amazon-apigateway-authorizer para API HTTP
En el siguiente ejemplo de OpenAPI 3.0 se crea un autorizador de JWT para una API HTTP que utiliza Amazon Cognito como proveedor de identidad, con el encabezado `Authorization` como origen de identidad.
```
"securitySchemes": {
"jwt-authorizer-oauth": {
"type": "oauth2",
"x-amazon-apigateway-authorizer": {
"type": "jwt",
"jwtConfiguration": {
"issuer": "https://cognito-idp.region.amazonaws.com/userPoolId",
"audience": [
"audience1",
"audience2"
]
},
"identitySource": "$request.header.Authorization"
}
}
}
```
En el siguiente ejemplo de OpenAPI 3.0 se crea el mismo autorizador de JWT que en el ejemplo anterior. Sin embargo, en este ejemplo se utiliza la propiedad `openIdConnectUrl` de OpenAPI para detectar automáticamente el emisor. La `openIdConnectUrl` debe estar completamente formada.
```
"securitySchemes": {
"jwt-authorizer-autofind": {
"type": "openIdConnect",
"openIdConnectUrl": "https://cognito-idp.region.amazonaws.com/userPoolId/.well-known/openid-configuration",
"x-amazon-apigateway-authorizer": {
"type": "jwt",
"jwtConfiguration": {
"audience": [
"audience1",
"audience2"
]
},
"identitySource": "$request.header.Authorization"
}
}
}
```
En el ejemplo siguiente se crea un autorizador Lambda para una API HTTP. Este autorizador de ejemplo utiliza el encabezado `Authorization` como su origen de identidad. El autorizador utiliza la versión `2.0` del formato de carga útil y devuelve el valor booleano, ya que `enableSimpleResponses` está establecido en `true`.
```
"securitySchemes" : {
"lambda-authorizer" : {
"type" : "apiKey",
"name" : "Authorization",
"in" : "header",
"x-amazon-apigateway-authorizer" : {
"type" : "request",
"identitySource" : "$request.header.Authorization",
"authorizerUri" : "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:function-name/invocations",
"authorizerPayloadFormatVersion" : "2.0",
"authorizerResultTtlInSeconds" : 300,
"enableSimpleResponses" : true
}
}
}
```
# Propiedad x-amazon-apigateway-authtype
Para las API REST, esta extensión se puede utilizar a fin definir un tipo personalizado de un autorizador de Lambda. En este caso, el valor es de forma libre. Por ejemplo, una API puede tener varios autorizadores de Lambda que utilizan diferentes esquemas internos. Puede utilizar esta extensión para identificar el esquema interno de un autorizador de Lambda.
Más comúnmente, en API HTTP y API REST, también se puede usar como una forma de definir la autorización de IAM en varias operaciones que comparten el mismo esquema de seguridad. En este caso, el término `awsSigv4` es un término reservado, junto con cualquier término prefijado por `aws`.
Esta extensión se aplica al esquema de seguridad de tipo `apiKey` en [OpenAPI 2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#security-scheme-object) y [OpenAPI 3.](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#security-scheme-object)
## Ejemplo de x-amazon-apigateway-authtype
El siguiente ejemplo de OpenAPI 3 define la autorización de IAM en varios recursos en una API REST o API HTTP:
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "openapi3",
"version" : "1.0"
},
"paths" : {
"/operation1" : {
"get" : {
"responses" : {
"default" : {
"description" : "Default response"
}
},
"security" : [ {
"sigv4Reference" : [ ]
} ]
}
},
"/operation2" : {
"get" : {
"responses" : {
"default" : {
"description" : "Default response"
}
},
"security" : [ {
"sigv4Reference" : [ ]
} ]
}
}
},
"components" : {
"securitySchemes" : {
"sigv4Reference" : {
"type" : "apiKey",
"name" : "Authorization",
"in" : "header",
"x-amazon-apigateway-authtype": "awsSigv4"
}
}
}
}
```
El siguiente ejemplo de OpenAPI 3 define un autorizador de Lambda con un esquema personalizado para una API REST:
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "openapi3 for REST API",
"version" : "1.0"
},
"paths" : {
"/protected-by-lambda-authorizer" : {
"get" : {
"responses" : {
"200" : {
"description" : "Default response"
}
},
"security" : [ {
"myAuthorizer" : [ ]
} ]
}
}
},
"components" : {
"securitySchemes" : {
"myAuthorizer" : {
"type" : "apiKey",
"name" : "Authorization",
"in" : "header",
"x-amazon-apigateway-authorizer" : {
"identitySource" : "method.request.header.Authorization",
"authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:function-name/invocations",
"authorizerResultTtlInSeconds" : 300,
"type" : "request",
"enableSimpleResponses" : false
},
"x-amazon-apigateway-authtype": "Custom scheme with corporate claims"
}
}
},
"x-amazon-apigateway-importexport-version" : "1.0"
}
```
## Véase también
[authorizer.authType](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#apigw-Type-Authorizer-authType)
# Propiedad x-amazon-apigateway-binary-media-types
Especifica la lista de tipos de medios binarios que se admiten en API Gateway, como `application/octet-stream` y `image/jpeg`. Esta extensión es una matriz JSON. Debe incluirse como una extensión de proveedor de nivel superior al documento de OpenAPI.
## Ejemplo de x-amazon-apigateway-binary-media-types
El siguiente ejemplo muestra el orden de búsqueda de codificación de una API.
```
"x-amazon-apigateway-binary-media-types": [ "application/octet", "image/jpeg" ]
```
# Objeto x-amazon-apigateway-documentation
Define las piezas de documentación que se van a importar a API Gateway. Este objeto es un objeto JSON que contiene una matriz de instancias `DocumentationPart`.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| documentationParts | Array | Una matriz de instancias `DocumentationPart` exportadas o importadas. |
| version | String | El identificador de versión de la snapshot de las piezas de documentación exportadas. |
## Ejemplo de x-amazon-apigateway-documentation
El siguiente ejemplo de la extensión de API Gateway para OpenAPI define instancias `DocumentationParts` para que se importen o exporten desde una API en API Gateway.
```
{ ...
"x-amazon-apigateway-documentation": {
"version": "1.0.3",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"info": {
"description": "API info description 4",
"version": "API info version 3"
}
}
},
{
… // Another DocumentationPart instance
}
]
}
}
```
# x-amazon-apigateway-endpoint-access-mode
Especifica el modo de acceso de punto de conexión para una API de REST o un nombre de dominio personalizado. Para obtener más información sobre el modo de acceso de punto de conexión, consulte [Modo de acceso de punto de conexión](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode).
## `x-amazon-apigateway-endpoint-access-mode`Ejemplo de
En el ejemplo siguiente se especifica el modo de acceso de punto de conexión estricto.
```
"x-amazon-apigateway-endpoint-access-mode": "STRICT"
```
# Objeto x-amazon-apigateway-endpoint-configuration
Especifica detalles de la configuración del punto de enlace para una API. Esta extensión es una propiedad extendida del objeto [Operation de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#operation-object). Este objeto debe estar presente en las [extensiones de proveedor de nivel superior](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#specification-extensions) de Swagger 2.0. Para OpenAPI 3.0, debe estar presente en las extensiones de proveedor del [objeto Server](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#server-object).
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| disableExecuteApiEndpoint | Booleano | Especifica si los clientes pueden invocar la API mediante el punto de enlace `execute-api` predeterminado. De forma predeterminada, los clientes pueden invocar su API con el punto de enlace `https://{api_id}.execute-api.{region}.amazonaws.com` predeterminado. Para exigir que los clientes utilicen un nombre de dominio personalizado para invocar su API, especifique `true`. |
| vpcEndpointIds | Matriz de String | Una lista de identificadores de VpcEndpoint en la que crear registros de alias de Route 53 para una API REST. Solo es compatible con las API REST del tipo de punto de enlace `PRIVATE`. |
| ipAddressType | string | Los tipos de direcciones IP que pueden invocar una API HTTP. Utilice `ipv4` para permitir que los tipos de direcciones IPv4 invoquen una API HTTP. Utilice `dualstack` para permitir que los tipos de direcciones IPv4 e IPv6 invoquen una API HTTP. Solo se admite para las API HTTP. |
## Ejemplos de x-amazon-apigateway-endpoint-configuration
En el siguiente ejemplo se asocian puntos de enlace de la VPC especificados a la API REST.
```
"x-amazon-apigateway-endpoint-configuration": {
"vpcEndpointIds": ["vpce-0212a4ababd5b8c3e", "vpce-01d622316a7df47f9"]
}
```
En el ejemplo siguiente se desactiva el punto de enlace predeterminado de una API.
```
"x-amazon-apigateway-endpoint-configuration": {
"disableExecuteApiEndpoint": true
}
```
El siguiente ejemplo establece el tipo de dirección IP en pila doble para una API HTTP.
```
"x-amazon-apigateway-endpoint-configuration": {
"ipAddressType": "dualstack"
}
```
# Objeto x-amazon-apigateway-gateway-responses
Define las respuestas de gateway de una API como un mapa de pares de clave-valor de cadena a [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). La extensión se aplica a la estructura de OpenAPI en el nivel raíz.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| responseType | [x-amazon-apigateway-gateway-responses.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md) | Un atributo `GatewayResponse` para el elemento *responseType* especificado. |
## Ejemplo de x-amazon-apigateway-gateway-responses
El siguiente ejemplo de extensión de API Gateway para OpenAPI define un mapa de [GatewayResponses](https://docs.aws.amazon.com/apigateway/latest/api/API_GetGatewayResponses.html) que contiene dos instancias de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), una para el tipo `DEFAULT_4XX` y otra para el tipo `INVALID_API_KEY`.
```
{
"x-amazon-apigateway-gateway-responses": {
"DEFAULT_4XX": {
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'domain.com'"
},
"responseTemplates": {
"application/json": "{\"message\": test 4xx b }"
}
},
"INVALID_API_KEY": {
"statusCode": "429",
"responseTemplates": {
"application/json": "{\"message\": test forbidden }"
}
}
}
}
```
# Objeto x-amazon-apigateway-gateway-responses.gatewayResponse
Define una respuesta de gateway de un tipo de respuesta determinado, incluido el código de estado, todos los parámetros de respuesta aplicables o las plantillas de respuesta.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| responseParameters | [x-amazon-apigateway-gateway-responses.responseParameters](api-gateway-swagger-extensions-gateway-responses.responseParameters.md) | Especifica los parámetros de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), es decir, los parámetros de encabezado. Los valores de los parámetros pueden tomar cualquier valor de [parámetro de solicitud](rest-api-parameter-mapping.md) entrante o un valor personalizado estático. |
| responseTemplates | [x-amazon-apigateway-gateway-responses.responseTemplates](api-gateway-swagger-extensions-gateway-responses.responseTemplates.md) | Especifica las plantillas de mapeo de la respuesta de gateway. El motor de VTL no procesa las plantillas. |
| statusCode | string | Un código de estado HTTP para la respuesta de gateway. |
## Ejemplo de x-amazon-apigateway-gateway-responses.gatewayResponse
El siguiente ejemplo de extensión de API Gateway para OpenAPI define un objeto [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) para personalizar la respuesta `INVALID_API_KEY` y devolver el código de estado `456`, el valor del encabezado `api-key` de la solicitud entrante y un mensaje `"Bad api-key"`.
```
"INVALID_API_KEY": {
"statusCode": "456",
"responseParameters": {
"gatewayresponse.header.api-key": "method.request.header.api-key"
},
"responseTemplates": {
"application/json": "{\"message\": \"Bad api-key\" }"
}
}
```
# Objeto x-amazon-apigateway-gateway-responses.responseParameters
Define un mapa de cadena a cadena de pares de clave-valor para generar parámetros de respuesta de gateway a partir de los parámetros de la solicitud entrante o mediante cadenas literales. Compatible solo con API REST.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| gatewayresponse.param-position.param-name | string | `param-position` puede ser `header`, `path` o `querystring`. Para obtener más información, consulte [Asignación de parámetros para las API de REST en API Gateway](rest-api-parameter-mapping.md). |
## Ejemplo de x-amazon-apigateway-gateway-responses.responseParameters
El siguiente ejemplo de extensión de OpenAPI muestra una expresión de asignación de parámetros de respuesta [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) para habilitar la compatibilidad de CORS con recursos en los dominios `*.example.domain`.
```
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": '*.example.domain',
"gatewayresponse.header.from-request-header" : method.request.header.Accept,
"gatewayresponse.header.from-request-path" : method.request.path.petId,
"gatewayresponse.header.from-request-query" : method.request.querystring.qname
}
```
# Objeto x-amazon-apigateway-gateway-responses.responseTemplates
Define las plantillas de asignación de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), como un mapa de cadena a cadena de pares de clave-valor, para una respuesta de gateway especificada. En cada par clave-valor, la clave es el tipo de contenido. Por ejemplo, "application/json" y el valor es una plantilla de mapeo stringified para sustituciones de variables simples. El motor de [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) no procesa una plantilla de mapeo de `GatewayResponse`.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| content-type | string | Una plantilla de mapeo de cuerpo de `GatewayResponse` que admite únicamente sustituciones de variables sencillas para personalizar un cuerpo de respuesta de gateway. |
## Ejemplo de x-amazon-apigateway-gateway-responses.responseTemplates
El siguiente ejemplo de extensión de OpenAPI muestra una plantilla de asignación de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) para personalizar una respuesta de error generada por API Gateway en un formato específico de la aplicación.
```
"responseTemplates": {
"application/json": "{ \"message\": $context.error.messageString, \"type\":$context.error.responseType, \"statusCode\": '488' }"
}
```
El siguiente ejemplo de extensión de OpenAPI muestra una plantilla de asignación de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) para invalidar una respuesta de error generada por API Gateway con un mensaje de error estático.
```
"responseTemplates": {
"application/json": "{ \"message\": 'API-specific errors' }"
}
```
# x-amazon-apigateway-importexport-version
Especifica la versión del algoritmo de importación y exportación de API Gateway para las API HTTP. Actualmente el único valor admitido es `1.0`. Para obtener más información, consulte [exportVersion](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#w125aab9c10b3b1b4) en la *Referencia de la API de la API Gateway versión 2*.
## Ejemplo de x-amazon-apigateway-importexport-version
En el ejemplo siguiente se establece la versión de importación y exportación en `1.0`.
```
{
"openapi": "3.0.1",
"x-amazon-apigateway-importexport-version": "1.0",
"info": { ...
```
# Objeto x-amazon-apigateway-integration
Especifica los detalles de la integración del backend utilizada para este método. Esta extensión es una propiedad extendida del objeto [Operation de OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object). El resultado es un objeto de [integración de API Gateway](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| cacheKeyParameters | Matriz de string | Una lista de parámetros de la solicitud cuyos valores se van a almacenar en caché. |
| cacheNamespace | string | Un grupo de etiquetas específicas de la API de parámetros almacenados en caché relacionados. |
| connectionId | string | ID de un enlace [VpcLink](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html) de la integración privada. |
| connectionType | string | Tipo de conexión de la integración. El valor válido es "VPC\$1LINK" para la integración privada o "INTERNET" para los demás casos. |
| credentials | string | Para las credenciales basadas en roles de AWS IAM, especifique el ARN de un rol de IAM. Si no se especifica, las credenciales adoptan de manera predeterminada los permisos basados en recursos que se deben añadir manualmente para permitir a la API tener acceso al recurso. Para obtener más información, consulte [Concesión de permisos mediante una política de recursos](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html#intro-permission-model-access-policy). Nota: Cuando utilice credenciales de IAM, asegúrese de que los [puntos de enlace regionales STS de AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html) están habilitados para la región en la que se implementa esta API para obtener un rendimiento óptimo. |
| contentHandling | string | Tipos de conversión de codificación de la carga de solicitud. Los valores válidos son 1) CONVERT\$1TO\$1TEXT, para convertir una carga binaria en una cadena codificada en base64 o para convertir una carga de texto en una cadena codificada en utf-8 o para transferir la carga de texto de forma nativa sin modificaciones, y 2) CONVERT\$1TO\$1BINARY, para convertir una carga de texto en un blob descodificado en base64 o para transferir una carga binaria de forma nativa sin modificaciones. |
| httpMethod | string | El método HTTP utilizado en la solicitud de integración. Para las invocaciones de funciones de Lambda, el valor debe ser POST. |
| integrationSubtype | string | Especifica el subtipo de integración para una integración del servicio de AWS. Solo se admite para API HTTP. Para obtener información sobre los subtipos de integración compatibles, consulte [Referencia del subtipo de integración](http-api-develop-integrations-aws-services-reference.md). |
| integrationTarget | string | El oyente de ALB o NLB al que se va a enviar la solicitud. Compatible solo con integraciones privadas que utilizan enlaces de VPC V2. Para obtener más información, consulte [Configuración de enlaces de VPC V2 en API Gateway](apigateway-vpc-links-v2.md). |
| passthroughBehavior | string | Especifica cómo se pasa una carga de solicitud de tipo de contenido sin asignar a través de la solicitud de integración sin modificación. Los valores admitidos son when\$1no\$1templates, when\$1no\$1match y never. Para obtener más información, consulte [Integration.passthroughBehavior](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#passthroughBehavior). |
| payloadFormatVersion | string | Especifica el formato de la carga enviada a una integración. Es necesario para las API HTTP. Para las API HTTP, los valores admitidos para las integraciones de proxy Lambda son 1.0 y 2.0. Para el resto de integraciones, 1.0 es el único valor admitido. Para obtener más información, consulte [Creación de integraciones de proxy de AWS Lambda para las API de HTTP en API Gateway](http-api-develop-integrations-lambda.md) y [Referencia del subtipo de integración](http-api-develop-integrations-aws-services-reference.md). |
| requestParameters | [Objeto x-amazon-apigateway-integration.requestParameters](api-gateway-swagger-extensions-integration-requestParameters.md) | Para API REST, especifica las asignaciones de los parámetros de solicitud de método a los parámetros de solicitud de integración. Los parámetros de solicitud admitidos son `querystring`, `path`, `header` y `body`. Para las API HTTP, los parámetros de solicitud son un mapeo de clave-valor que especifica los parámetros que se pasan a integraciones de `AWS_PROXY` con `integrationSubtype` especificado. Puede proporcionar valores estáticos o datos de solicitud de mapeo, variables de etapa o variables de contexto que se evalúan en tiempo de ejecución. Para obtener más información, consulte [Creación de integraciones de servicio de AWS para las API de HTTP en API Gateway](http-api-develop-integrations-aws-services.md). |
| requestTemplates | [Objeto x-amazon-apigateway-integration.requestTemplates](api-gateway-swagger-extensions-integration-requestTemplates.md) | Plantillas de mapeo para una carga de solicitud de tipos MIME especificados. |
| responses | [Objeto x-amazon-apigateway-integration.responses](api-gateway-swagger-extensions-integration-responses.md) | Define las respuestas del método y especifica las asignaciones de parámetros o de carga deseadas desde respuestas de integración a respuestas de método. |
| responseTransferMode | string | El modo de transferencia de respuesta de la integración. Use BUFFERED para que API Gateway espere a recibir la respuesta completa antes de iniciar la transmisión. Use STREAM para que API Gateway envíe de vuelta respuestas parciales al cliente a medida que estén disponibles. Para obtener más información, consulte [Transmisión de la respuesta de integración para las integraciones de proxy en API Gateway](response-transfer-mode.md). |
| timeoutInMillis | integer | Tiempos de espera de la integración comprendidos entre 50 ms y 29.000 ms. |
| type | string | El tipo de integración con el backend especificado. Los valores válidos son: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration.html) Para obtener más información sobre los tipos de integración, consulte [integration:type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type). |
| tlsConfig | [Objeto x-amazon-apigateway-integration.tlsConfig](api-gateway-extensions-integration-tls-config.md) | Especifica la configuración de TLS para una integración. |
| uri | string | El URI del punto de enlace del backend. Para integraciones del tipo aws, este es un valor de ARN. Para la integración HTTP, esta es la dirección URL del punto de enlace HTTP incluido el esquema https o http. |
## Ejemplos de x-amazon-apigateway-integration
En API HTTP, puede definir integraciones en la sección de componentes de la definición de OpenAPI. Para obtener más información, consulte [Objeto x-amazon-apigateway-integrations](api-gateway-extensions-integrations.md).
```
"x-amazon-apigateway-integration": {
"$ref": "#/components/x-amazon-apigateway-integrations/integration1"
}
```
El siguiente ejemplo se crea una integración con una función de Lambda. Para fines de demostración, en las plantillas de asignación de ejemplo en `requestTemplates` y `responseTemplates` de los ejemplos que aparecen a continuación se asume que se aplica la siguiente carga con formato JSON: `{ "name":"value_1", "key":"value_2", "redirect": {"url" :"..."} }` para generar una salida JSON `{ "stage":"value_1", "user-id":"value_2" }` o una salida XML `value_1`.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"uri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:012345678901:function:HelloWorld/invocations",
"httpMethod" : "POST",
"credentials" : "arn:aws:iam::012345678901:role/apigateway-invoke-lambda-exec-role",
"requestTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
},
"requestParameters" : {
"integration.request.path.stage" : "method.request.querystring.version",
"integration.request.querystring.provider" : "method.request.querystring.vendor"
},
"cacheNamespace" : "cache namespace",
"cacheKeyParameters" : [],
"responses" : {
"2\\d{2}" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.requestId" : "integration.response.header.cid"
},
"responseTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
}
},
"302" : {
"statusCode" : "302",
"responseParameters" : {
"method.response.header.Location" : "integration.response.body.redirect.url"
}
},
"default" : {
"statusCode" : "400",
"responseParameters" : {
"method.response.header.test-method-response-header" : "'static value'"
}
}
}
}
```
Tenga en cuenta que las comillas dobles (") de la cadena JSON en las plantillas de mapeo deben incluirse en una secuencia de escape (\$1").
# Objeto x-amazon-apigateway-integrations
Define una colección de integraciones. Puede definir integraciones en la sección de componentes de la definición de OpenAPI y reutilizar las integraciones para varias rutas. Solo se admite para API HTTP.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| integration | [Objeto x-amazon-apigateway-integration](api-gateway-swagger-extensions-integration.md) | Una colección de objetos de integración. |
## Ejemplo de x-amazon-apigateway-integrations
En el ejemplo siguiente se crea una API HTTP que define dos integraciones y se hace referencia a las integraciones mediante `$ref": "#/components/x-amazon-apigateway-integrations/integration-name`.
```
{
"openapi": "3.0.1",
"info":
{
"title": "Integrations",
"description": "An API that reuses integrations",
"version": "1.0"
},
"servers": [
{
"url": "https://example.com/{basePath}",
"description": "The production API server",
"variables":
{
"basePath":
{
"default": "example/path"
}
}
}],
"paths":
{
"/":
{
"get":
{
"x-amazon-apigateway-integration":
{
"$ref": "#/components/x-amazon-apigateway-integrations/integration1"
}
}
},
"/pets":
{
"get":
{
"x-amazon-apigateway-integration":
{
"$ref": "#/components/x-amazon-apigateway-integrations/integration1"
}
}
},
"/checkout":
{
"get":
{
"x-amazon-apigateway-integration":
{
"$ref": "#/components/x-amazon-apigateway-integrations/integration2"
}
}
}
},
"components": {
"x-amazon-apigateway-integrations":
{
"integration1":
{
"type": "aws_proxy",
"httpMethod": "POST",
"uri": "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"passthroughBehavior": "when_no_templates",
"payloadFormatVersion": "1.0"
},
"integration2":
{
"type": "aws_proxy",
"httpMethod": "POST",
"uri": "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:example-function/invocations",
"passthroughBehavior": "when_no_templates",
"payloadFormatVersion" : "1.0"
}
}
}
}
```
# Objeto x-amazon-apigateway-integration.requestTemplates
Especifica las plantillas de mapeo de una carga de solicitud de los tipos MIME especificados.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| MIME type | string | Un ejemplo de tipo MIME es `application/json`. Para obtener información acerca de la creación de una plantilla de mapeo, consulte [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md). |
## Ejemplo de x-amazon-apigateway-integration.requestTemplates
El siguiente ejemplo especifica las plantillas de mapeo de una carga de solicitud de los tipos MIME `application/json` y `application/xml`.
```
"requestTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
}
```
# Objeto x-amazon-apigateway-integration.requestParameters
Para API REST, especifica las asignaciones de los parámetros de solicitud de método designados a los parámetros de solicitud de integración. Los parámetros de solicitud de método deben estar definidos para poder hacer referencia a ellos.
Para API HTTP, especifica los parámetros que se pasan a integraciones de `AWS_PROXY` con un `integrationSubtype` especificado.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| integration.request.. | string | Para API REST, el valor es típicamente un parámetro de solicitud de método predefinido con el formato `method.request..`, donde `` puede ser `querystring`, `path`, `header` o `body`. Sin embargo, `$context.VARIABLE_NAME`, `$stageVariables.VARIABLE_NAME`, y `STATIC_VALUE` son también válidas. Para el parámetro `body`, `` es una expresión de ruta JSON sin el prefijo `$.` |
| parameter | string | Para las API HTTP, los parámetros de solicitud son un mapeo de clave-valor que especifica los parámetros que se pasan a integraciones de `AWS_PROXY` con `integrationSubtype` especificado. Puede proporcionar valores estáticos o datos de solicitud de mapeo, variables de etapa o variables de contexto que se evalúan en tiempo de ejecución. Para obtener más información, consulte [Creación de integraciones de servicio de AWS para las API de HTTP en API Gateway](http-api-develop-integrations-aws-services.md). |
## `x-amazon-apigateway-integration.requestParameters`Ejemplo de
El siguiente ejemplo de asignaciones de parámetros de solicitud traduce la consulta (`version`), el encabezado, (`x-user-id`) y los parámetros de ruta (`service`) de la solicitud de método en la consulta (`stage`), encabezado (`x-userid`) y los parámetros de ruta (`op`) de la solicitud de integración, respectivamente.
**nota**
Si está creando recursos a través de OpenAPI o CloudFormation, los valores estáticos deben escribirse entre comillas simples.
Para añadir este valor desde la consola, escriba `application/json` en el cuadro, sin las comillas.
```
"requestParameters" : {
"integration.request.querystring.stage" : "method.request.querystring.version",
"integration.request.header.x-userid" : "method.request.header.x-user-id",
"integration.request.path.op" : "method.request.path.service"
},
```
# Objeto x-amazon-apigateway-integration.responses
Define las respuestas del método y especifica las asignaciones de parámetros o de carga desde respuestas de integración a respuestas de método.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| Patrón de estado de respuesta | [Objeto x-amazon-apigateway-integration.response](api-gateway-swagger-extensions-integration-response.md) | Ya sea una expresión regular utilizada para hacer coincidir la respuesta de integración con la respuesta del método, o `default` para detectar cualquier respuesta que no haya configurado. Para las integraciones HTTP, la RegEx se aplica al código de estado de la respuesta de integración. Para las invocaciones de Lambda, la expresión regular se aplica al campo `errorMessage` del objeto de información del error que devuelve AWS Lambda como un cuerpo de respuesta de error cuando la ejecución de la función de Lambda produce una excepción. El nombre de propiedad *Patrón de estado de respuesta* hace referencia a un código de estado de respuesta o a una expresión regular que describe un grupo de códigos de estado de respuesta. No se corresponde con ningún identificador de un recurso [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) en la API REST de API Gateway. |
## `x-amazon-apigateway-integration.responses`Ejemplo de
El siguiente ejemplo muestra una lista de respuestas `2xx` y `302`. Para la respuesta `2xx`, la respuesta del método se asigna desde la carga de la respuesta de integración del tipo MIME `application/json` o `application/xml`. Esta respuesta utiliza las plantillas de mapeo proporcionadas. Para la respuesta `302`, la respuesta del método devuelve un encabezado `Location` cuyo valor se obtiene de la propiedad `redirect.url` de la carga de la respuesta de integración.
```
"responses" : {
"2\\d{2}" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
}
},
"302" : {
"statusCode" : "302",
"responseParameters" : {
"method.response.header.Location": "integration.response.body.redirect.url"
}
}
}
```
# Objeto x-amazon-apigateway-integration.response
Define una respuesta y especifica asignaciones de parámetros o asignaciones de carga desde la respuesta de integración a la respuesta del método.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| statusCode | string | Código de estado HTTP para la respuesta de método (por ejemplo,, `"200"`. Se debe corresponder con una respuesta coincidente en el campo [OpenAPI Operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object) `responses`. |
| responseTemplates | [Objeto x-amazon-apigateway-integration.responseTemplates](api-gateway-swagger-extensions-integration-responseTemplates.md) | Especifica las plantillas de mapeo específicas del tipo MIME para la carga de la respuesta. |
| responseParameters | [Objeto x-amazon-apigateway-integration.responseParameters](api-gateway-swagger-extensions-integration-responseParameters.md) | Especifica las asignaciones de parámetros para la respuesta. Solo los parámetros `header` y `body` de la respuesta de integración se pueden asignar a los parámetros `header` del método. |
| contentHandling | string | Tipos de conversión de codificación de la carga de la respuesta. Los valores válidos son 1) CONVERT\$1TO\$1TEXT, para convertir una carga binaria en una cadena codificada en base64 o para convertir una carga de texto en una cadena codificada en utf-8 o para transferir la carga de texto de forma nativa sin modificaciones, y 2) CONVERT\$1TO\$1BINARY, para convertir una carga de texto en un blob descodificado en base64 o para transferir una carga binaria de forma nativa sin modificaciones. |
## `x-amazon-apigateway-integration.response`Ejemplo de
El siguiente ejemplo define una respuesta `302` para el método que obtiene una carga del tipo MIME `application/json` o `application/xml` del backend. La respuesta utiliza las plantillas de mapeo proporcionadas y devuelve la URL de redireccionamiento de la respuesta de integración en el encabezado `Location` del método.
```
{
"statusCode" : "302",
"responseTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
},
"responseParameters" : {
"method.response.header.Location": "integration.response.body.redirect.url"
}
}
```
# Objeto x-amazon-apigateway-integration.responseTemplates
Especifica las plantillas de mapeo de una carga de respuesta de los tipos MIME especificados.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| MIME type | string | Especifica una plantilla de mapeo para transformar el cuerpo de la respuesta de integración en el cuerpo de la respuesta del método para un tipo MIME especificado. Para obtener información acerca de la creación de una plantilla de mapeo, consulte [Asignación de las transformaciones de plantillas de asignación para las API de REST en API Gateway](models-mappings.md). Un ejemplo de *tipo MIME* es `application/json`. |
## Ejemplo de x-amazon-apigateway-integration.responseTemplate
El siguiente ejemplo especifica las plantillas de mapeo de una carga de solicitud de los tipos MIME `application/json` y `application/xml`.
```
"responseTemplates" : {
"application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }",
"application/xml" : "#set ($root=$input.path('$')) $root.name "
}
```
# Objeto x-amazon-apigateway-integration.responseParameters
Especifica las asignaciones de parámetros del método de integración a parámetros de la respuesta del método. Puede mapear `header`, `body` o valores estáticos al tipo `header` de la respuesta del método. Compatible solo con API REST.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| method.response.header. | string | El valor del parámetro designado se puede obtener a partir de los tipos `header` y `body` de los parámetros de la respuesta de integración. |
## `x-amazon-apigateway-integration.responseParameters`Ejemplo de
El siguiente ejemplo asigna los parámetros `body` y `header` de la respuesta de integración a dos parámetros `header` de la respuesta del método.
```
"responseParameters" : {
"method.response.header.Location" : "integration.response.body.redirect.url",
"method.response.header.x-user-id" : "integration.response.header.x-userid"
}
```
# Objeto x-amazon-apigateway-integration.tlsConfig
Especifica la configuración de TLS para una integración.
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| insecureSkipVerification | Boolean | Compatible solo con API REST. Especifica si API Gateway omite o no la verificación de que el certificado para un punto de enlace de integración es emitido por una [entidad de certificación admitida](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-supported-certificate-authorities-for-http-endpoints.html). No se recomienda, pero le permite utilizar certificados firmados por entidades de certificación privadas o certificados autofirmados. Si está habilitado, API Gateway sigue realizando la validación básica del certificado, que incluye comprobar la fecha de vencimiento del certificado, el nombre de host y la presencia de una entidad de certificación principal. El certificado raíz que pertenece a la autoridad privada debe cumplir las siguientes restricciones: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/api-gateway-extensions-integration-tls-config.html) Compatible solo para integraciones de `HTTP` y `HTTP_PROXY`. No se recomienda habilitar `insecureSkipVerification`, especialmente para integraciones con puntos de conexión HTTPS públicos. Si habilita `insecureSkipVerification`, aumenta el riesgo de ataques MITM (man-in-the-middle). |
| serverNameToVerify | string | Compatible únicamente con integraciones privadas de API HTTP. Si especifica un nombre de servidor, API Gateway lo utiliza para verificar el nombre de host en el certificado de integración. El nombre del servidor también se incluye en el protocolo de enlace TLS para admitir la indicación de nombre del servidor (SNI) o el alojamiento virtual. |
## Ejemplos de x-amazon-apigateway-integration.tlsConfig
En el siguiente ejemplo de OpenAPI 3.0 se habilita `insecureSkipVerification` una integración de proxy HTTP de API REST.
```
"x-amazon-apigateway-integration": {
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses": {
default": {
"statusCode": "200"
}
},
"passthroughBehavior": "when_no_match",
"httpMethod": "ANY",
"tlsConfig" : {
"insecureSkipVerification" : true
}
"type": "http_proxy",
}
```
En el siguiente ejemplo de OpenAPI 3.0 se especifica un `serverNameToVerify` para una integración privada de API HTTP.
```
"x-amazon-apigateway-integration" : {
"payloadFormatVersion" : "1.0",
"connectionId" : "abc123",
"type" : "http_proxy",
"httpMethod" : "ANY",
"uri" : "arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/0467ef3c8400ae65",
"connectionType" : "VPC_LINK",
"tlsConfig" : {
"serverNameToVerify" : "example.com"
}
}
```
# x-amazon-apigateway-minimum-compression-size
Especifica el tamaño mínimo de compresión de una API REST. Para habilitar la compresión, especifique un número entero entre 0 y 10485760. Para obtener más información, consulte [Compresión de la carga útil para las API de REST en API Gateway](api-gateway-gzip-compression-decompression.md).
## Ejemplo de x-amazon-apigateway-minimum-compression-size
En el siguiente ejemplo se especifica un tamaño mínimo de compresión de `5242880` bytes para una API REST.
```
"x-amazon-apigateway-minimum-compression-size": 5242880
```
# x-amazon-apigateway-policy
Especifica una política de recursos para una API REST. Para obtener más información sobre las políticas de recursos, consulte [Control del acceso a una API de REST con políticas de recursos de API Gateway](apigateway-resource-policies.md). Para obtener ejemplos de políticas de recursos, consulte [Ejemplos de políticas de recursos de API Gateway](apigateway-resource-policies-examples.md).
## `x-amazon-apigateway-policy`Ejemplo de
En el ejemplo siguiente se especifica una política de recursos para una API REST. La política de recursos deniega (bloquea) el tráfico entrante a una API desde un bloque de dirección IP de origen especificado. En la importación, `"execute-api:/*"` se convierte en `arn:aws:execute-api:region:account-id:api-id/*`, y se utiliza la región actual, el ID de la cuenta de AWS y el ID actual de la API REST.
```
"x-amazon-apigateway-policy": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
]
},
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": [
"execute-api:/*"
],
"Condition" : {
"IpAddress": {
"aws:SourceIp": "192.0.2.0/24"
}
}
}
]
}
```
# Propiedad x-amazon-apigateway-request-validator
Especifica un validador de solicitudes, haciendo referencia a un `request_validator_name` del mapa [Objeto x-amazon-apigateway-request-validators](api-gateway-swagger-extensions-request-validators.md), para habilitar la validación de solicitudes en la API contenedora o en un método. El valor de esta extensión es una cadena JSON.
Esta extensión puede especificarse en el nivel de API o en el nivel de método. El validador de nivel de API se aplica a todos los métodos, a menos que lo invalide el validador de nivel de método.
## `x-amazon-apigateway-request-validator`Ejemplo de
El siguiente ejemplo aplica el validador de solicitudes `basic` en el nivel de API aplicando al mismo tiempo el validador de solicitudes `parameter-only` a la solicitud `POST /validation`.
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"x-amazon-apigateway-request-validators" : {
"basic" : {
"validateRequestBody" : true,
"validateRequestParameters" : true
},
"params-only" : {
"validateRequestBody" : false,
"validateRequestParameters" : true
}
},
"x-amazon-apigateway-request-validator" : "basic",
"paths": {
"/validation": {
"post": {
"x-amazon-apigateway-request-validator" : "params-only",
...
}
}
```
------
# Objeto x-amazon-apigateway-request-validators
Define los validadores de solicitudes admitidos para la API contenedora como un mapa entre un nombre de validador y las reglas de validación de solicitudes asociadas. Esta extensión se aplica a una API REST
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| `request_validator_name` | [Objeto x-amazon-apigateway-request-validators.requestValidator](api-gateway-swagger-extensions-request-validators.requestValidator.md) | Especifica las reglas de validación del validador designado. Por ejemplo: "basic" : {
"validateRequestBody" : true,
"validateRequestParameters" : true
},
Para aplicar este validador a un método específico, haga referencia al nombre del validador (`basic`) como el valor de la propiedad [Propiedad x-amazon-apigateway-request-validator](api-gateway-swagger-extensions-request-validator.md). |
## `x-amazon-apigateway-request-validators`Ejemplo de
El siguiente ejemplo muestra un conjunto de validadores de solicitudes para una API como un mapa entre un nombre de validador y las reglas de validación de solicitudes asociadas.
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
...
"x-amazon-apigateway-request-validators" : {
"basic" : {
"validateRequestBody" : true,
"validateRequestParameters" : true
},
"params-only" : {
"validateRequestBody" : false,
"validateRequestParameters" : true
}
},
...
}
```
------
# Objeto x-amazon-apigateway-request-validators.requestValidator
Especifica las reglas de validación de un validador de solicitudes como parte de la definición del mapa [Objeto x-amazon-apigateway-request-validators](api-gateway-swagger-extensions-request-validators.md).
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| `validateRequestBody` | Boolean | Especifica si se debe validar el cuerpo de la solicitud (`true`) o no (`false`). |
| `validateRequestParameters` | Boolean | Especifica si se deben validar los parámetros de solicitud obligatorios (`true`) o no (`false`). |
## `x-amazon-apigateway-request-validators.requestValidator`Ejemplo de
El siguiente ejemplo muestra un validador de solicitudes de solo parámetros:
```
"params-only": {
"validateRequestBody" : false,
"validateRequestParameters" : true
}
```
# x-amazon-apigateway-security-policy
Especifica una política de seguridad para una API de REST. Si crea una política de seguridad que comience por `"SecurityPolicy_"`, también debe configurar el [modo de acceso de punto de conexión](openapi-extensions-endpoint-access-mode.md). Para obtener más información sobre las políticas de seguridad, consulte [Políticas de seguridad de las API de REST en API Gateway](apigateway-security-policies.md).
## `x-amazon-apigateway-security-policy`Ejemplo de
En el ejemplo siguiente se especifica `SecurityPolicy_TLS13_1_3_2025_0` para una API de REST.
```
"x-amazon-apigateway-security-policy": "SecurityPolicy_TLS13_1_3_2025_09"
```
# Propiedad x-amazon-apigateway-tag-value
Especifica el valor de una [etiqueta de AWS](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html) para una API HTTP. Puede utilizar la propiedad `x-amazon-apigateway-tag-value` como parte del [objeto de etiqueta OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#tag-object) de nivel de raíz para especificar etiquetas de AWS para una API HTTP. Si especifica un nombre de etiqueta sin la propiedad `x-amazon-apigateway-tag-value`, API Gateway crea una etiqueta con una cadena vacía para un valor.
Para obtener más información acerca del etiquetado, consulte [Etiquetado de recursos de API Gateway](apigateway-tagging.md).
| Nombre de la propiedad | Tipo | Descripción |
| --- | --- | --- |
| `name` | String | Especifica la clave de etiqueta. |
| `x-amazon-apigateway-tag-value` | String | Especifica el valor de la etiqueta. |
## `x-amazon-apigateway-tag-value`Ejemplo de
En el ejemplo siguiente se especifican dos etiquetas para una API HTTP:
+ "Owner": "Admin"
+ "Prod": ""
```
"tags": [
{
"name": "Owner",
"x-amazon-apigateway-tag-value": "Admin"
},
{
"name": "Prod"
}
]
```