# Extensões OpenAPI para o API Gateway
As extensões do API Gateway são compatíveis com a autorização específica da AWS e as integrações de API específicas do API Gateway para APIs REST e APIs HTTP. Nesta seção, descreveremos as extensões do API Gateway para a especificação do OpenAPI.
**dica**
Para entender como as extensões do API Gateway são usadas em uma aplicação, você pode usar o console do API Gateway para criar uma API REST ou HTTP e exportá-la para um arquivo de definição do OpenAPI. Para obter mais informações sobre como exportar uma API, consulte [Exportar uma API REST do API Gateway](api-gateway-export-api.md) e [Exportar APIs HTTP do 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)
+ [Propriedade x-amazon-apigateway-api-key-source](api-gateway-swagger-extensions-api-key-source.md)
+ [Objeto x-amazon-apigateway-auth](api-gateway-swagger-extensions-auth.md)
+ [Objeto x-amazon-apigateway-authorizer](api-gateway-swagger-extensions-authorizer.md)
+ [Propriedade x-amazon-apigateway-authtype](api-gateway-swagger-extensions-authtype.md)
+ [Propriedade 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)
+ [Propriedade 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)
+ [Propriedade x-amazon-apigateway-tag-value](api-gateway-openapi-extensions-x-amazon-apigateway-tag-value.md)
# Objeto x-amazon-apigateway-any-method
Especifica o [Objeto de operação do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object) para o método `ANY` genérico do API Gateway em um [Objeto de item de caminho do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#path-item-object). Esse objeto pode existir junto com outros objetos de operação e obterá qualquer método HTTP que não tenha sido explicitamente declarado.
A tabela a seguir lista as propriedades estendidas pelo API Gateway. Para as outras propriedades de Operação do OpenAPI, consulte a especificação OpenAPI.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| isDefaultRoute | Boolean | Especifica se uma rota é a rota do \$1default. Compatível apenas com APIs HTTP. Para saber mais, consulte [Criar rotas para APIs HTTP no API Gateway](http-api-develop-routes.md). |
| x-amazon-apigateway-integration | [Objeto x-amazon-apigateway-integration](api-gateway-swagger-extensions-integration.md) | Especifica a integração do método com o backend. Esta é uma propriedade estendida do objeto de [Operação do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object). A integração pode ser de tipo AWS, AWS\$1PROXY, HTTP, HTTP\$1PROXY ou MOCK. |
## Exemplos de x-amazon-apigateway-any-method
O exemplo a seguir integra o método `ANY` em um recurso de proxy, `{proxy+}`, com uma função do 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"
}
```
O exemplo a seguir cria uma rota `$default` para uma API HTTP que se integra a uma função do 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 a configuração de compartilhamento de recursos entre origens (CORS) para uma API HTTP. A extensão é aplicável à estrutura OpenAPI em nível de raiz. Para saber mais, consulte [Configurar CORS para APIs HTTP no API Gateway](http-api-cors.md).
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| allowOrigins | Array | Especifica as origens permitidas. |
| allowCredentials | Boolean | Especifica se as credenciais estão incluídas na solicitação de CORS. |
| exposeHeaders | Array | Especifica os cabeçalhos que estão expostos. |
| maxAge | Integer | Especifica o número de segundos que o navegador deve armazenar em cache os resultados da solicitação de simulação. |
| allowMethods | Array | Especifica os métodos HTTP permitidos. |
| allowHeaders | Array | Especifica os cabeçalhos permitidos. |
## Exemplo de x-amazon-apigateway-cors
Veja a seguir um exemplo de configuração de CORS para uma 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"
]
}
```
# Propriedade x-amazon-apigateway-api-key-source
Especifique a origem para receber uma chave de API a fim de controlar os métodos de API que exigem uma chave. Essa propriedade no nível da API é do tipo `String`. Para saber mais sobre como configurar um método para exigir uma chave de API, consulte [Configurar um método para usar chaves de API com uma definição OpenAPI](api-key-usage-plan-oas.md).
Especifique a origem da chave de API para as solicitações. Os valores válidos são:
+ `HEADER` para receber a chave de API do cabeçalho `X-API-Key` de uma solicitação.
+ `AUTHORIZER` para receber a chave da API do `UsageIdentifierKey` de um autorizador do Lambda (anteriormente conhecido como autorizador personalizado).
## Exemplo de x-amazon-apigateway-api-key-source
O exemplo a seguir define o cabeçalho `X-API-Key` como a origem da chave de 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 x-amazon-apigateway-auth
Define um tipo de autenticação a ser aplicado para a autenticação de invocações de método no API Gateway.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| type | string | Especifica o tipo de autorização. Especifique "NONE" para acesso aberto. Especifique "AWS\$1IAM" para usar permissões do IAM. Os valores diferenciam maiúsculas de minúsculas. |
## Exemplo de x-amazon-apigateway-auth
O exemplo a seguir define o tipo de autenticação para um 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 um autorizador do Lambda, um grupo de usuários do Amazon Cognito ou um autorizador do JWT a ser aplicado para a autorização de invocações de método no API Gateway. Esta extensão se aplica à definição de segurança no [OpenAPI 2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#security-definitions-object) e ao esquema de segurança no [OpenAPI 3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#security-scheme-object).
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| type | string | O tipo de autorizador. Essa é uma propriedade obrigatória. Para APIs REST, especifique `token` para um autorizador com a identidade do autor da chamada incorporada em um token de autorização. Especifique `request` para um autorizador com a identidade do autor da chamada contida nos parâmetros da solicitação. Especifique `cognito_user_pools` para um autorizador que use um grupo de usuários do Amazon Cognito para controlar o acesso à API. Para APIs HTTP, especifique `request` para um autorizador do Lambda com a identidade do autor da chamada contida nos parâmetros da solicitação. Especifique `jwt` para um autorizador do JWT. |
| authorizerUri | string | O URI (Uniform Resource Identifier) da função do Lambda do autorizador. A sintaxe é a seguinte: "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 | As credenciais necessárias para invocar o autorizador, se houver, no formato de um ARN de uma função de execução do IAM. Por exemplo, "arn:aws:iam::*account-id*:*IAM\$1role*". |
| authorizerPayloadFormatVersion | string | Para APIs HTTP, especifica o formato dos dados que o API Gateway envia para um autorizador do Lambda e como o API Gateway interpreta a resposta do Lambda. Para saber mais, consulte [Versão do formato da carga útil](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format). |
| enableSimpleResponses | Boolean | Para APIs HTTP, especifica se um autorizador `request` retorna um valor booliano ou uma política do IAM. Compatível apenas com autorizadores com um `authorizerPayloadFormatVersion` de `2.0`. Se habilitado, a função do autorizador do Lambda retornará um valor booliano. Para saber mais, consulte [Resposta de função do Lambda para o formato 2.0](http-api-lambda-authorizer.md#http-api-lambda-authorizer.v2). |
| identitySource | string | Lista de expressões de mapeamento separadas por vírgulas dos parâmetros de solicitação como a origem de identidade. Aplicável somente para o autorizador dos tipos "`request` e `jwt`. |
| jwtConfiguration | Object | Especifica o emissor e os públicos para um autorizador de JWT. Para saber mais, consulte [JWTConfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration)na Referência de API do API Gateway versão 2. Compatível apenas com APIs HTTP. |
| identityValidationExpression | string | Uma expressão regular para validar o token como identidade de entrada. Por exemplo, "^x-[a-z]\$1". Compatível somente com autorizadores `TOKEN` para APIs REST. |
| authorizerResultTtlInSeconds | string | O número de segundos durante os quais o resultado do autorizador é armazenado em cache. |
| providerARNs | Uma matriz de string | Uma lista dos ARNs do grupo de usuários do Amazon Cognito para `COGNITO_USER_POOLS`. |
## Exemplos de x-amazon-apigateway-authorizer para APIs REST
O exemplo de definições de segurança do OpenAPI a seguir especifica um autorizador do Lambda do tipo “token” chamado `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
}
}
}
```
O trecho de objeto de operação do OpenAPI a seguir define o `GET /http` para usar o autorizador do Lambda anterior.
```
"/http" : {
"get" : {
"responses" : { },
"security" : [ {
"test-authorizer" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"httpMethod" : "GET",
"uri" : "http://api.example.com"
}
}
}
```
O exemplo de definições de segurança do OpenAPI a seguir especifica um autorizador do Lambda do tipo “solicitação”, com um único parâmetro de cabeçalho (`auth`) como origem de identidade. O `securityDefinitions` é chamado `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
}
}
}
```
As definições de segurança demonstrativas do OpenAPI a seguir especificam um autorizador do Lambda do tipo “solicitação”, com um cabeçalho (`HeaderAuth1`) e um parâmetro de string de consulta `QueryString1` como origens de identidade.
```
"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
}
}
}
```
As definições de segurança demonstrativas do OpenAPI a seguir especificam um autorizador do Lambda do API Gateway do tipo “solicitação”, com uma única variável de estágio (`stage`) como origem de identidade.
```
"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
}
}
}
```
O exemplo a seguir de definição de segurança da OpenAPI especifica um grupo de usuários do 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"
]
}
}
```
O trecho de objeto de operação da OpenAPI a seguir define o `GET /http` para usar o grupo de usuários anterior do Amazon Cognito como autorizador, sem escopos personalizados.
```
"/http" : {
"get" : {
"responses" : { },
"security" : [ {
"cognito-pool" : [ ]
} ],
"x-amazon-apigateway-integration" : {
"type" : "http",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"httpMethod" : "GET",
"uri" : "http://api.example.com"
}
}
}
```
## Exemplos de x-amazon-apigateway-authorizer para APIs HTTP
O exemplo de OpenAPI 3.0 a seguir cria um autorizador JWT para uma API HTTP que usa o Amazon Cognito como um provedor de identidade, com o cabeçalho `Authorization` como uma origem de identidade.
```
"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"
}
}
}
```
O exemplo de OpenAPI 3.0 a seguir produz o mesmo autorizador de JWT como o exemplo anterior. No entanto, esse exemplo usa a propriedade `openIdConnectUrl` do OpenAPI para detectar o emissor automaticamente. O `openIdConnectUrl` deve estar totalmente formado.
```
"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"
}
}
}
```
O exemplo a seguir cria um autorizador do Lambda para uma API HTTP. Este exemplo de autorizador usa o cabeçalho `Authorization` como sua fonte de identidade. O autorizador usa a versão do formato de carga `2.0` e retorna o valor booliano, porque `enableSimpleResponses` está definido como `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
}
}
}
```
# Propriedade x-amazon-apigateway-authtype
Para APIs REST, essa extensão pode ser usada para definir um tipo personalizado de um autorizador do Lambda. Nesse caso, o valor é de formato livre. Por exemplo, uma API pode ter vários autorizadores do Lambda que usam esquemas internos diferentes. Você pode usar essa extensão para identificar o esquema interno de um autorizador do Lambda.
Mais comumente, em APIs HTTP e APIs REST, ele também pode ser usado como uma maneira de definir a autorização do IAM em várias operações que compartilham o mesmo esquema de segurança. Neste caso, o termo `awsSigv4` é um termo reservado, juntamente com qualquer termo prefixado por `aws`.
Esta extensão se aplica ao esquema `apiKey` de segurança de tipo no [OpenAPI 2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#security-scheme-object) e [OpenAPI 3.](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#security-scheme-object)
## Exemplo de x-amazon-apigateway-authtype
O exemplo do OpenAPI 3 a seguir define a autorização do IAM em vários recursos em uma API REST ou 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"
}
}
}
}
```
O exemplo do OpenAPI 3 a seguir define um autorizador do Lambda com um esquema personalizado para uma 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"
}
```
## Consulte também
[authorizer.authType](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#apigw-Type-Authorizer-authType)
# Propriedade x-amazon-apigateway-binary-media-types
Especifica a lista de tipos de mídia binários que serão compatíveis com o API Gateway, como `application/octet-stream` e `image/jpeg`. Essa extensão é uma matriz JSON. Ela deve ser incluída como uma extensão de fornecedor de nível superior ao documento OpenAPI.
## Exemplo de x-amazon-apigateway-binary-media-types
O exemplo a seguir mostra a ordem de pesquisa de codificação de uma API.
```
"x-amazon-apigateway-binary-media-types": [ "application/octet", "image/jpeg" ]
```
# Objeto x-amazon-apigateway-documentation
Define as partes de documentação a serem importadas para o API Gateway. Esse objeto é um objeto JSON que contém uma matriz das instâncias de `DocumentationPart`.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| documentationParts | Array | Uma matriz das instâncias de `DocumentationPart` exportadas ou importadas. |
| version | String | O identificador de versão do snapshot das partes de documentação exportadas. |
## Exemplo de x-amazon-apigateway-documentation
O exemplo a seguir da extensão do API Gateway para o OpenAPI define instâncias `DocumentationParts` a serem importadas ou exportadas de uma API no 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 o modo de acesso ao endpoint para uma API REST ou nome de domínio personalizado. Para saber mais sobre o acesso ao endpoint, consulte [Modo de acesso ao endpoint](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode).
## `x-amazon-apigateway-endpoint-access-mode`Exemplo de
O exemplo a seguir especifica o modo de acesso ao endpoint como estrito.
```
"x-amazon-apigateway-endpoint-access-mode": "STRICT"
```
# Objeto x-amazon-apigateway-endpoint-configuration
Especifica detalhes da configuração do endpoint de uma API. Esta extensão é uma propriedade estendida do objeto de [Operação do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#operation-object). Esse objeto deve estar presente em [extensões de fornecedor de nível superior](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#specification-extensions) para o Swagger 2.0. Para a OpenAPI 3.0, ele deve estar presente nas extensões de fornecedor do [objeto Server](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#server-object).
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| disableExecuteApiEndpoint | Booliano | Especifica se os clientes podem invocar sua API usando o endpoint `execute-api` padrão. Por padrão, os clientes podem invocar sua API com o endpoint `https://{api_id}.execute-api.{region}.amazonaws.com` padrão. Para exigir que os clientes usem um nome de domínio personalizado para invocar sua API, especifique `true`. |
| vpcEndpointIds | Uma matriz de String | Uma lista de identificadores de VpcEndpoint nos quais criar aliases do Route 53 para uma API REST. Ele só é compatível com APIs REST do tipo de endpoint `PRIVATE`. |
| ipAddressType | string | Os tipos de endereço IP que podem invocar uma API HTTP. Use `ipv4` para permitir que tipos de endereço IPv4 invoquem uma API HTTP. Use `dualstack` para permitir que tipos de endereço IPv4 e IPv6 invoquem uma API HTTP. É compatível apenas com APIs HTTP. |
## Exemplos de x-amazon-apigateway-endpoint-configuration
O exemplo a seguir associa VPC endpoints especificados à API REST.
```
"x-amazon-apigateway-endpoint-configuration": {
"vpcEndpointIds": ["vpce-0212a4ababd5b8c3e", "vpce-01d622316a7df47f9"]
}
```
O exemplo a seguir desabilita o endpoint padrão para uma API.
```
"x-amazon-apigateway-endpoint-configuration": {
"disableExecuteApiEndpoint": true
}
```
O exemplo a seguir define o tipo de endereço IP como pilha dupla para uma API HTTP.
```
"x-amazon-apigateway-endpoint-configuration": {
"ipAddressType": "dualstack"
}
```
# Objeto x-amazon-apigateway-gateway-responses
Define as respostas de gateway para uma API como um mapa de string para [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) de pares de chave/valor. A extensão é aplicável à estrutura OpenAPI em nível de raiz.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| responseType | [x-amazon-apigateway-gateway-responses.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md) | Um `GatewayResponse` para o *responseType* especificado. |
## Exemplo de x-amazon-apigateway-gateway-responses
A extensão demonstrativa do API Gateway para OpenAPI a seguir define um mapa [GatewayResponses](https://docs.aws.amazon.com/apigateway/latest/api/API_GetGatewayResponses.html) que contém duas instâncias de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), uma para o tipo `DEFAULT_4XX` e outra para o 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 uma resposta de gateway de um tipo de resposta especificado, incluindo o código de status, todos os parâmetros de resposta aplicáveis ou modelos de resposta.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| responseParameters | [x-amazon-apigateway-gateway-responses.responseParameters](api-gateway-swagger-extensions-gateway-responses.responseParameters.md) | Especifica os parâmetros [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), ou seja, os parâmetros de cabeçalho. Os valores de parâmetros podem usar qualquer valor de [parâmetro de solicitação](rest-api-parameter-mapping.md) de entrada ou um valor personalizado estático. |
| responseTemplates | [x-amazon-apigateway-gateway-responses.responseTemplates](api-gateway-swagger-extensions-gateway-responses.responseTemplates.md) | Especifica os modelos de mapeamento da resposta de gateway. Os modelos não são processados pelo mecanismo VTL. |
| statusCode | string | Um código de status HTTP da resposta do gateway. |
## Exemplo de x-amazon-apigateway-gateway-responses.gatewayResponse
O exemplo a seguir da extensão do API Gateway para OpenAPI define uma [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) para personalizar a resposta `INVALID_API_KEY` de forma a retornar o código de status de `456`, o valor do cabeçalho `api-key` da solicitação de entrada e a mensagem `"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 um mapa de string para string de pares de chave/valor para gerar parâmetros de resposta de gateway a partir dos parâmetros da solicitação de entrada ou usando strings literais. Compatível apenas com APIs REST.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| gatewayresponse.param-position.param-name | string | `param-position` pode ser `header`, `path` ou `querystring`. Para obter mais informações, consulte [Mapeamento de parâmetros para APIs REST no API Gateway](rest-api-parameter-mapping.md). |
## x-amazon-apigateway-gateway-responses.responseParameters example
O exemplo de extensões do OpenAPI a seguir mostra uma expressão de mapeamento de parâmetros de resposta [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) para habilitar o suporte a CORS para recursos nos domínios `*.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 modelos de mapeamento [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), como um mapa de string para string de pares de chave/valor para uma determinada resposta de gateway. Para cada par chave-valor, a chave é o tipo de conteúdo. Por exemplo, “application/json” e o valor são um modelo de mapeamento stringified para substituições de variáveis simples. Um modelo de mapeamento `GatewayResponse` não é processado pelo mecanismo [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html).
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| content-type | string | Um modelo de mapeamento de corpo `GatewayResponse` que oferece suporte apenas à substituição de variáveis simples para personalizar um corpo de resposta de gateway. |
## Exemplo de x-amazon-apigateway-gateway-responses.responseTemplates
O exemplo de extensões do OpenAPI a seguir mostra um modelo de mapeamento [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) para personalizar uma resposta de erro gerada pelo API Gateway em um formato específico do aplicativo.
```
"responseTemplates": {
"application/json": "{ \"message\": $context.error.messageString, \"type\":$context.error.responseType, \"statusCode\": '488' }"
}
```
O exemplo de extensões do OpenAPI a seguir mostra um modelo de mapeamento [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) para substituir uma resposta de erro gerada pelo API Gateway por uma mensagem de erro estática.
```
"responseTemplates": {
"application/json": "{ \"message\": 'API-specific errors' }"
}
```
# x-amazon-apigateway-importexport-version
Especifica a versão do algoritmo de importação e exportação do API Gateway para APIs HTTP. Atualmente, o único valor compatível é `1.0`. Para saber mais, consulte [exportVersion](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#w125aab9c10b3b1b4) na *Referência de API do API Gateway Versão 2*.
## x-amazon-apigateway-importexport-version example
O exemplo a seguir define a versão de importação e exportação como `1.0`.
```
{
"openapi": "3.0.1",
"x-amazon-apigateway-importexport-version": "1.0",
"info": { ...
```
# Objeto x-amazon-apigateway-integration
Especifica detalhes da integração de backend usada para esse método. Esta extensão é uma propriedade estendida do objeto de [Operação do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object). O resultado é um objeto de [integração do API Gateway](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| cacheKeyParameters | Uma matriz de string | Uma lista de parâmetros de solicitação cujos valores devem ser armazenados em cache. |
| cacheNamespace | string | Um grupo de tags específicas de API dos parâmetros em cache relacionados. |
| connectionId | string | O ID de um [VpcLink](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html) para a integração privada. |
| connectionType | string | O tipo de conexão da integração. O valor válido é "VPC\$1LINK" para integração privada ou "INTERNET", para outras. |
| credentials | string | Para credenciais baseadas em função IAM da AWS, especifique o ARN de uma função IAM apropriada. Se não forem especificadas, as credenciais assumirão como padrão permissões baseadas em recursos que devem ser adicionadas manualmente para permitir que a API acesse o recurso. Para obter mais informações, consulte [Conceder permissões com o uso de uma política de recursos](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html#intro-permission-model-access-policy). Observação: ao usar credenciais do IAM, verifique se os [endpoints regionais STS da AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html) estão habilitados para a região na qual essa API está implantada para obter a melhor performance. |
| contentHandling | string | Tipos de conversão de codificação da carga de solicitação. Os valores válidos são 1) CONVERT\$1TO\$1TEXT, para converter uma carga binária em uma string codificada em base64 ou converter uma carga de texto em uma string codificada por utf-8 ou transferir a carga de texto de forma nativa sem modificação e 2) CONVERT\$1TO\$1BINARY para converter uma carga de texto em um blob decodificado em base64 ou transferir uma carga binária de forma nativa sem modificação. |
| httpMethod | string | O método HTTP usado na solicitação de integração. Para invocações de função do Lambda, o valor deve ser POST. |
| integrationSubtype | string | Especifica o subtipo para uma integração de serviço da AWS. Compatível apenas com APIs HTTP. Para obter subtipos de integração compatíveis, consulte [Referência do subtipo de integração](http-api-develop-integrations-aws-services-reference.md). |
| integrationTarget | string | O receptor do ALB ou do NLB para o qual enviar a solicitação. Aceito apenas em integrações privadas que usem links da VPC V2. Para obter mais informações, consulte [Configurar links da VPC V2 no API Gateway](apigateway-vpc-links-v2.md). |
| passthroughBehavior | string | Especifica como uma carga de solicitação de um tipo de conteúdo não mapeado é transmitida na solicitação de integração sem modificação. Os valores com suporte when\$1no\$1templates, when\$1no\$1match e never. Para obter mais informações, consulte [Integration.passthroughBehavior](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#passthroughBehavior). |
| payloadFormatVersion | string | Especifica o formato da carga enviada para uma integração. Obrigatório para APIs HTTP. Para APIs HTTP, os valores suportados para integrações de proxy do Lambda são 1.0 e 2.0. Para todas as outras integrações, 1.0 é o único valor suportado. Para saber mais, consulte [Criar integrações de proxy AWS Lambda para APIs HTTP no API Gateway](http-api-develop-integrations-lambda.md) e [Referência do subtipo de integração](http-api-develop-integrations-aws-services-reference.md). |
| requestParameters | [Objeto x-amazon-apigateway-integration.requestParameters](api-gateway-swagger-extensions-integration-requestParameters.md) | Para APIs REST, especifica mapeamentos de parâmetros de solicitação de método para parâmetros de solicitação de integração. Parâmetros de solicitação com suporte são `querystring`, `path`, `header` e `body`. Para APIs HTTP, parâmetros de solicitação são um mapa de chave-valor que especifica parâmetros que são passados para integrações `AWS_PROXY` com um `integrationSubtype` especificado. Você pode fornecer valores estáticos ou mapear dados de solicitação, variáveis de estágio ou variáveis de contexto que são avaliadas no tempo de execução. Para saber mais, consulte [Criar integrações de serviços da AWS para APIs HTTP no API Gateway](http-api-develop-integrations-aws-services.md). |
| requestTemplates | [Objeto x-amazon-apigateway-integration.requestTemplates](api-gateway-swagger-extensions-integration-requestTemplates.md) | Modelos de mapeamento para uma carga de solicitação de tipos MIME especificados. |
| responses | [Objeto x-amazon-apigateway-integration.responses](api-gateway-swagger-extensions-integration-responses.md) | Define as respostas do método e especifica mapeamentos de parâmetros desejados ou mapeamentos de carga de respostas de integração para respostas de método. |
| responseTransferMode | string | O modo de transferência de resposta da integração. Utilize BUFFERED para o API Gateway esperar receber a resposta completa antes de iniciar a transmissão. Use STREAM para o API Gateway enviar respostas parciais de volta ao cliente assim que elas se tornem disponíveis. Para saber mais, consulte [Transmitir a resposta para suas integrações de proxy no API Gateway](response-transfer-mode.md). |
| timeoutInMillis | integer | Tempos limite para a integração entre 50 ms e 29.000 ms. |
| type | string | O tipo de integração com o backend especificado. Os valores válidos são: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration.html) Para obter mais informações sobre os tipos de integração, 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 a configuração de TLS para uma integração. |
| uri | string | O URI de endpoint do backend. Para integrações do tipo aws, este é um valor de ARN. Para a integração HTTP, esta é a URL do endpoint HTTP, incluindo o esquema https ou http. |
## Exemplos de x-amazon-apigateway-integration
Para APIs HTTP, é possível definir integrações na seção de componentes da sua definição do OpenAPI. Para saber mais, consulte [Objeto x-amazon-apigateway-integrations](api-gateway-extensions-integrations.md).
```
"x-amazon-apigateway-integration": {
"$ref": "#/components/x-amazon-apigateway-integrations/integration1"
}
```
O exemplo a seguir cria uma integração com uma função do Lambda. Para fins de demonstração, supõe-se que os modelos de mapeamento de amostra mostrados em `requestTemplates` e `responseTemplates` dos exemplos abaixo apliquem a seguinte carga em formato JSON: `{ "name":"value_1", "key":"value_2", "redirect": {"url" :"..."} }` para gerar uma saída JSON de `{ "stage":"value_1", "user-id":"value_2" }` ou uma saída XML de `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'"
}
}
}
}
```
Observe que as aspas duplas (") da string JSON nos modelos de mapeamento devem ser escapadas por string (\$1").
# Objeto x-amazon-apigateway-integrations
Define uma coleção de integrações. Você pode definir integrações na seção de componentes da definição do OpenAPI e reutilizar as integrações para várias rotas. Compatível apenas com APIs HTTP.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| integração | [Objeto x-amazon-apigateway-integration](api-gateway-swagger-extensions-integration.md) | Uma coleção de objetos de integração. |
## Exemplo de x-amazon-apigateway-integrations
O exemplo a seguir cria uma API HTTP que define duas integrações e faz referência às integrações usando `$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 modelos de mapeamento para uma carga de solicitação dos tipos MIME especificados.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| MIME type | string | Um exemplo do tipo MIME é `application/json`. Para obter informações sobre como criar um modelo de mapeamento, consulte [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md). |
## Exemplo de x-amazon-apigateway-integration.requestTemplates
O exemplo a seguir define modelos de mapeamento para uma carga de solicitação dos tipos MIME `application/json` e `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 APIs REST, especifica mapeamentos de parâmetros de solicitação de método nomeados para parâmetros de solicitação de integração. Os parâmetros de solicitação do método devem ser definidos antes de serem referenciados.
Para APIs HTTP, especifica parâmetros que são transmitidos para integrações `AWS_PROXY` com um `integrationSubtype` especificado.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| integration.request.. | string | Para APIs REST, normalmente, o valor é um parâmetro de solicitação de método predefinido do formato `method.request..` em que `` pode ser `querystring`, `path`, `header` ou `body`. No entanto `$context.VARIABLE_NAME`, `$stageVariables.VARIABLE_NAME` e `STATIC_VALUE` também são válidos. Para o parâmetro `body`, `` é uma expressão de caminho JSON sem o prefixo `$.` |
| parameter | string | Para APIs HTTP, parâmetros de solicitação são um mapa de chave-valor que especifica parâmetros que são passados para integrações `AWS_PROXY` com um `integrationSubtype` especificado. Você pode fornecer valores estáticos ou mapear dados de solicitação, variáveis de estágio ou variáveis de contexto que são avaliadas no tempo de execução. Para saber mais, consulte [Criar integrações de serviços da AWS para APIs HTTP no API Gateway](http-api-develop-integrations-aws-services.md). |
## `x-amazon-apigateway-integration.requestParameters`Exemplo de
O seguinte exemplo de mapeamentos de parâmetros de solicitação converte os parâmetros de consulta (`version`), cabeçalho (`x-user-id`) e caminho (`service`) de uma solicitação de método nos parâmetros de consulta (`stage`), cabeçalho (`x-userid`) e caminho (`op`) de uma solicitação de integração, respectivamente.
**nota**
Se você estiver criando recursos por meio do OpenAPI ou do CloudFormation, os valores estáticos deverão estar entre aspas simples.
Para adicionar esse valor no console, digite `application/json` na caixa, sem aspas.
```
"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 as respostas do método e especifica mapeamentos de parâmetros ou mapeamentos de carga de respostas de integração para respostas de método.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| Padrão do status de resposta | [Objeto x-amazon-apigateway-integration.response](api-gateway-swagger-extensions-integration-response.md) | Uma expressão regular usada para corresponder a resposta de integração à resposta do método ou `default` para capturar qualquer resposta que você não tenha configurado. Para integrações HTTP, essa expressão regular é aplicada ao código de status da resposta de integração. Para invocações do Lambda, a expressão se aplica ao campo `errorMessage` do objeto de informações de erro retornado por AWS Lambda como um corpo de resposta de falha quando a execução da função do Lambda lança uma exceção. O nome da propriedade do *Padrão do status de resposta* refere-se a um código de status de resposta ou a uma expressão regular que descreve um grupo de códigos de status de resposta. Ele não corresponde a nenhum identificador de um recurso [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) na API REST do API Gateway. |
## `x-amazon-apigateway-integration.responses`Exemplo de
O exemplo a seguir mostra uma lista de respostas `2xx` e `302`. Para a resposta `2xx`, a resposta do método é mapeada a partir da carga da resposta de integração do tipo MIME `application/json` ou `application/xml`. Essa resposta usa os modelos de mapeamento fornecidos. Para a resposta `302`, a resposta de método retorna um cabeçalho `Location` cujo valor é derivado da propriedade `redirect.url` na carga da resposta de integração.
```
"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 uma resposta e especifica mapeamentos de parâmetros ou mapeamentos de carga a partir da resposta de integração para a resposta de método.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| statusCode | string | Código de status HTTP para a resposta de método; por exemplo, `"200"`. Isso deve equivaler a uma resposta correspondente no campo `responses` da [Operação do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object). |
| responseTemplates | [Objeto x-amazon-apigateway-integration.responseTemplates](api-gateway-swagger-extensions-integration-responseTemplates.md) | Especifica modelos de mapeamento específicos de tipo MIME para a carga da resposta. |
| responseParameters | [Objeto x-amazon-apigateway-integration.responseParameters](api-gateway-swagger-extensions-integration-responseParameters.md) | Especifica mapeamentos de parâmetros para a resposta. Somente os parâmetros `header` e `body` da resposta de integração podem ser mapeados para os parâmetros `header` do método. |
| contentHandling | string | Tipos de conversão de codificação da carga de resposta. Os valores válidos são 1) CONVERT\$1TO\$1TEXT, para converter uma carga binária em uma string codificada em base64 ou converter uma carga de texto em uma string codificada por utf-8 ou transferir a carga de texto de forma nativa sem modificação e 2) CONVERT\$1TO\$1BINARY para converter uma carga de texto em um blob decodificado em base64 ou transferir uma carga binária de forma nativa sem modificação. |
## `x-amazon-apigateway-integration.response`Exemplo de
O exemplo a seguir define uma resposta `302` para o método que deriva uma carga do tipo MIME do `application/json` ou do `application/xml` no backend. A resposta usa os modelos de mapeamento fornecidos e retorna a URL de redirecionamento da resposta de integração no cabeçalho `Location` do 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 modelos de mapeamento para uma carga de resposta dos tipos MIME especificados.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| MIME type | string | Especifica um modelo de mapeamento para transformar o corpo da resposta de integração no corpo da resposta de método para um determinado tipo MIME. Para obter informações sobre como criar um modelo de mapeamento, consulte [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md). Um exemplo do *tipo MIME* é `application/json`. |
## Exemplo de x-amazon-apigateway-integration.responseTemplate
O exemplo a seguir define modelos de mapeamento para uma carga de solicitação dos tipos MIME `application/json` e `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 mapeamentos de parâmetros de resposta de método de integração para parâmetros de resposta de método. Você pode mapear `header`, `body` ou valores estáticos no tipo `header` da resposta do método. Compatível apenas com APIs REST.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| method.response.header. | string | O valor do parâmetro nomeado pode ser derivado dos tipos `header` e `body` dos parâmetros de resposta de integração. |
## `x-amazon-apigateway-integration.responseParameters`Exemplo de
O exemplo a seguir mapeia parâmetros `body` e `header` da resposta de integração para dois parâmetros `header` da resposta de 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 a configuração de TLS para uma integração.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| insecureSkipVerification | Boolean | Compatível apenas com APIs REST. Especifica se o API Gateway ignorará ou não a verificação de que o certificado para um endpoint de integração é emitido por uma [autoridade de certificação compatível](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-supported-certificate-authorities-for-http-endpoints.html). Isso não é recomendado, mas permite que você use certificados assinados por autoridades de certificação privadas ou certificados autoassinados. Se habilitado, o API Gateway ainda executará a validação básica do certificado, que inclui verificar a data de expiração do certificado, o nome do host e a presença de uma autoridade de certificação raiz. O certificado raiz pertencente à autoridade privada deve atender às seguintes restrições: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/api-gateway-extensions-integration-tls-config.html) Compatível apenas com integrações `HTTP` e `HTTP_PROXY`. Habilitar `insecureSkipVerification` não é recomendado, especialmente para integrações com endpoints HTTPS públicos. Se você habilitar `insecureSkipVerification`, você aumenta o risco de ataques man-in-the-middle. |
| serverNameToVerify | string | Compatível apenas com integrações privadas de API HTTP. Se você especificar um nome de servidor, o API Gateway o usará para verificar o nome do host no certificado de integração. O nome do servidor também está incluído no handshake de TLS para oferecer suporte à indicação de nome de servidor (SNI) ou à hospedagem virtual. |
## Exemplos x-amazon-apigateway-integration.tlsConfig
O OpenAPI 3.0 demonstrativo a seguir permite `insecureSkipVerification` para uma integração 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",
}
```
O OpenAPI 3.0 demonstrativo a seguir especifica um `serverNameToVerify` para uma integração 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 o tamanho mínimo de compactação para um API REST. Para habilitar a compactação, especifique um inteiro entre 0 e 10485760. Para saber mais, consulte [Compressão de carga útil para APIs REST no API Gateway](api-gateway-gzip-compression-decompression.md).
## Exemplo de x-amazon-apigateway-minimum-compression-size
O exemplo a seguir especifica um tamanho mínimo de compactação de `5242880` bytes para uma API REST.
```
"x-amazon-apigateway-minimum-compression-size": 5242880
```
# x-amazon-apigateway-policy
Especifica uma política de recursos para uma API REST. Para saber mais sobre as políticas de recursos, consulte [Controlar o acesso a uma API REST com políticas de recursos do API Gateway](apigateway-resource-policies.md). Para obter políticas de recursos demonstrativas, consulte [Exemplos de política de recursos do API Gateway](apigateway-resource-policies-examples.md).
## `x-amazon-apigateway-policy`Exemplo de
O exemplo a seguir especifica uma política de recursos para uma API REST. A política de recursos nega (bloqueia) o tráfego de entrada para uma API de um bloco de endereços IP de origem especificado. Na importação, `"execute-api:/*"` é convertido para `arn:aws:execute-api:region:account-id:api-id/*`, usando a Região atual, o ID de sua conta da AWS e o ID da API REST atual.
```
"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"
}
}
}
]
}
```
# Propriedade x-amazon-apigateway-request-validator
Especifica um validador de solicitação, fazendo referência a um `request_validator_name` do mapa [Objeto x-amazon-apigateway-request-validators](api-gateway-swagger-extensions-request-validators.md), para habilitar a validação de solicitações na API receptora ou em um método. O valor dessa extensão é uma string JSON.
Essa extensão pode ser especificada no nível de API ou no nível de método. O validador em nível de API aplica-se a todos os métodos, a menos que ela seja substituído pelo validador em nível de método.
## `x-amazon-apigateway-request-validator`Exemplo de
O exemplo a seguir aplica o validador de solicitação `basic` em nível de API e, ao mesmo tempo, aplica o validador de solicitação `parameter-only` na solicitação `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 os validadores de solicitação com suporte para a API receptora como um mapa entre um nome de validador e as regras de validação de solicitações associadas. Esta extensão se aplica a uma API REST.
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| `request_validator_name` | [Objeto x-amazon-apigateway-request-validators.requestValidator](api-gateway-swagger-extensions-request-validators.requestValidator.md) | Especifica as regras de validação que consistem no validador nomeado. Por exemplo: "basic" : {
"validateRequestBody" : true,
"validateRequestParameters" : true
},
Para aplicar esse validador a um método específico, faça referência ao nome do validador (`basic`) como o valor da propriedade [Propriedade x-amazon-apigateway-request-validator](api-gateway-swagger-extensions-request-validator.md). |
## `x-amazon-apigateway-request-validators`Exemplo de
O exemplo a seguir mostra um conjunto de validadores de solicitação para uma API como um mapa entre um nome de validador e as regras de validação de solicitações associadas.
------
#### [ 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 as regras de validação de um validador de solicitação como parte da definição do mapa [Objeto x-amazon-apigateway-request-validators](api-gateway-swagger-extensions-request-validators.md).
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| `validateRequestBody` | Boolean | Especifica se o corpo da solicitação deve ser validado (`true`) ou não (`false`). |
| `validateRequestParameters` | Boolean | Especifica se os parâmetros de solicitação necessários devem ser validados (`true`) ou não (`false`). |
## `x-amazon-apigateway-request-validators.requestValidator`Exemplo de
O exemplo a seguir mostra um validador de solicitação somente para parâmetros:
```
"params-only": {
"validateRequestBody" : false,
"validateRequestParameters" : true
}
```
# x-amazon-apigateway-security-policy
Especifica uma política de segurança para uma API REST. Se você criar uma política de segurança que comece com `"SecurityPolicy_"`, também deverá definir o [modo de acesso ao endpoint](openapi-extensions-endpoint-access-mode.md). Para saber mais sobre políticas de segurança, consulte [Políticas de segurança para APIs REST no API Gateway](apigateway-security-policies.md).
## `x-amazon-apigateway-security-policy`Exemplo de
O exemplo a seguir especifica `SecurityPolicy_TLS13_1_3_2025_0` para uma API REST.
```
"x-amazon-apigateway-security-policy": "SecurityPolicy_TLS13_1_3_2025_09"
```
# Propriedade x-amazon-apigateway-tag-value
Especifica o valor de uma [tag da AWS](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html) para uma API HTTP. É possível usar a propriedade `x-amazon-apigateway-tag-value` como parte do [objeto da tag OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#tag-object) para especificar as tags da AWS para uma API HTTP. Se você especificar um nome de tag sem a propriedade `x-amazon-apigateway-tag-value`, o API Gateway criará uma tag com uma string vazia para um valor.
Para saber mais sobre marcação, consulte [Marcar recursos do API Gateway](apigateway-tagging.md).
| Nome da propriedade | Tipo | Descrição |
| --- | --- | --- |
| `name` | String | Especifica a chave da tag. |
| `x-amazon-apigateway-tag-value` | String | Especifica o valor da tag. |
## `x-amazon-apigateway-tag-value`Exemplo de
O exemplo a seguir especifica duas tags para uma API HTTP:
+ “Proprietário”: “Admin”
+ "Prod": ""
```
"tags": [
{
"name": "Owner",
"x-amazon-apigateway-tag-value": "Admin"
},
{
"name": "Prod"
}
]
```