# APIs HTTP do API Gateway
APIs REST e APIs HTTP são produtos da API RESTful. As APIs REST são compatíveis com mais recursos do que as APIs HTTP, enquanto as APIs HTTP são projetadas com recursos mínimos para que possam ser oferecidas por um preço mais baixo. Para ter mais informações, consulte [Escolher entre APIs REST e APIs HTTP](http-api-vs-rest.md).
Você pode usar APIs HTTP para enviar solicitações para funções AWS Lambda ou para qualquer endpoint HTTP roteável. Por exemplo, você pode criar uma API HTTP que se integre a uma função do Lambda no backend. Quando um cliente chama sua API, o API Gateway envia a solicitação para a função do Lambda e retorna a resposta da função para o cliente.
APIs HTTP são compatíveis com as autorizações [OpenID Connect](https://openid.net/developers/how-connect-works/) e [OAuth 2.0](https://oauth.net/2/). Eles são fornecidos com suporte incorporado para compartilhamento de recursos de origem cruzada (CORS) e implantações automáticas.
Você pode criar APIs HTTP usando o Console de Gerenciamento da AWS, a AWS CLI, APIs, CloudFormation ou SDKs.
**Topics**
+ [Desenvolver APIs HTTP no API Gateway](http-api-develop.md)
+ [Publicar APIs HTTP para os clientes invocarem](http-api-publish.md)
+ [Proteger as APIs HTTP no API Gateway](http-api-protect.md)
+ [Monitorar APIs HTTP no API Gateway](http-api-monitor.md)
+ [Solução de problemas com APIs HTTP no API Gateway](http-api-troubleshooting.md)
# Desenvolver APIs HTTP no API Gateway
Esta seção fornece detalhes sobre os recursos necessários do API Gateway durante o desenvolvimento de suas APIs do API Gateway.
Ao desenvolver a API do API Gateway, você decidirá uma série de características da API. Essas características dependem do caso de uso da sua API. Por exemplo, talvez você queira permitir que somente determinados clientes chamem sua API ou talvez queira disponibilizá-las a todos. É recomendável que uma chamada de API execute uma função do Lambda, faça uma consulta de banco de dados ou chame uma aplicação.
**Topics**
+ [Criar uma API HTTP](#http-api-examples)
+ [Criar rotas para APIs HTTP no API Gateway](http-api-develop-routes.md)
+ [Tipos de endereço IP para APIs HTTP no API Gateway](http-api-ip-address-type.md)
+ [Controlar e gerenciar o acesso a APIs HTTP no API Gateway](http-api-access-control.md)
+ [Criar integrações para APIs HTTP no API Gateway](http-api-develop-integrations.md)
+ [Configurar CORS para APIs HTTP no API Gateway](http-api-cors.md)
+ [Transformar solicitações e respostas de API para APIs HTTP no API Gateway](http-api-parameter-mapping.md)
+ [Usar definições do OpenAPI para APIs HTTP no API Gateway](http-api-open-api.md)
## Criar uma API HTTP
Para criar uma API funcional, você deve ter pelo menos uma rota, integração, estágio e implantação.
Os exemplos a seguir mostram como criar uma API com uma integração de AWS Lambda ou HTTP, uma rota e um estágio padrão configurado para implantar alterações automaticamente.
Este guia pressupõe que você já está familiarizado com o API Gateway e o Lambda. Para obter uma lista mais detalhada, consulte [Começar a usar o API Gateway](getting-started.md)
**Topics**
+ [Crie uma API HTTP usando o Console de gerenciamento da AWS](#apigateway-http-api-create.console)
+ [Criar uma API HTTP usando a CLI da AWS](#http-api-examples.cli.quick-create)
### Crie uma API HTTP usando o Console de gerenciamento da AWS
1. Abra o [console do API Gateway](https://console.aws.amazon.com/apigateway).
1. Selecione **Create API** (Criar API).
1. Em **HTTP API (API HTTP)**, escolha **Build (Criar)**.
1. Escolha **Add integration (Adicionar integração)** e, em seguida, escolha uma função do AWS Lambda ou insira um endpoint HTTP.
1. Em **Name (Nome)**, insira um nome para a sua API.
1. Selecione **Review and create**.
1. Escolha **Create** (Criar).
Agora sua API está pronta para invocar. Você pode testar sua API inserindo seu URL de invocação em um navegador ou usando Curl.
```
curl https://api-id.execute-api.us-east-2.amazonaws.com
```
### Criar uma API HTTP usando a CLI da AWS
É possível usar a criação rápida para criar uma API com uma integração do Lambda ou HTTP, uma rota padrão genérica e um estágio padrão configurado para implantar alterações automaticamente. O comando [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) a seguir usa criação rápida para criar uma API que se integra a uma função do Lambda no backend.
**nota**
Para invocar uma integração do Lambda, o API Gateway deve ter as permissões obrigatórias. Você pode usar uma política baseada em recursos ou uma função do IAM para conceder permissões do API Gateway para invocar uma função do Lambda. Para saber mais, consulte [AWS Lambda Permissões](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html) no *Guia do desenvolvedor do AWS Lambda*.
**Example**
```
aws apigatewayv2 create-api --name my-api --protocol-type HTTP --target arn:aws:lambda:us-east-2:123456789012:function:function-name
```
Agora sua API está pronta para invocar. Você pode testar sua API inserindo seu URL de invocação em um navegador ou usando Curl.
```
curl https://api-id.execute-api.us-east-2.amazonaws.com
```
# Criar rotas para APIs HTTP no API Gateway
Roteia solicitações diretas recebidas de API para recursos de backend. As rotas consistem em duas partes: um método HTTP e um caminho de recurso, por exemplo, `GET /pets`. É possível definir métodos HTTP específicos para a rota. Ou usar o método `ANY` para corresponder a todos os métodos não definidos para um recurso. Você pode criar uma rota `$default` que funciona como um catch-all para solicitações que não correspondem a nenhuma outra rota.
**nota**
O API Gateway decodifica parâmetros de solicitação codificados em URL antes de passá-los para integrações de back-end.
## Trabalhar com variáveis de caminho
É possível usar variáveis de caminho em rotas de API HTTP.
Por exemplo, a rota `GET /pets/{petID}` captura uma solicitação `GET` que um cliente envia para `https://api-id.execute-api.us-east-2.amazonaws.com/pets/6`.
Uma *variável de caminho voraz* captura todos os recursos filho de uma rota. Para criar uma variável de caminho voraz, adicione `+` ao nome da variável, por exemplo, `{proxy+}`. O parâmetro de caminho voraz deve estar no final do caminho do recurso.
## Trabalhar com parâmetros de string de consulta
Por padrão, o API Gateway enviará parâmetros de string de consulta para a integração de backend se eles estiverem incluídos em uma solicitação para uma API Gateway.
Por exemplo, quando um cliente envia uma solicitação para `https://api-id.execute-api.us-east-2.amazonaws.com/pets?id=4&type=dog`, os parâmetros de string de consulta `?id=4&type=dog` são enviados para a integração.
## Trabalhar com a rota `$default`
A rota `$default` captura solicitações que não correspondem explicitamente a outras rotas na API.
Quando a rota `$default` recebe uma solicitação, o API Gateway envia o caminho de solicitação completo para a integração. Por exemplo, é possível criar uma API com apenas uma rota `$default` e integrá-la ao método `ANY` com o endpoint do HTTP `https://petstore-demo-endpoint.execute-api.com`. Quando uma solicitação é enviada para `https://api-id.execute-api.us-east-2.amazonaws.com/store/checkout`, o API Gateway envia uma solicitação para `https://petstore-demo-endpoint.execute-api.com/store/checkout`.
Para saber mais sobre integrações HTTP, consulte [Criar integrações de proxy HTTP para APIs HTTP](http-api-develop-integrations-http.md).
## Rotear solicitações de API
Quando um cliente envia uma solicitação de API, o API Gateway primeiro determina para qual [estágio](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-stages.html) rotear a solicitação. Se a solicitação corresponder explicitamente a um estágio, o API Gateway enviará a solicitação para esse estágio. Se nenhum estágio corresponder totalmente à solicitação, o API Gateway enviará a solicitação para o estágio `$default`. Se não houver estágio `$default`, a API retornará `{"message":"Not Found"}` e não gerará logs do CloudWatch.
Depois de selecionar um estágio, o API Gateway seleciona uma rota. Ele seleciona a rota com a correspondência mais específica, usando as seguintes prioridades:
1. Correspondência completa para uma rota e um método.
1. Correspondência para uma rota e um método com uma variável de caminho voraz (`{proxy+}`).
1. A rota `$default`.
Se nenhuma rota corresponder a uma solicitação, o API Gateway retornará `{"message":"Not Found"}` ao cliente.
Por exemplo, considere uma API com um estágio `$default` e as seguintes rotas de exemplo:
1. `GET /pets/dog/1`
1. `GET /pets/dog/{id}`
1. `GET /pets/{proxy+}`
1. `ANY /{proxy+}`
1. `$default`
A tabela a seguir resume como o API Gateway roteia solicitações para as rotas demonstrativas.
| Solicitação | Rota selecionada | Explicação |
| --- | --- | --- |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/1` | `GET /pets/dog/1` | A solicitação corresponde totalmente a esta rota estática. |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/2` | `GET /pets/dog/{id}` | A solicitação corresponde totalmente a essa rota. |
| `GET https://api-id.execute-api.region.amazonaws.com/pets/cat/1` | `GET /pets/{proxy+}` | A solicitação não corresponde totalmente a uma rota. A rota com um método `GET` e uma variável de caminho voraz captura essa solicitação. |
| `POST https://api-id.execute-api.region.amazonaws.com/test/5` | `ANY /{proxy+}` | O método `ANY` corresponde a todos os métodos não definidos para uma rota. Rotas com variáveis de caminho voraz têm prioridade mais alta que a rota `$default`. |
# Tipos de endereço IP para APIs HTTP no API Gateway
Ao criar uma API, você especifica o tipo de endereços IP que podem invocar sua API. É possível escolher IPv4 para resolver endereços IPv4 e invocar sua API ou escolher pilha dupla para permitir que endereços IPv4 e IPv6 invoquem sua API. Recomendamos que você defina o tipo de endereço IP como pilha dupla para aliviar o esgotamento do espaço IP ou para seu procedimento de segurança. Para ter mais informações sobre os benefícios de um tipo de endereço IP de pilha dupla, consulte [IPv6 na AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Considerações sobre tipos de endereço IP
As seguintes considerações podem afetar o uso de tipos de endereço IP:
+ O tipo de endereço IP padrão para APIs HTTP é IPv4.
+ Se você alterar o tipo de endereço IP de uma API existente de IPv4 para pilha dupla, confirme se todas as políticas que controlam o acesso às suas APIs foram atualizadas para considerar as chamadas IPv6. Quando você altera o tipo de endereço IP, a alteração entra em vigor imediatamente.
+ Sua API pode ser associada a um nome de domínio personalizado com um tipo de endereço IP diferente do da sua API. Se você desabilitar seu endpoint de API padrão, isso poderá afetar como os chamadores podem invocar sua API.
## Alterar o tipo de endereço IP de uma API HTTP
É possível alterar o tipo de endereço IP atualizando a configuração da API. É possível atualizar a configuração da API usando o Console de gerenciamento da AWS, a AWS CLI, o CloudFormation ou um SDK da AWS. Se você alterar o tipo de endereço IP da API, não poderá reimplantá-la para que as alterações entrem em vigor.
------
#### [ Console de gerenciamento da AWS ]
**Como alterar o tipo de endereço IP de uma API HTTP**
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Selecione uma API HTTP.
1. Em **Configurações da API**, escolha **Editar**.
1. Em Tipo de endereço IP, escolha **IPv4** ou **Pilha dupla**.
1. Escolha **Salvar**.
A alteração na configuração da sua API entrará em vigor imediatamente.
------
#### [ AWS CLI ]
O comando [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) a seguir atualiza uma API para ter um tipo de endereço IP de pilha dupla:
```
aws apigatewayv2 update-api \
--api-id abcd1234 \
--ip-address-type dualstack
```
A saída será exibida da seguinte forma:
```
{
"ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com",
"ApiId": "abcd1234",
"ApiKeySelectionExpression": "$request.header.x-api-key",
"CreatedDate": "2025-02-04T22:20:20+00:00",
"DisableExecuteApiEndpoint": false,
"Name": "My-HTTP-API",
"ProtocolType": "HTTP",
"RouteSelectionExpression": "$request.method $request.path",
"Tags": {},
"NotificationUris": [],
"IpAddressType": "dualstack"
}
```
------
# Controlar e gerenciar o acesso a APIs HTTP no API Gateway
O API Gateway é compatível com vários mecanismos de controle de acesso à sua API HTTP:
+ **Autorizadores do Lambda** usam funções do Lambda para controlar o acesso a APIs. Para obter mais informações, consulte [Controlar o acesso a APIs HTTP com autorizadores do AWS Lambda](http-api-lambda-authorizer.md).
+ **Os autorizadores do JWT** usam tokens da Web JSON para controlar o acesso a APIs. Para obter mais informações, consulte [Controlar o acesso a APIs HTTP com autorizadores JWT no API Gateway](http-api-jwt-authorizer.md).
+ As **funções e políticas padrão do AWS IAM** oferecem controles de acesso flexíveis e robustos. É possível usar as funções e políticas do IAM para controlar quem pode criar e gerenciar suas APIs, bem como quem pode invocá-las. Para obter mais informações, consulte [Controlar o acesso a APIs HTTP com autorização do IAM no API Gateway](http-api-access-control-iam.md).
Para melhorar seu procedimento de segurança, recomendamos que você configure um autorizador para todas as rotas na sua API HTTP. Você pode precisar fazer isso para cumprir vários requisitos de conformidade. Para ter mais informações, consulte [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) no *Guia do usuário do AWS Security Hub*.
# Controlar o acesso a APIs HTTP com autorizadores do AWS Lambda
Use um autorizador do Lambda para utilizar uma função do Lambda a fim de controlar o acesso à sua API HTTP. Depois, quando um cliente chamar a API, o API Gateway invocará sua função do Lambda. O API Gateway usará a resposta da função do Lambda para determinar se o cliente pode acessar sua API.
## Versão do formato da carga útil
A versão do formato de carga do autorizador especifica o formato dos dados que o API Gateway envia a um autorizador do Lambda e como o API Gateway interpreta a resposta do Lambda. Por padrão, se você não especificar uma versão de formato de carga útil, o Console de gerenciamento da AWS usará a versão mais recente. Se você criar um autorizador do Lambda usando a AWS CLI, o CloudFormation ou um SDK, será necessário especificar um `authorizerPayloadFormatVersion`. Os valores suportados são `1.0` e `2.0`.
Se precisar de compatibilidade com APIs REST, use a versão `1.0`.
Os exemplos a seguir mostram a estrutura de cada versão do formato de carga útil.
------
#### [ 2.0 ]
```
{
"version": "2.0",
"type": "REQUEST",
"routeArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": ["user1", "123"],
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value",
"cookies": ["cookie1", "cookie2"],
"headers": {
"header1": "value1",
"header2": "value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",
"apiId": "api-id",
"authentication": {
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "IP",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"pathParameters": { "parameter1": "value1" },
"stageVariables": { "stageVariable1": "value1", "stageVariable2": "value2" }
}
```
------
#### [ 1.0 ]
```
{
"version": "1.0",
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request",
"identitySource": "user1,123",
"authorizationToken": "user1,123",
"resource": "/request",
"path": "/request",
"httpMethod": "GET",
"headers": {
"X-AMZ-Date": "20170718T062915Z",
"Accept": "*/*",
"HeaderAuth1": "headerValue1",
"CloudFront-Viewer-Country": "US",
"CloudFront-Forwarded-Proto": "https",
"CloudFront-Is-Tablet-Viewer": "false",
"CloudFront-Is-Mobile-Viewer": "false",
"User-Agent": "..."
},
"queryStringParameters": {
"QueryString1": "queryValue1"
},
"pathParameters": {},
"stageVariables": {
"StageVar1": "stageValue1"
},
"requestContext": {
"path": "/request",
"accountId": "123456789012",
"resourceId": "05c7jb",
"stage": "test",
"requestId": "...",
"identity": {
"apiKey": "...",
"sourceIp": "...",
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"resourcePath": "/request",
"httpMethod": "GET",
"apiId": "abcdef123"
}
}
```
------
## Formato de resposta do autorizador do Lambda
A versão do formato de carga também determina a estrutura da resposta que deve ser retornada pela função do Lambda.
### Resposta de função do Lambda para o formato 1.0
Se você escolher a versão de formato `1.0`, os autorizadores do Lambda deverão retornar uma política do IAM que permita ou negue acesso à sua rota da API. É possível usar a sintaxe de política do IAM padrão na política. Para obter políticas demonstrativas do IAM, consulte [Controlar o acesso para chamar uma API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). É possível transmitir propriedades de contexto para integrações do Lambda ou logs de acesso usando `$context.authorizer.property`. O objeto `context` é opcional e `claims` é um espaço reservado que não pode ser usado como objeto de contexto. Para saber mais, consulte [Personalizar logs de acesso à API HTTP](http-api-logging-variables.md).
**Example**
****
```
{
"principalId": "abcdef",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
]
},
"context": {
"exampleKey": "exampleValue"
}
}
```
### Resposta de função do Lambda para o formato 2.0
Se você escolher a versão de formato `2.0`, poderá retornar um valor booliano ou uma política do IAM que use a sintaxe de política padrão do IAM da sua função do Lambda. Para retornar um valor booliano, ative respostas simples para o autorizador. Os exemplos a seguir demonstram o formato que você deve codificar para ser retornado pela sua função do Lambda. O objeto `context` é opcional. É possível transmitir propriedades de contexto para integrações do Lambda ou logs de acesso usando `$context.authorizer.property`. Para saber mais, consulte [Personalizar logs de acesso à API HTTP](http-api-logging-variables.md).
------
#### [ Simple response ]
```
{
"isAuthorized": true/false,
"context": {
"exampleKey": "exampleValue"
}
}
```
------
#### [ IAM policy ]
****
```
{
"principalId": "abcdef",
"policyDocument": {
"Version":"2012-10-17",
"Statement": [
{
"Action": "execute-api:Invoke",
"Effect": "Allow|Deny",
"Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]"
}
]
},
"context": {
"exampleKey": "exampleValue"
}
}
```
------
## Funções demonstrativas do autorizador do Lambda
As funções demonstrativas do Lambda Node.js a seguir mostram os formatos de resposta que você precisa retornar de sua função do Lambda para a versão de formato de carga `2.0`.
------
#### [ Simple response - Node.js ]
```
export const handler = async(event) => {
let response = {
"isAuthorized": false,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};
if (event.headers.authorization === "secretToken") {
console.log("allowed");
response = {
"isAuthorized": true,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
};
}
return response;
};
```
------
#### [ Simple response - Python ]
```
import json
def lambda_handler(event, context):
response = {
"isAuthorized": False,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
try:
if (event["headers"]["authorization"] == "secretToken"):
response = {
"isAuthorized": True,
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
print('allowed')
return response
else:
print('denied')
return response
except BaseException:
print('denied')
return response
```
------
#### [ IAM policy - Node.js ]
```
export const handler = async(event) => {
if (event.headers.authorization == "secretToken") {
console.log("allowed");
return {
"principalId": "abcdef", // The principal user identification associated with the token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": { "value1": "value2" }
}
};
}
else {
console.log("denied");
return {
"principalId": "abcdef", // The principal user identification associated with the token sent by the client.
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": event.routeArn
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": true,
"arrayKey": ["value1", "value2"],
"mapKey": { "value1": "value2" }
}
};
}
};
```
------
#### [ IAM policy - Python ]
```
import json
def lambda_handler(event, context):
response = {
# The principal user identification associated with the token sent by
# the client.
"principalId": "abcdef",
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Deny",
"Resource": event["routeArn"]
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
try:
if (event["headers"]["authorization"] == "secretToken"):
response = {
# The principal user identification associated with the token
# sent by the client.
"principalId": "abcdef",
"policyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Action": "execute-api:Invoke",
"Effect": "Allow",
"Resource": event["routeArn"]
}]
},
"context": {
"stringKey": "value",
"numberKey": 1,
"booleanKey": True,
"arrayKey": ["value1", "value2"],
"mapKey": {"value1": "value2"}
}
}
print('allowed')
return response
else:
print('denied')
return response
except BaseException:
print('denied')
return response
```
------
## Fontes de identidade
Também é possível especificar fontes de identidade para um autorizador do Lambda. As fontes de identidade especificam a localização dos dados necessários para autorizar uma solicitação. Por exemplo, é possível especificar valores de cabeçalho ou string de consulta como origens de identidade. Se você especificar fontes de identidade, os clientes deverão incluí-las na solicitação. Se a solicitação do cliente não incluir as fontes de identidade, o API Gateway não invocará o autorizador do Lambda, e o cliente receberá um erro `401`.
A tabela a seguir descreve as fontes de identidade compatíveis com um autorizador do Lambda.
| **Tipo** | **Exemplo do** | **Observações** |
| --- | --- | --- |
| Valor de cabeçalho | \$1request.header.nome | Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas. |
| Valor da string de consulta | \$1request.querystring.nome | Os nomes de strings de consulta diferenciam maiúsculas e minúsculas |
| Variável de contexto | \$1context.variableName | O valor de uma [variável de contexto](http-api-logging-variables.md) compatível. |
| Variável de estágio | \$1stageVariables.variableName | O valor de uma [variável de estágio](http-api-stages.stage-variables.md). |
Você também pode retornar diretamente ` {"errorMessage" : "Unauthorized"}` da função do Lambda para exibir um erro `401` aos clientes. Se você retornar diretamente um erro `401` da função do Lambda para os clientes, não especifique nenhuma fonte de identidade ao criar o autorizador do Lambda.
## Armazenar em cache respostas do autorizador
É possível habilitar o armazenamento em cache para um autorizador do Lambda especificando um [authorizerResultTtlInSeconds](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers.html#apis-apiid-authorizers-prop-createauthorizerinput-authorizerresultttlinseconds). Quando o cache está habilitado para um autorizador, o API Gateway usa as fontes de identidade do autorizador como a chave de cache. Se um cliente especificar os mesmos parâmetros em fontes de identidade dentro do TTL configurado, o API Gateway usará o resultado do autorizador em cache em vez de invocar sua função do Lambda.
Para habilitar o cache, seu autorizador deve ter pelo menos uma fonte de identidade.
Se você habilitar respostas simples para um autorizador, a resposta do autorizador permitirá ou negará totalmente todas as solicitações de API que correspondam aos valores da fonte de identidade armazenados em cache. Para obter permissões mais granulares, desative respostas simples e retorne uma política do IAM. Dependendo do seu autorizador, sua política de IAM pode precisar controlar o acesso a vários recursos.
Por padrão, o API Gateway usa a resposta do autorizador em cache para todas as rotas de uma API que usam o autorizador. Para armazenar em cache as respostas por rota, adicione `$context.routeKey` às fontes de identidade do seu autorizador.
## Criar um autorizador do Lambda
Ao criar um autorizador do Lambda, especifique a função do Lambda a ser usada pelo API Gateway. É necessário conceder permissão do API Gateway para invocar a função do Lambda usando a política de recursos da função ou uma função do IAM. O comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) indicado abaixo cria um autorizador do Lambda:
```
aws apigatewayv2 create-authorizer \
--api-id abcdef123 \
--authorizer-type REQUEST \
--identity-source '$request.header.Authorization' \
--name lambda-authorizer \
--authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-function/invocations' \
--authorizer-payload-format-version '2.0' \
--enable-simple-responses
```
O comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) a seguir atualiza a política de recursos da função do Lambda para conceder permissão ao API Gateway para invocar a função. Se o API Gateway não tiver permissão para invocar sua função, os clientes receberão um `500 Internal Server Error`.
```
aws lambda add-permission \
--function-name my-authorizer-function \
--statement-id apigateway-invoke-permissions-abc123 \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/authorizers/authorizer-id"
```
Depois de criar um autorizador e conceder ao API Gateway permissão para invocá-lo, atualize sua rota para usar o autorizador. O comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) a seguir adiciona o autorizador do Lambda à rota. Se seu autorizador do Lambda usa o armazenamento em cache de política, atualize a política para controlar o acesso ao método adicional.
```
aws apigatewayv2 update-route \
--api-id abcdef123 \
--route-id abc123 \
--authorization-type CUSTOM \
--authorizer-id def123
```
## Solução de problemas em autorizadores do Lambda
Se o API Gateway não conseguir invocar o autorizador do Lambda, ou se o autorizador do Lambda retornar uma resposta em um formato inválido, os clientes receberão um arquivo `500 Internal Server Error`.
Para solucionar erros, [habilite o registro em log de acesso](http-api-logging.md) para o estágio da API. Inclua a variável de registro em log `$context.authorizer.error` em seu formato de log.
Se os logs indicarem que o API Gateway não tem permissão para invocar sua função, atualize a política de recursos da função ou forneça uma função do IAM para conceder ao API Gateway permissão para invocar o autorizador.
Se os logs indicarem que a função do Lambda retorna uma resposta inválida, verifique se a função do Lambda retorna uma resposta no [formato necessário](#http-api-lambda-authorizer.payload-format-response).
# Controlar o acesso a APIs HTTP com autorizadores JWT no API Gateway
O JSON Web Tokens (JWTs) pode ser usado como parte das estruturas [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html) e [OAuth 2.0](https://oauth.net/2/) para que você possa restringir o acesso do cliente às suas APIs.
Se você configurar um autorizador JWT para uma rota da sua API, o API Gateway valida os JWTs enviados pelos clientes com solicitações de API. O API Gateway aceita ou rejeita solicitações com base na validação de tokens e, opcionalmente, escopos no token. Se você configurar escopos para uma rota, o token deverá incluir pelo menos um dos escopos da rota.
Você pode configurar autorizadores distintos para cada rota de uma API ou usar o mesmo autorizador para várias rotas.
**nota**
Não existe nenhum mecanismo padrão para diferenciar tokens de acesso JWT de outros tipos de JWTs, como os tokens OpenID e Connect ID. Exceto se precisar de tokens de ID para autorização de API, recomendamos que você configure suas rotas para exigir escopos de autorização. Você também pode configurar seus autorizadores do JWT para exigir emissores ou públicos que seu provedor de identidade usa somente ao emitir tokens de acesso do JWT.
## Autorização de solicitações de API com um autorizador JWT
O API Gateway usa o fluxo de trabalho geral a seguir para autorizar solicitações para rotas configuradas para usar um autorizador JWT.
1. Verifique se há um token em [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource). O `identitySource` pode incluir apenas o token ou o token com o prefixo `Bearer`.
1. Decodifique o token.
1. Verifique o algoritmo e a assinatura do token usando a chave pública obtida do do emisso `jwks_uri`. No momento, somente algoritmos baseados em RSA são compatíveis. O API Gateway pode armazenar a chave pública em cache por duas horas. Como prática recomendada, ao alternar as chaves, aguarde um período de carência durante o qual as chaves antigas e novas sejam válidas.
1. Valide reivindicações. O API Gateway avalia as seguintes reivindicações de token:
+ [https://datatracker.ietf.org/doc/html/rfc7517#section-4.5](https://datatracker.ietf.org/doc/html/rfc7517#section-4.5): o token deve ter uma reivindicação de cabeçalho que corresponda à chave no `jwks_uri` que assinou o token.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1): deve corresponder ao [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) configurado para o autorizador.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3) ou `client_id`: deve corresponder a uma das entradas [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) configuradas para o autorizador. O API Gateway valida `client_id` somente se `aud` não estiver presente. Quando `aud` e `client_id` estão presentes, o API Gateway avalia `aud`.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) – deve ser após a hora atual em UTC.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) – deve ser antes da hora atual em UTC.
+ [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) – deve ser antes da hora atual em UTC.
+ [https://datatracker.ietf.org/doc/html/rfc6749#section-3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) ou `scp`: o token deve incluir pelo menos um dos escopos em [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes) da rota.
Se qualquer uma dessas etapas falhar, o API Gateway negará a solicitação de API.
Depois de validar o JWT, o API Gateway passa as alegações no token para a integração da rota da API. Recursos de backend, como as funções do Lambda, podem acessar as alegações de JWT. Por exemplo, se o JWT incluiu um `emailID` de alegação de identidade, ele estará disponível para uma integração do Lambda em `$event.requestContext.authorizer.jwt.claims.emailID`. Para obter mais informações sobre a carga útil que o API Gateway envia para integrações do Lambda, consulte [Criar integrações de proxy AWS Lambda para APIs HTTP no API Gateway](http-api-develop-integrations-lambda.md).
## Criar um autorizador de JWT
Antes de criar um autorizador de JWT, você deve registrar um aplicativo cliente com um provedor de identidade. Também deve ter criado uma API HTTP. Para obter exemplos de criação de uma API HTTP, consulte [Criar uma API HTTP](http-api-develop.md#http-api-examples).
### Criar um autorizador JWT usando o console
As etapas a seguir mostram como criar o autorizador JWT usando o console.
**Criar um autorizador JWT usando o console**
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Selecione uma API HTTP.
1. No painel de navegação principal, selecione **Autorização**.
1. Escolha a guia **Gerenciar autorizadores**.
1. Escolha **Criar**.
1. Em **Tipo de autorizador**, escolha **JWT**.
1. Configure o autorizador JWT e especifique uma **Origem da identidade** que defina a origem do token.
1. Escolha **Criar**.
#### Criar um autorizador JWT usando a AWS CLI
O comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) a seguir cria um autorizador de JWT. Para `jwt-configuration`, especifique o `Audience` e o `Issuer` para seu provedor de identidades. Se você usa o Amazon Cognito como provedor de identidade, o `IssuerUrl` é `https://cognito-idp.us-east-2.amazonaws.com/userPoolID`.
```
aws apigatewayv2 create-authorizer \
--name authorizer-name \
--api-id api-id \
--authorizer-type JWT \
--identity-source '$request.header.Authorization' \
--jwt-configuration Audience=audience,Issuer=IssuerUrl
```
##### Criar um autorizador de AWS CloudFormation
O modelo CloudFormation a seguir cria uma API HTTP com um autorizador JWT usando o Amazon Cognito como provedor de identidade.
A saída do modelo CloudFormation é um URL para uma interface de usuário hospedada no Amazon Cognito, na qual os clientes podem se inscrever e fazer login para receber um JWT. Depois que o cliente faz login, é redirecionado para sua API HTTP com um token de acesso no URL. Para invocar a API com o token de acesso, altere o `#` no URL para um `?` para usar o token como um parâmetro de string de consulta.
##### Exemplo de modelo CloudFormation
```
AWSTemplateFormatVersion: '2010-09-09'
Description: |
Example HTTP API with a JWT authorizer. This template includes an Amazon Cognito user pool as the issuer for the JWT authorizer
and an Amazon Cognito app client as the audience for the authorizer. The outputs include a URL for an Amazon Cognito hosted UI where clients can
sign up and sign in to receive a JWT. After a client signs in, the client is redirected to your HTTP API with an access token
in the URL. To invoke the API with the access token, change the '#' in the URL to a '?' to use the token as a query string parameter.
Resources:
MyAPI:
Type: AWS::ApiGatewayV2::Api
Properties:
Description: Example HTTP API
Name: api-with-auth
ProtocolType: HTTP
Target: !GetAtt MyLambdaFunction.Arn
DefaultRouteOverrides:
Type: AWS::ApiGatewayV2::ApiGatewayManagedOverrides
Properties:
ApiId: !Ref MyAPI
Route:
AuthorizationType: JWT
AuthorizerId: !Ref JWTAuthorizer
JWTAuthorizer:
Type: AWS::ApiGatewayV2::Authorizer
Properties:
ApiId: !Ref MyAPI
AuthorizerType: JWT
IdentitySource:
- '$request.querystring.access_token'
JwtConfiguration:
Audience:
- !Ref AppClient
Issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}
Name: test-jwt-authorizer
MyLambdaFunction:
Type: AWS::Lambda::Function
Properties:
Runtime: nodejs18.x
Role: !GetAtt FunctionExecutionRole.Arn
Handler: index.handler
Code:
ZipFile: |
exports.handler = async (event) => {
const response = {
statusCode: 200,
body: JSON.stringify('Hello from the ' + event.routeKey + ' route!'),
};
return response;
};
APIInvokeLambdaPermission:
Type: AWS::Lambda::Permission
Properties:
FunctionName: !Ref MyLambdaFunction
Action: lambda:InvokeFunction
Principal: apigateway.amazonaws.com
SourceArn: !Sub arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:${MyAPI}/$default/$default
FunctionExecutionRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: '2012-10-17 '
Statement:
- Effect: Allow
Principal:
Service:
- lambda.amazonaws.com
Action:
- 'sts:AssumeRole'
ManagedPolicyArns:
- arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
UserPool:
Type: AWS::Cognito::UserPool
Properties:
UserPoolName: http-api-user-pool
AutoVerifiedAttributes:
- email
Schema:
- Name: name
AttributeDataType: String
Mutable: true
Required: true
- Name: email
AttributeDataType: String
Mutable: false
Required: true
AppClient:
Type: AWS::Cognito::UserPoolClient
Properties:
AllowedOAuthFlows:
- implicit
AllowedOAuthScopes:
- aws.cognito.signin.user.admin
- email
- openid
- profile
AllowedOAuthFlowsUserPoolClient: true
ClientName: api-app-client
CallbackURLs:
- !Sub https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
ExplicitAuthFlows:
- ALLOW_USER_PASSWORD_AUTH
- ALLOW_REFRESH_TOKEN_AUTH
UserPoolId: !Ref UserPool
SupportedIdentityProviders:
- COGNITO
HostedUI:
Type: AWS::Cognito::UserPoolDomain
Properties:
Domain: !Join
- '-'
- - !Ref MyAPI
- !Ref AppClient
UserPoolId: !Ref UserPool
Outputs:
SignupURL:
Value: !Sub https://${HostedUI}.auth.${AWS::Region}.amazoncognito.com/login?client_id=${AppClient}&response_type=token&scope=email+profile&redirect_uri=https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com
```
## Atualizar uma rota para usar um autorizador JWT
Você pode usar o console, a AWS CLI ou um AWS SDK para atualizar uma rota para usar um autorizador JWT.
### Atualizar uma rota para usar um autorizador JWT com o console
As etapas a seguir mostram como atualizar uma rota para usar o autorizador JWT com o console.
**Para criar um autorizador JWT usando o console**
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Selecione uma API HTTP.
1. No painel de navegação principal, selecione **Autorização**.
1. Escolha um método, selecione o autorizador no menu suspenso e escolha **Anexar autorizador**.
#### Atualizar uma rota para usar um autorizador JWT com a AWS CLI
O comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) indicado abaixo atualiza uma rota para usar um autorizador de JWT:
```
aws apigatewayv2 update-route \
--api-id api-id \
--route-id route-id \
--authorization-type JWT \
--authorizer-id authorizer-id \
--authorization-scopes user.email
```
# Controlar o acesso a APIs HTTP com autorização do IAM no API Gateway
É possível habilitar a autorização do IAM para rotas de API HTTP. Quando a autorização do IAM está habilitada, os clientes precisam usar o [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) para assinar suas solicitações com credenciais da AWS. O API Gateway invocará sua rota de API somente se o cliente tiver a permissão `execute-api` para a rota.
A autorização do IAM para APIs HTTP é semelhante à das [APIs REST](api-gateway-control-access-using-iam-policies-to-invoke-api.md).
**nota**
Atualmente, as políticas de recursos não são compatíveis com as APIs HTTP.
Para obter políticas demonstrativas do IAM que concedem aos clientes permissão para invocar APIs, consulte [Controlar o acesso para chamar uma API](api-gateway-control-access-using-iam-policies-to-invoke-api.md).
## Habilitar a autorização do IAM para uma rota
O comando [update-rout](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) indicado abaixo habilita a autorização do IAM para uma rota de API HTTP:
```
aws apigatewayv2 update-route \
--api-id abc123 \
--route-id abcdef \
--authorization-type AWS_IAM
```
# Criar integrações para APIs HTTP no API Gateway
*Integrações* conectam uma rota aos recursos de backend. As APIs HTTP são compatíveis com integrações de proxy do Lambda, serviços da AWS e proxy HTTP. Por exemplo, é possível configurar uma solicitação `POST` para a rota `/signup` da sua API para se integrar a uma função do Lambda que lida com o cadastro de clientes.
**Topics**
+ [Criar integrações de proxy AWS Lambda para APIs HTTP no API Gateway](http-api-develop-integrations-lambda.md)
+ [Criar integrações de proxy HTTP para APIs HTTP](http-api-develop-integrations-http.md)
+ [Criar integrações de serviços da AWS para APIs HTTP no API Gateway](http-api-develop-integrations-aws-services.md)
+ [Criar integrações privadas para APIs HTTP no API Gateway](http-api-develop-integrations-private.md)
# Criar integrações de proxy AWS Lambda para APIs HTTP no API Gateway
Uma integração de proxy do Lambda permite integrar uma rota de API com uma função do Lambda. Quando um cliente chama sua API, o API Gateway envia a solicitação para a função do Lambda e retorna a resposta da função para o cliente. Para obter exemplos de criação de uma API HTTP, consulte [Criar uma API HTTP](http-api-develop.md#http-api-examples).
## Versão do formato da carga útil
A versão do formato de carga útil especifica o formato do evento que o API Gateway envia para uma integração do Lambda e como o API Gateway interpreta a resposta do Lambda. Por padrão, se você não especificar uma versão de formato de carga útil, o Console de gerenciamento da AWS usará a versão mais recente. Se você criar uma integração do Lambda usando a AWS CLI, o CloudFormation ou um SDK, será necessário especificar um `payloadFormatVersion`. Os valores suportados são `1.0` e `2.0`.
Para saber mais sobre como definir o`payloadFormatVersion`, consulte [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html). Para saber mais sobre como determinar a `payloadFormatVersion` de uma integração existente, consulte [get-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-integration.html).
### Diferenças do formato da carga útil
A lista a seguir mostra as diferenças entre as versões do formato da carga útil `1.0` e `2.0`:
+ O formato `2.0` não tem campos `multiValueHeaders` ou `multiValueQueryStringParameters`. Os cabeçalhos duplicados são combinados com vírgulas e incluídos no campo `headers`. As strings de consulta duplicadas são combinadas com vírgulas e incluídas no campo `queryStringParameters`.
+ O formato `2.0` tem `rawPath`. Se você usar um mapeamento de API para associar o estágio a um nome de domínio personalizado, `rawPath` não fornecerá o valor do mapeamento de API. Use o formato `1.0` e `path` para acessar o mapeamento da API de seu nome de domínio personalizado.
+ O formato `2.0` inclui um novo campo `cookies`. Todos os cabeçalhos de cookie na solicitação são combinados com vírgulas e adicionados ao campo `cookies`. Na resposta ao cliente, cada cookie torna-se um cabeçalho `set-cookie`.
### Estrutura do formato da carga útil
Os exemplos a seguir mostram a estrutura de cada versão do formato de carga útil. Todos os nomes de cabeçalho ficam em letras minúsculas.
------
#### [ 2.0 ]
```
{
"version": "2.0",
"routeKey": "$default",
"rawPath": "/my/path",
"rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value",
"cookies": [
"cookie1",
"cookie2"
],
"headers": {
"header1": "value1",
"header2": "value1,value2"
},
"queryStringParameters": {
"parameter1": "value1,value2",
"parameter2": "value"
},
"requestContext": {
"accountId": "123456789012",
"apiId": "api-id",
"authentication": {
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"authorizer": {
"jwt": {
"claims": {
"claim1": "value1",
"claim2": "value2"
},
"scopes": [
"scope1",
"scope2"
]
}
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"http": {
"method": "POST",
"path": "/my/path",
"protocol": "HTTP/1.1",
"sourceIp": "192.0.2.1",
"userAgent": "agent"
},
"requestId": "id",
"routeKey": "$default",
"stage": "$default",
"time": "12/Mar/2020:19:03:58 +0000",
"timeEpoch": 1583348638390
},
"body": "Hello from Lambda",
"pathParameters": {
"parameter1": "value1"
},
"isBase64Encoded": false,
"stageVariables": {
"stageVariable1": "value1",
"stageVariable2": "value2"
}
}
```
------
#### [ 1.0 ]
```
{
"version": "1.0",
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"header1": "value1",
"header2": "value2"
},
"multiValueHeaders": {
"header1": [
"value1"
],
"header2": [
"value1",
"value2"
]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value"
},
"multiValueQueryStringParameters": {
"parameter1": [
"value1",
"value2"
],
"parameter2": [
"value"
]
},
"requestContext": {
"accountId": "123456789012",
"apiId": "id",
"authorizer": {
"claims": null,
"scopes": null
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"extendedRequestId": "request-id",
"httpMethod": "GET",
"identity": {
"accessKey": null,
"accountId": null,
"caller": null,
"cognitoAuthenticationProvider": null,
"cognitoAuthenticationType": null,
"cognitoIdentityId": null,
"cognitoIdentityPoolId": null,
"principalOrgId": null,
"sourceIp": "192.0.2.1",
"user": null,
"userAgent": "user-agent",
"userArn": null,
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"path": "/my/path",
"protocol": "HTTP/1.1",
"requestId": "id=",
"requestTime": "04/Mar/2020:19:15:17 +0000",
"requestTimeEpoch": 1583349317135,
"resourceId": null,
"resourcePath": "/my/path",
"stage": "$default"
},
"pathParameters": null,
"stageVariables": null,
"body": "Hello from Lambda!",
"isBase64Encoded": false
}
```
------
## Formato de resposta da função do Lambda
A versão do formato da carga determina a estrutura da resposta que a função do Lambda deve retornar.
### Resposta de função do Lambda para o formato 1.0
Com a versão do formato `1.0`, as integrações do Lambda devem retornar uma resposta no formato JSON a seguir:
**Example**
```
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headername": "headervalue", ... },
"multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
"body": "..."
}
```
### Resposta de função do Lambda para o formato 2.0
Com a versão de formato `2.0`, o API Gateway pode inferir o formato de resposta para você. O API Gateway fará as suposições a seguir se sua função do Lambda retornar JSON válido e não retornar um `statusCode`:
+ `isBase64Encoded` é `false`.
+ `statusCode` é `200`.
+ `content-type` é `application/json`.
+ `body` é a resposta da função.
Os exemplos a seguir mostram a saída de uma função do Lambda e a interpretação do API Gateway.
| Saída da função do Lambda | Interpretação do API Gateway |
| --- | --- |
| "Hello from Lambda!"
| {
"isBase64Encoded": false,
"statusCode": 200,
"body": "Hello from Lambda!",
"headers": {
"content-type": "application/json"
}
} |
| { "message": "Hello from Lambda!" } | {
"isBase64Encoded": false,
"statusCode": 200,
"body": "{ \"message\": \"Hello from Lambda!\" }",
"headers": {
"content-type": "application/json"
}
} |
Para personalizar a resposta, a função do Lambda deve retornar uma resposta com o formato a seguir.
```
{
"cookies" : ["cookie1", "cookie2"],
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headername": "headervalue", ... },
"body": "Hello from Lambda!"
}
```
# Criar integrações de proxy HTTP para APIs HTTP
Uma integração de proxy HTTP permite que você conecte uma rota de API a um endpoint HTTP roteável publicamente. Com esse tipo de integração, o API Gateway transmite toda a solicitação e resposta entre o front-end e o backend.
Para criar uma integração de proxy HTTP, forneça a URL de um endpoint HTTP roteável publicamente.
## Integração de proxy HTTP com variáveis de caminho
É possível usar variáveis de caminho em rotas de API HTTP.
Por exemplo, a rota `/pets/{petID}` captura solicitações para a `/pets/6`. Você pode fazer referência a variáveis de caminho no URI de integração para enviar o conteúdo das variáveis para uma integração. Um exemplo é `/pets/extendedpath/{petID}`.
Você pode usar variáveis de caminho voraz para capturar todos os recursos filho de uma rota. Para criar uma variável de caminho voraz, adicione `+` ao nome da variável, por exemplo, `{proxy+}`.
Para configurar uma rota com uma integração de proxy HTTP que captura todas as solicitações, crie uma rota de API com uma variável de caminho voraz (por exemplo, `/parent/{proxy+}`). Integre a rota a um endpoint HTTP (por exemplo, `https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}`) no método `ANY`. O parâmetro de caminho voraz deve estar no final do caminho do recurso.
# Criar integrações de serviços da AWS para APIs HTTP no API Gateway
Você pode integrar sua API HTTP com serviços da AWS usando *integrações de primeira classe*. Uma integração de primeira classe conecta uma rota de API HTTP a uma API de serviço da AWS. Quando um cliente invoca uma rota apoiada por uma integração de primeira classe, o API Gateway invoca uma API de serviço da AWS para você. Por exemplo, é possível usar integrações de primeira classe para enviar uma mensagem para uma fila do Amazon Simple Queue Service ou iniciar uma máquina de estado do AWS Step Functions. Para obter ações de serviço compatíveis, consulte [Referência do subtipo de integração](http-api-develop-integrations-aws-services-reference.md).
## Mapear parâmetros de solicitação
Integrações de primeira classe têm parâmetros obrigatórios e opcionais. É necessário configurar todos os parâmetros necessários para criar uma integração. Você pode usar valores estáticos ou mapear parâmetros que são avaliados dinamicamente no tempo de execução. Para obter uma lista completa de integrações e parâmetros compatíveis, consulte [Referência do subtipo de integração](http-api-develop-integrations-aws-services-reference.md).
A tabela a seguir descreve os parâmetros de solicitação de mapeamento compatíveis.
| Tipo | Exemplo | Observações |
| --- | --- | --- |
| Valor de cabeçalho | \$1request.header.nome | Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas. O API Gateway combina vários valores de cabeçalho com vírgulas, por exemplo, "header1": "value1,value2". |
| Valor da string de consulta | \$1request.querystring.nome | Os nomes de strings de consulta diferenciam maiúsculas e minúsculas O API Gateway combina vários valores com vírgulas, por exemplo, "querystring1": "Value1,Value2". |
| Parâmetro de caminho | \$1request.path.name | O valor de um parâmetro de caminho na solicitação. Por exemplo, se a rota for /pets/\$1petId\$1, você poderá mapear o parâmetro petId da solicitação com \$1request.path.petId. |
| Solicitar passagem do corpo | \$1request.body | O API Gateway transmite todo o corpo da solicitação. |
| Corpo da solicitação | \$1request.body.name | Uma [expressão de caminho JSON](https://goessner.net/articles/JsonPath/index.html#e2). Descidas recursivas (\$1request.body..name) e expressões de filtro (?(expression)) não são compatíveis. Quando você especifica um caminho JSON, o API Gateway trunca o corpo da solicitação em 100 KB e, em seguida, aplica a expressão de seleção. Para enviar cargas maiores que 100 KB, especifique `$request.body`. |
| Variável de contexto | \$1context.variableName | O valor de uma [variável de contexto](http-api-logging-variables.md) compatível. |
| Variável de estágio | \$1stageVariables.variableName | O valor de uma [variável de estágio](http-api-stages.stage-variables.md). |
| Valor estático | string | Um valor constante. |
## Criar uma integração de primeira classe
Antes de criar uma integração de primeira classe, é necessário criar uma função do IAM que conceda ao API Gateway permissões para invocar a ação de serviço da AWS à qual você está se integrando. Para saber mais, consulte [Criação de uma função para um serviço da AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html).
Para criar uma integração de primeira classe, escolha uma ação de serviço da AWS compatível, como `SQS-SendMessage`, configure os parâmetros de solicitação e forneça uma função que conceda ao API Gateway permissões para invocar a API de serviço integrado da AWS. Dependendo do subtipo de integração, diferentes parâmetros de solicitação são necessários. Para saber mais, consulte [Referência do subtipo de integração](http-api-develop-integrations-aws-services-reference.md).
O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) indicado abaixo cria uma integração que envia uma mensagem do Amazon SQS:
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-subtype SQS-SendMessage \
--integration-type AWS_PROXY \
--payload-format-version 1.0 \
--credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \
--request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}'
```
## Criar uma integração de primeira classe usando o CloudFormation
O exemplo a seguir mostra um trecho do CloudFormation que cria uma rota `/{source}/{detailType}` com uma integração de primeira classe com o Amazon EventBridge.
O parâmetro `Source` é mapeado para o parâmetro de caminho `{source}`, o `DetailType` é mapeado para o parâmetro de caminho `{DetailType}` e o parâmetro `Detail` é mapeado para o corpo da solicitação.
O trecho não mostra o barramento de eventos ou o perfil do IAM que concede permissões ao API Gateway para invocar a ação `PutEvents`.
```
Route:
Type: AWS::ApiGatewayV2::Route
Properties:
ApiId: !Ref HttpApi
AuthorizationType: None
RouteKey: 'POST /{source}/{detailType}'
Target: !Join
- /
- - integrations
- !Ref Integration
Integration:
Type: AWS::ApiGatewayV2::Integration
Properties:
ApiId: !Ref HttpApi
IntegrationType: AWS_PROXY
IntegrationSubtype: EventBridge-PutEvents
CredentialsArn: !GetAtt EventBridgeRole.Arn
RequestParameters:
Source: $request.path.source
DetailType: $request.path.detailType
Detail: $request.body
EventBusName: !GetAtt EventBus.Arn
PayloadFormatVersion: "1.0"
```
# Referência do subtipo de integração
Os [subtipos de integração](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationsubtype) a seguir são compatíveis com APIs HTTP.
**Topics**
+ [EventBridge-PutEvents 1.0](#EventBridge-PutEvents)
+ [SQS-SendMessage 1.0](#SQS-SendMessage)
+ [SQS-ReceiveMessage 1.0](#SQS-ReceiveMessage)
+ [SQS-DeleteMessage 1.0](#SQS-DeleteMessage)
+ [SQS-PurgeQueue 1.0](#SQS-PurgeQueue)
+ [AppConfig-GetConfiguration 1.0](#AppConfig-GetConfiguration)
+ [Kinesis-PutRecord 1.0](#Kinesis-PutRecord)
+ [StepFunctions-StartExecution 1.0](#StepFunctions-StartExecution)
+ [StepFunctions-StartSyncExecution 1.0](#StepFunctions-StartSyncExecution)
+ [StepFunctions-StopExecution 1.0](#StepFunctions-StopExecution)
## EventBridge-PutEvents 1.0
Envia eventos personalizados para o Amazon EventBridge para que eles possam ser correspondidos a regras.
| Parâmetro | Obrigatório |
| --- | --- |
| Detalhes | Verdadeiro |
| DetailType | Verdadeiro |
| Origem | Verdadeiro |
| Tempo | Falso |
| EventBusName | Falso |
| Recursos | Falso |
| Região | Falso |
| TraceHeader | Falso |
Para saber mais, consulte [PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html) na *Referência de API do Amazon EventBridge*.
## SQS-SendMessage 1.0
Entrega uma mensagem para a fila especificada.
| Parâmetro | Obrigatório |
| --- | --- |
| QueueUrl | Verdadeiro |
| MessageBody | Verdadeiro |
| DelaySeconds | Falso |
| MessageAttributes | Falso |
| MessageDeduplicationId | Falso |
| MessageGroupId | Falso |
| MessageSystemAttributes | Falso |
| Região | Falso |
Para saber mais, consulte [SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) na *Referência de API do Amazon Simple Queue Service*.
## SQS-ReceiveMessage 1.0
Recupera uma ou mais mensagens (até 10) de uma fila especificada.
| Parâmetro | Obrigatório |
| --- | --- |
| QueueUrl | Verdadeiro |
| AttributeNames | Falso |
| MaxNumberOfMessages | Falso |
| MessageAttributeNames | Falso |
| ReceiveRequestAttemptId | Falso |
| VisibilityTimeout | Falso |
| WaitTimeSeconds | Falso |
| Região | Falso |
Para saber mais, consulte [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) na *Referência de API do Amazon Simple Queue Service*.
## SQS-DeleteMessage 1.0
Exclui a mensagem especificada da fila especificada.
| Parâmetro | Obrigatório |
| --- | --- |
| ReceiptHandle | Verdadeiro |
| QueueUrl | Verdadeiro |
| Região | Falso |
Para saber mais, consulte [DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html) na *Referência de API do Amazon Simple Queue Service*.
## SQS-PurgeQueue 1.0
Exclui todas as mensagens da fila especificada.
| Parâmetro | Obrigatório |
| --- | --- |
| QueueUrl | Verdadeiro |
| Região | Falso |
Para saber mais, consulte [PurgeQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_PurgeQueue.html) na *Referência de API do Amazon Simple Queue Service*.
## AppConfig-GetConfiguration 1.0
Receba informações sobre uma configuração.
| Parâmetro | Obrigatório |
| --- | --- |
| Aplicativo | Verdadeiro |
| Ambiente | Verdadeiro |
| Configuração | Verdadeiro |
| ClientId | Verdadeiro |
| ClientConfigurationVersion | Falso |
| Região | Falso |
Para saber mais, consulte [GetConfiguration](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html) na *Referência da API AppConfig da AWS*.
## Kinesis-PutRecord 1.0
Grava um único registro de dados em um stream de dados do Amazon Kinesis.
| Parâmetro | Obrigatório |
| --- | --- |
| StreamName | Verdadeiro |
| Dados | Verdadeiro |
| PartitionKey | Verdadeiro |
| SequenceNumberForOrdering | Falso |
| ExplicitHashKey | Falso |
| Região | Falso |
Para saber mais, consulte [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html) na *Referência de API do Amazon Kinesis Data Streams*.
## StepFunctions-StartExecution 1.0
Inicia uma execução de máquina de estado.
| Parâmetro | Obrigatório |
| --- | --- |
| StateMachineArn | Verdadeiro |
| Nome | Falso |
| Entrada | Falso |
| Região | Falso |
Para saber mais, consulte [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) na *Referência da API do AWS Step Functions*.
## StepFunctions-StartSyncExecution 1.0
Inicia uma execução de máquina de estado síncrono.
| Parâmetro | Obrigatório |
| --- | --- |
| StateMachineArn | Verdadeiro |
| Nome | Falso |
| Entrada | Falso |
| Região | Falso |
| TraceHeader | Falso |
Para saber mais, consulte [StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html) na *Referência da API do AWS Step Functions*.
## StepFunctions-StopExecution 1.0
Interrompe uma execução.
| Parâmetro | Obrigatório |
| --- | --- |
| ExecutionArn | Verdadeiro |
| Causa | Falso |
| Erro | Falso |
| Região | Falso |
Para saber mais, consulte [StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html) na *Referência da API do AWS Step Functions*.
# Criar integrações privadas para APIs HTTP no API Gateway
As integrações privadas permitem que você crie integrações de API com recursos privados em uma VPC, como Application Load Balancers ou aplicações baseadas em contêiner do Amazon ECS.
Você pode expor seus recursos em uma VPC para acesso por clientes fora da VPC usando integrações privadas. Você pode controlar o acesso à sua API usando qualquer um dos [ métodos de autorização](http-api-access-control.md) compatíveis com o API Gateway.
**nota**
Para criar uma integração privada, primeiro crie um link de VPC. Os links da VPC V2 agora comportam APIs HTTP e REST. Para saber mais sobre links da VPC V2, consulte [Configurar links da VPC V2 no API Gateway](apigateway-vpc-links-v2.md).
Depois de criar um link da VPC V2, é possível configurar integrações privadas que se conectam a um Application Load Balancer, Network Load Balancer ou a recursos registrados em um serviço do AWS Cloud Map.
## Considerações
As considerações a seguir podem afetar o uso de integrações privadas:
+ Todos os recursos devem ser de propriedade da mesma Conta da AWS. Isso inclui o balanceador de carga ou o serviço AWS Cloud Map, o link da VPC e a API HTTP.
+ Por padrão, o tráfego de integração privada usa o protocolo HTTP. Para usar HTTPS, especifique uma [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html). Para fazer isso usando o Console de gerenciamento da AWS, ao criar sua integração privada, escolha **Configurações avançadas** e, depois, insira um nome de servidor seguro.
+ Para integrações privadas, o API Gateway inclui a parte do [estágio](http-api-stages.md) do endpoint da API na solicitação para seus recursos de backend. Por exemplo, uma solicitação para o estágio `test` de uma API inclui `test/route-path` na solicitação para sua integração privada. Para remover o nome do estágio da solicitação para os seus recursos de backend, use o [mapeamento de parâmetros](http-api-parameter-mapping.md) para substituir o caminho da solicitação para `$request.path`.
## Criar uma integração privada usando um Application Load Balancer ou Network Load Balancer
Antes de criar uma integração privada, você deve criar um link da VPC V2. Para saber mais sobre links da VPC V2, consulte [Configurar links da VPC V2 no API Gateway](apigateway-vpc-links-v2.md).
Para criar uma integração privada com um Application Load Balancer ou Network Load Balancer, crie uma integração de proxy HTTP, especifique o link de VPC a ser usado e forneça o ARN de listener do balanceador de carga.
O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) indicado abaixo cria uma integração privada que se conecta a um balanceador de carga usando um link de VPC.
```
aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \
--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:elasticloadbalancing:us-east-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/0467ef3c8400ae65
--payload-format-version 1.0
```
## Criar uma integração privada usando a descoberta de serviço do AWS Cloud Map
Antes de criar uma integração privada, você deve criar um link da VPC V2. Para saber mais sobre links de VPC, consulte [Configurar links da VPC V2 no API Gateway](apigateway-vpc-links-v2.md).
Para integrações com o AWS Cloud Map, o API Gateway usa `DiscoverInstances` para identificar recursos. Você pode usar parâmetros de consulta para direcionar recursos específicos. Os atributos dos recursos registrados devem incluir endereços IP e portas. O API Gateway distribui solicitações entre recursos íntegros que são retornados de `DiscoverInstances`. Para saber mais, consulte [DiscoverInstances](https://docs.aws.amazon.com/cloud-map/latest/api/API_DiscoverInstances.html) na Referência da API do AWS Cloud Map.
**nota**
Se usar o Amazon ECS para preencher entradas no AWS Cloud Map, você deverá configurar a tarefa do Amazon ECS para usar registros SRV com a descoberta de serviços do Amazon ECS ou ativar o Amazon ECS Service Connect. Para obter mais informações, consulte [Interconexão de serviços](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/interconnecting-services.html) no Guia do desenvolvedor do Amazon Elastic Container Service.
Para criar uma integração privada com o AWS Cloud Map, crie uma integração de proxy HTTP, especifique o link de VPC a ser usado e forneça o ARN do serviço AWS Cloud Map.
O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) indicado abaixo cria uma integração privada que usa a descoberta de serviços do AWS Cloud Map para identificar recursos:
```
aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \
--integration-method GET --connection-type VPC_LINK \
--connection-id VPC-link-ID \
--integration-uri arn:aws:servicediscovery:us-east-2:123456789012:service/srv-id?stage=prod&deployment=green_deployment
--payload-format-version 1.0
```
# Configurar CORS para APIs HTTP no API Gateway
O [compartilhamento de recursos entre origens (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) é um recurso de segurança de navegador que restringe as solicitações HTTP que são iniciadas em scripts em execução no navegador. Se você não conseguir acessar sua API e receber uma mensagem de erro contendo `Cross-Origin Request Blocked`, talvez seja necessário habilitar o CORS. Consulte mais informações em [O que é CORS?](https://aws.amazon.com/what-is/cross-origin-resource-sharing/).
Normalmente o CORS é necessário para criar aplicativos Web que acessem APIs hospedadas em um domínio ou origem diferente. O CORS pode ser habilitado para permitir solicitações para sua API a partir de um aplicativo Web hospedado em um domínio diferente. Por exemplo, se sua API estiver hospedada em `https://{api_id}.execute-api.{region}.amazonaws.com/`, e você quiser chamar sua API a partir de um aplicativo web hospedado no `example.com`, sua API deverá ser compatível com CORS.
Se você configurar o CORS para uma API, o API Gateway enviará automaticamente uma resposta às solicitações de comprovação OPTIONS, mesmo que não haja uma rota OPTIONS configurada para sua API. Para uma solicitação CORS, o API Gateway adiciona os cabeçalhos de CORS configurados à resposta de uma integração.
**nota**
Se você configurar CORS para uma API, o API Gateway ignorará os cabeçalhos de CORS retornados de sua integração de backend.
Em uma configuração de CORS, é possível especificar os parâmetros a seguir. Para adicionar esses parâmetros usando o console da API HTTP do API Gateway, selecione **Adicionar** depois de inserir o valor.
| Cabeçalhos de CORS | Propriedade da configuração de CORS | Exemplos de valores |
| --- | --- | --- |
| Access-Control-Allow-Origin | allowOrigins | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/http-api-cors.html) |
| Access-Control-Allow-Credentials | allowCredentials | true |
| Access-Control-Expose-Headers | exposeHeaders | date, x-api-id, \$1 |
| Access-Control-Max-Age | maxAge | 300 |
| Access-Control-Allow-Methods | allowMethods | GET, POST, DELETE, \$1 |
| Access-Control-Allow-Headers | allowHeaders | authorization, \$1 |
Para retornar cabeçalhos CORS, sua solicitação deve conter um cabeçalho `origin`. Para o método `OPTIONS`, sua solicitação deve conter um cabeçalho `origin` e um cabeçalho `Access-Control-Request-Method`.
A configuração de CORS pode parecer com a seguinte imagem:
![\[Configuração de CORS para APIs HTTP\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/http-cors-console.png)
## Configurar o CORS para uma API HTTP com uma rota `$default` e um autorizador
É possível habilitar o CORS e configurar a autorização para qualquer rota de uma API HTTP. Quando você habilita o CORS e a autorização para a [rota `$default`](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html#http-api-develop-routes.default), há algumas considerações especiais. A rota `$default` captura solicitações para todos os métodos e rotas não definidos explicitamente, inclusive solicitações `OPTIONS`. Para oferecer suporte a solicitações `OPTIONS` não autorizadas, adicione uma rota `OPTIONS /{proxy+}` à API que não exija autorização e anexe uma integração à rota. A rota `OPTIONS /{proxy+}` tem prioridade mais alta que a `$default`. Como resultado, ela permite que os clientes enviem solicitações `OPTIONS` para a API sem autorização. Para obter mais informações sobre prioridades de roteamento, consulte [Rotear solicitações de API](http-api-develop-routes.md#http-api-develop-routes.evaluation).
## Configurar o CORS para uma API HTTP usando a CLI da AWS
O comando [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) a seguir habilita as solicitações de CORS em `https://www.example.com`.
**Example**
```
aws apigatewayv2 update-api --api-id api-id --cors-configuration AllowOrigins="https://www.example.com"
```
Para obter mais informações, consulte [CORS](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid.html#apis-apiid-model-cors) na Referência de API do Amazon API Gateway versão 2.
# Transformar solicitações e respostas de API para APIs HTTP no API Gateway
Você pode modificar solicitações de API dos clientes antes que eles atinjam suas integrações de backend. Você também pode alterar a resposta das integrações antes que o API Gateway retorne a resposta aos clientes. Use o *mapeamento de parâmetros* para modificar solicitações e respostas de API para APIs HTTP. Para usar o mapeamento de parâmetros, especifique os parâmetros de solicitação de API ou resposta a serem modificados e especifique como modificar esses parâmetros.
## Transformação de solicitações de API
Você usa parâmetros de solicitação para alterar solicitações antes que elas atinjam suas integrações de backend. Você pode modificar cabeçalhos, strings de consulta ou o caminho da solicitação.
Os parâmetros de solicitação são um mapa de chave-valor. A chave identifica a localização do parâmetro da solicitação a ser alterado e como alterá-lo. O valor especifica os novos dados para o parâmetro.
A tabela a seguir mostra as chaves suportadas.
| Tipo | Sintaxe |
| --- | --- |
| Cabeçalho | append\$1overwrite\$1remove:header.headername |
| String de consulta | append\$1overwrite\$1remove:querystring.querystring-name |
| Caminho | overwrite:path |
A tabela a seguir mostra os valores suportados que você pode mapear para parâmetros.
| Tipo | Sintaxe | Observações |
| --- | --- | --- |
| Valor de cabeçalho | \$1request.header.name ou \$1\$1request.header.name\$1 | Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas. O API Gateway combina vários valores de cabeçalho com vírgulas, por exemplo, "header1": "value1,value2". Alguns cabeçalhos são reservados. Para saber mais, consulte [Cabeçalhos reservados](#http-api-mapping-reserved-headers). |
| Valor da string de consulta | \$1request.querystring.name ou \$1\$1request.querystring.name\$1 | Os nomes de strings de consulta diferenciam maiúsculas e minúsculas O API Gateway combina vários valores com vírgulas, por exemplo, "querystring1" "Value1,Value2". |
| Corpo da solicitação | \$1request.body.name ou \$1\$1request.body.name\$1 | Uma expressão de caminho JSON. Descida recursiva (\$1request.body..name) e expressões de filtro (?(expression)) não são suportadas. Quando você especifica um caminho JSON, o API Gateway trunca o corpo da solicitação em 100 KB e, em seguida, aplica a expressão de seleção. Para enviar cargas maiores que 100 KB, especifique `$request.body`. |
| O caminho da solicitação. | \$1request.path ou \$1\$1request.path\$1 | O caminho da solicitação, sem o nome do estágio. |
| Parâmetro de caminho | \$1request.path.name ou \$1\$1request.path.name\$1 | O valor de um parâmetro de caminho na solicitação. Por exemplo, se a rota for /pets/\$1petId\$1, você poderá mapear o parâmetro petId da solicitação com \$1request.path.petId. |
| Variável de contexto | \$1context.variableName ou \$1\$1context.variableName\$1 | O valor de uma [variável de contexto](http-api-logging-variables.md). Somente os caracteres especiais `.` e `_` são aceitos. |
| Variável de estágio | \$1stageVariables.variableName ou \$1\$1stageVariables.variableName\$1 | O valor de uma [variável de estágio](http-api-stages.stage-variables.md). |
| Valor estático | string | Um valor constante. |
**nota**
Para usar mais de uma variável em uma expressão de seleção, inclua a variável entre colchetes. Por exemplo, `${request.path.name} ${request.path.id}`.
## Transformando respostas da API
Você usa parâmetros de resposta para transformar a resposta HTTP de uma integração de backend antes de retornar a resposta aos clientes. Você pode modificar cabeçalhos ou o código de status de uma resposta antes que o API Gateway retorne a resposta aos clientes.
Você configura os parâmetros de resposta para cada código de status que sua integração retorna. Os parâmetros de resposta são um mapa de chave-valor. A chave identifica a localização do parâmetro da solicitação a ser alterado e como alterá-lo. O valor especifica os novos dados para o parâmetro.
A tabela a seguir mostra as chaves suportadas.
| Tipo | Sintaxe |
| --- | --- |
| Cabeçalho | append\$1overwrite\$1remove:header.headername |
| Código de status | overwrite:statuscode |
A tabela a seguir mostra os valores suportados que você pode mapear para parâmetros.
| Tipo | Sintaxe | Observações |
| --- | --- | --- |
| Valor de cabeçalho | \$1response.header.nome ou \$1\$1response.header.nome\$1 | Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas. O API Gateway combina vários valores de cabeçalho com vírgulas, por exemplo, "header1": "value1,value2". Alguns cabeçalhos são reservados. Para saber mais, consulte [Cabeçalhos reservados](#http-api-mapping-reserved-headers). |
| Corpo da resposta | \$1response.body.name ou \$1\$1response.body.name\$1 | Uma expressão de caminho JSON. Descidas recursivas (\$1response.body..name) e expressões de filtro (?(expression)) não são compatíveis. Quando você especifica um caminho JSON, o API Gateway trunca o corpo da resposta a 100 KB e, em seguida, aplica a expressão de seleção. Para enviar cargas maiores que 100 KB, especifique `$response.body`. |
| Variável de contexto | \$1context.variableName ou \$1\$1context.variableName\$1 | O valor de uma [variável de contexto](http-api-logging-variables.md) compatível. |
| Variável de estágio | \$1stageVariables.variableName ou \$1\$1stageVariables.variableName\$1 | O valor de uma [variável de estágio](http-api-stages.stage-variables.md). |
| Valor estático | string | Um valor constante. |
**nota**
Para usar mais de uma variável em uma expressão de seleção, inclua a variável entre colchetes. Por exemplo, `${request.path.name} ${request.path.id}`.
## Cabeçalhos reservados
Os seguintes cabeçalhos são reservados. Não é possível configurar mapeamentos de solicitação ou resposta para esses cabeçalhos.
+ access-control-\$1
+ apigw-\$1
+ Autorização
+ Conexão
+ Content-Encoding
+ Content-Length
+ Content-Location
+ Encaminhado
+ Keep-alive
+ Origem
+ Proxy-Authenticate
+ Proxy-Authorization
+ TE
+ Trailers
+ Transfer-Encoding
+ Upgrade
+ x-amz-\$1
+ x-amzn-\$1
+ X-Forwarded-For
+ X-Forwarded-Host
+ X-Forwarded-Proto
+ Via
## Exemplos
Os exemplos da AWS CLI a seguir configuram mapeamentos de dados. Para ver modelos de exemplo do CloudFormation, consulte o [GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates).
### Adicionar um cabeçalho a uma solicitação de API
O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) a seguir cria um cabeçalho chamado `header1` para uma solicitação de API antes que ela atinja sua integração de backend. O API Gateway preenche o cabeçalho com o ID da solicitação.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header1": "$context.requestId" }'
```
### Renomear um cabeçalho de solicitação
O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) indicado abaixo renomeia um cabeçalho de solicitação de `header1` para `header2`:
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--request-parameters '{ "append:header.header2": "$request.header.header1", "remove:header.header1": "''"}'
```
### Alterar a resposta de uma integração
O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) a seguir configura parâmetros de resposta para uma integração. Quando as integrações retornam um código de status 500, o API Gateway altera o código de status para 403 e adiciona `header1`1 à resposta. Quando a integração retorna um código de status 404, o API Gateway adiciona um `error` cabeçalho à resposta.
```
aws apigatewayv2 create-integration \
--api-id abcdef123 \
--integration-type HTTP_PROXY \
--payload-format-version 1.0 \
--integration-uri 'https://api.example.com' \
--integration-method ANY \
--response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"} }'
```
### Remover mapeamentos de parâmetros configurados
O comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) a seguir remove os parâmetros de solicitação configurados anteriormente para `append:header.header1`. Ele também remove parâmetros de resposta previamente configurados para um código de status 200.
```
aws apigatewayv2 update-integration \
--api-id abcdef123 \
--integration-id hijk456 \
--request-parameters '{"append:header.header1" : ""}' \
--response-parameters '{"200" : {}}'
```
# Usar definições do OpenAPI para APIs HTTP no API Gateway
É possível definir a API HTTP usando um arquivo de definição de OpenAPI 3.0. Depois, é possível importar a definição no API Gateway para criar uma API. Para saber mais sobre as extensões do API Gateway para OpenAPI, consulte [Extensões OpenAPI para o API Gateway](api-gateway-swagger-extensions.md).
## Importar uma API HTTP
É possível criar uma API HTTP importando um arquivo de definição do OpenAPI 3.0.
Para realizar a migração de uma API REST para uma API HTTP, é possível exportar sua API REST como um arquivo de definição do OpenAPI 3.0. Depois, importe a definição de API como uma API HTTP. Para saber mais sobre como exportar uma API REST, consulte [Exportar uma API REST do API Gateway](api-gateway-export-api.md).
**nota**
As APIs HTTP são compatíveis com as mesmas variáveis da AWS que as APIs REST. Para saber mais, consulte [Variáveis da AWS para importação de OpenAPI](import-api-aws-variables.md).
### Importar informações de validação
À medida que você importa uma API, o API Gateway fornece três categorias de informações de validação.
**Informações**
Uma propriedade é válida de acordo com a especificação do OpenAPI, mas essa propriedade não é compatível com APIs HTTP.
Por exemplo, o snippet do OpenAPI 3.0 a seguir produz informações sobre importação porque APIs HTTP não são compatíveis com a validação de solicitação. O API Gateway ignora os campos `requestBody` e `schema`.
```
"paths": {
"/": {
"get": {
"x-amazon-apigateway-integration": {
"type": "AWS_PROXY",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Body"
}
}
}
}
}
}
...
},
"components": {
"schemas": {
"Body": {
"type": "object",
"properties": {
"key": {
"type": "string"
}
}
}
...
}
...
}
```
**Aviso**
Uma propriedade ou estrutura é inválida de acordo com a especificação OpenAPI, mas não bloqueia a criação de API.çç É possível especificar se o API Gateway deve ignorar esses avisos e continuar criando a API ou parar de criar a API em avisos.
O documento do OpenAPI 3.0 a seguir produz avisos na importação porque APIs HTTP são compatíveis apenas com integrações de proxy do Lambda e HTTP.
```
"x-amazon-apigateway-integration": {
"type": "AWS",
"httpMethod": "POST",
"uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
"payloadFormatVersion": "1.0"
}
```
**Erro**
A especificação do OpenAPI é inválida ou malformada. O API Gateway não pode criar recursos a partir do documento malformado. Você precisa corrigir os erros e, em seguida, tentar novamente.
A definição de API a seguir produz erros na importação porque as APIs HTTP são compatíveis apenas com a especificação do OpenAPI 3.0.
```
{
"swagger": "2.0.0",
"info": {
"title": "My API",
"description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo",
"version": "1.0"
}
...
}
```
Como outro exemplo, enquanto o OpenAPI permite que os usuários definam uma API com vários requisitos de segurança anexados a uma determinada operação, o API Gateway não oferece suporte a isso. Cada operação pode ter apenas uma autorização do IAM, um autorizador do Lambda ou um autorizador JWT. A tentativa de modelar vários requisitos de segurança resulta em um erro.
### Importar uma API usando a AWS CLI
O comando [import-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/import-api.html) indicado abaixo importa o arquivo de definição `api-definition.json` do OpenAPI 3.0 como uma API HTTP:
**Example**
```
aws apigatewayv2 import-api --body file://api-definition.json
```
**Example**
É possível importar a definição demonstrativa do OpenAPI 3.0 a seguir para criar uma API HTTP.
```
{
"openapi": "3.0.1",
"info": {
"title": "Example Pet Store",
"description": "A Pet Store API.",
"version": "1.0"
},
"paths": {
"/pets": {
"get": {
"operationId": "GET HTTP",
"parameters": [
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "page",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pets"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
},
"post": {
"operationId": "Create Pet",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPet"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewPetResponse"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "POST",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
"payloadFormatVersion": 1.0
}
}
},
"/pets/{petId}": {
"get": {
"operationId": "Get Pet",
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "HTTP_PROXY",
"httpMethod": "GET",
"uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets/{petId}",
"payloadFormatVersion": 1.0
}
}
}
},
"x-amazon-apigateway-cors": {
"allowOrigins": [
"*"
],
"allowMethods": [
"GET",
"OPTIONS",
"POST"
],
"allowHeaders": [
"x-amzm-header",
"x-apigateway-header",
"x-api-key",
"authorization",
"x-amz-date",
"content-type"
]
},
"components": {
"schemas": {
"Pets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Pet"
}
},
"Empty": {
"type": "object"
},
"NewPetResponse": {
"type": "object",
"properties": {
"pet": {
"$ref": "#/components/schemas/Pet"
},
"message": {
"type": "string"
}
}
},
"Pet": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"price": {
"type": "number"
}
}
},
"NewPet": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/PetType"
},
"price": {
"type": "number"
}
}
},
"PetType": {
"type": "string",
"enum": [
"dog",
"cat",
"fish",
"bird",
"gecko"
]
}
}
}
}
```
# Exportar APIs HTTP do API Gateway
Depois de criar uma API HTTP, é possível exportar uma definição do OpenAPI 3.0 da API a partir do API Gateway. Você pode escolher um estágio para exportar ou exportar a configuração mais recente da API. Também é possível importar uma definição de API exportada para o API Gateway para a criação de outra API idêntica. Para saber mais sobre a importação de definições de API, consulte [Importar uma API HTTP](http-api-open-api.md#http-api-import).
## Exportar uma definição do OpenAPI 3.0 de um estágio usando a CLI da AWS
O comando [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) a seguir exporta uma definição do OpenAPI de um estágio de API chamado `prod` para um arquivo YAML denominado `stage-definition.yaml`. O arquivo de definição exportado inclui [extensões do API Gateway](api-gateway-swagger-extensions.md) por padrão.
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type YAML \
--specification OAS30 \
--stage-name prod \
stage-definition.yaml
```
## Exporte uma definição do OpenAPI 3.0 das alterações mais recentes da API usando a CLI da AWS
O comando [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) a seguir exporta uma definição do OpenAPI de uma API HTTP para um arquivo JSON denominado `latest-api-definition.json`. Como o comando não especifica um estágio, o API Gateway exporta a configuração mais recente da API, quer ela tenha sido implantada em um estágio ou não. O arquivo de definição exportado não inclui [extensões do API Gateway](api-gateway-swagger-extensions.md).
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type JSON \
--specification OAS30 \
--no-include-extensions \
latest-api-definition.json
```
Para obter mais informações, consulte [ExportAPI](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#apis-apiid-exports-specification-http-methods) na *Referência de API do Amazon API Gateway versão 2*.
## Exportar uma definição do OpenAPI 3.0 usando o console do API Gateway
O procedimento a seguir mostra como exportar uma definição do OpenAPI de uma API HTTP.
**Como exportar uma definição do OpenAPI 3.0 usando o console do API Gateway**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Selecione uma API HTTP.
1. No painel de navegação principal, em **Desenvolver**, escolha **Exportar**.
1. Selecione uma das seguintes opções para exportar a API:
![\[Opções de exportação para APIs HTTP.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/export-http-api.png)
1. Em **Origem**, selecione uma origem para a definição do OpenAPI 3.0. Você pode escolher um estágio para exportar ou exportar a configuração mais recente da API.
1. Ative a opção **Incluir extensões do API Gateway** para incluir [extensões do API Gateway](api-gateway-swagger-extensions.md).
1. Em **Formato de saída**, selecione um formato de saída.
1. Escolha **Baixar**.
# Publicar APIs HTTP para os clientes invocarem
Você pode usar estágios e nomes de domínio personalizados para publicar sua API para que os clientes chamem.
O estágio de uma API é uma referência lógica a um estado do ciclo de vida de sua API (por exemplo, `dev`, `prod`, `beta` ou `v2`). Cada estágio é uma referência nomeada a uma implantação da API e é disponibilizado para chamadas feitas por aplicativos cliente. É possível configurar diferentes integrações e configurações para cada estágio de uma API.
É possível usar nomes de domínio personalizados para fornecer um URL mais simples e intuitivo para que os clientes chamem sua API do que o URL padrã, `https://api-id.execute-api.region.amazonaws.com/stage`.
**nota**
Para aumentar a segurança das APIs do API Gateway, o domínio `execute-api.{region}.amazonaws.com` é registrado na [Public Suffix List (PSL)](https://publicsuffix.org/). Para maior segurança, recomendamos que você use cookies com um prefixo `__Host-` se precisar definir cookies confidenciais no nome de domínio padrão para as APIs do API Gateway. Essa prática ajudará a defender seu domínio contra tentativas de falsificação de solicitação entre sites (CSRF). Para obter mais informações, consulte a página [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) na Mozilla Developer Network.
**Topics**
+ [Estágios para APIs HTTP no API Gateway](http-api-stages.md)
+ [Política de segurança para APIs HTTP no API Gateway](http-api-ciphers.md)
+ [Nomes de domínio personalizados para APIs HTTP no API Gateway](http-api-custom-domain-names.md)
# Estágios para APIs HTTP no API Gateway
O estágio de uma API é uma referência lógica a um estado do ciclo de vida de sua API (por exemplo, `dev`, `prod`, `beta` ou `v2`). Os estágios de API são identificados por seu ID de API e nome de estágio e são incluídos no URL que você usa para chamar a API. Cada estágio é uma referência nomeada a uma implantação da API e é disponibilizado para chamadas feitas por aplicativos cliente.
É possível criar um estágio `$default` que é servido a partir da base do URL da sua API, por exemplo, `https://{api_id}.execute-api.{region}.amazonaws.com/`. Use esse URL para chamar um estágio de API.
Uma implantação é um instantâneo da configuração da API. Depois de implantar uma API em um estágio, ela estará disponível para ser chamada por clientes. Você deve implantar uma API para que as alterações entrem em vigor. Se você habilitar implantações automáticas, as alterações em uma API serão liberadas automaticamente para você.
# Usar variáveis de estágio para APIs HTTP no API Gateway
As variáveis de estágio são pares chave/valor que você pode definir para um estágio de uma API HTTP. Elas atuam como variáveis de ambiente e podem ser usadas na configuração da API.
As variáveis de estágio não se destinam a ser usadas para dados confidenciais, como credenciais. Para transmitir dados confidenciais para integrações, use um autorizador do AWS Lambda. Você pode passar dados confidenciais para integrações na saída do autorizador do Lambda. Para saber mais, consulte [Formato de resposta do autorizador do Lambda](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response).
## Exemplo: usar uma variável de estágio para personalizar o endpoint de integração HTTP
Por exemplo, você pode definir uma variável de estágio e, depois, definir seu valor como um endpoint HTTP para uma integração de proxy HTTP. Posteriormente, você pode fazer referência ao endpoint usando o nome da variável de estágio associada. Fazendo isso, você pode usar a mesma configuração de API com um endpoint diferente em cada estágio. Da mesma forma, você pode usar variáveis de estágio para especificar uma integração de função diferente do AWS Lambda para cada estágio da API.
Para usar uma variável de estágio para personalizar o endpoint de integração HTTP, primeiro defina o nome e o valor da variável de estágio (por exemplo, `url`) com um valor de `example.com`. Depois, configure uma integração de proxy HTTP. Em vez de inserir o URL do endpoint, você pode instruir o API Gateway a usar o valor da variável de estágio, **http://\$1\$1stageVariables.url\$1**. Esse valor instrui o API Gateway a substituir sua variável de estágio `${}` em tempo de execução, dependendo do estágio da API.
É possível fazer referência a variáveis de estágio de forma semelhante para especificar um nome de função do Lambda ou um ARN de função da AWS.
Ao especificar um nome de função do Lambda como um valor de variável de estágio, você deve configurar as permissões nessa função do Lambda manualmente. O comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) indicado abaixo configura a permissão para a função do Lambda:
```
aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
# Referência de variáveis de estágios do API Gateway para APIs HTTP no API Gateway
É possível usar variáveis de estágios do API Gateway para APIs HTTP nos casos a seguir.
## URIs de integração HTTP
Uma variável de estágio pode ser usada como parte de um URI de integração HTTP, como mostram os exemplos a seguir.
+ Um URI completo sem protocol – `http://${stageVariables.}`
+ Um domínio complet – `http://${stageVariables.}/resource/operation`
+ Um subdomíni – `http://${stageVariables.}.example.com/resource/operation`
+ Um caminh – `http://example.com/${stageVariables.}/bar`
+ Uma string de consult – `http://example.com/foo?q=${stageVariables.}`
## Funções do Lambda
É possível usar uma variável de estágio no lugar de um nome ou alias de integração da função do Lambda, conforme mostrado nos exemplos a seguir.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**nota**
Para usar uma variável de estágio para uma função do Lambda, a função deve estar na mesma conta que a API. As variáveis de estágio não suportam funções do Lambda entre contas.
## AWSCredenciais de integração da
É possível usar uma variável de estágio como parte de um ARN de credencial de usuário ou de função da AWS, conforme mostrado no exemplo a seguir.
+ `arn:aws:iam:::${stageVariables.}`
# Política de segurança para APIs HTTP no API Gateway
O API Gateway impõe uma política de segurança de `TLS_1_2` para todos os endpoints da API HTTP.
Uma *política de segurança* é uma combinação predefinida da versão mínima do TLS e dos pacotes de criptografia oferecida pelo Amazon API Gateway. O protocolo TLS trata problemas de segurança de rede, como violação e interceptação entre um cliente e o servidor. Quando seus clientes estabelecem um handshake do TLS para a API por meio do domínio personalizado, a política de segurança aplica as opções do pacote de criptografia e da versão do TLS que seus clientes podem optar por usar. Essa política de segurança é compatível com tráfego TLS 1.2 e TLS 1.3 e rejeita tráfego TLS 1.0.
## Protocolos e cifras TLS compatíveis com APIs HTTP
A tabela a seguir descreve os protocolos TLS compatíveis com APIs HTTP.
| **Protocolos TLS** | **Política de segurança TLS\$11\$12** |
| --- | --- |
| TLSv1.3 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| TLSv1.2 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
A tabela a seguir descreve as cifras TLS disponíveis para a política de segurança TLS 1\$12 para APIs HTTP.
| **Cifras TLS** | **Política de segurança TLS\$11\$12** |
| --- | --- |
| TLS-AES-128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| TLS-AES-256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| TLS-CHACHA20-POLY1305-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-ECDSA-AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-RSA-AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-ECDSA-AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-RSA-AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-ECDSA-AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-RSA-AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-ECDSA-AES256-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-RSA-AES256-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| AES256-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
## Nomes das criptografias OpenSSL e RFC
OpenSSL e IETF RFC 5246 usam nomes diferentes para as mesmas cifras. Para ver uma lista dos nomes das cifras, consulte [Nomes das criptografias OpenSSL e RFC](apigateway-security-policies-list.md#apigateway-secure-connections-openssl-rfc-cipher-names).
## Informações sobre APIs REST e APIs de WebSocket
Para saber mais sobre APIs REST e APIs de WebSocket, consulte [Escolher uma política de segurança para o domínio personalizado no API Gateway](apigateway-custom-domain-tls-version.md) e [Política de segurança para APIs de WebSocket no API Gateway](websocket-api-ciphers.md).
# Nomes de domínio personalizados para APIs HTTP no API Gateway
Os *nomes de domínio personalizados* são URLs mais simples e intuitivos que você pode fornecer aos usuários da API.
Após a implantação da sua API, você e seus clientes podem invocar essa API usando a URL de base padrão com o seguinte formato:
```
https://api-id.execute-api.region.amazonaws.com/stage
```
em que *api-id* é gerado pelo API Gateway, *region* é a região da AWS e *stage* é especificado por você ao implantar a API.
A parte do nome de host do URL, `api-id.execute-api.region.amazonaws.com`, refere-se a um endpoint de API. O endpoint de API padrão é gerado aleatoriamente, difícil de lembrar e não é simples de usar.
Com nomes de domínio personalizados, você pode configurar o nome de host da API e escolher um caminho base (por exemplo, `myservice`) para mapear o URL alternativo para sua API. Por exemplo, um URL de base de API mais amigável pode se tornar:
```
https://api.example.com/myservice
```
## Considerações
As considerações a seguir podem afetar o uso de um nome de domínio personalizado.
+ Um nome de domínio regional personalizado pode ser associado a APIs REST e APIs HTTP. É possível usar as APIs do API Gateway versão 2 para criar e gerenciar nomes de domínio regionais personalizados para APIs REST.
+ Para a versão mínima de TLS, somente o TLS 1.2 é compatível.
+ É necessário criar ou atualizar o registro de recursos do provedor DNS para ser mapeado ao endpoint da API. Sem esse mapeamento, as solicitações de API que forem direcionadas para o nome de domínio personalizado não conseguirão acessar o API Gateway.
+ É possível comportar um número quase infinito de nomes de domínio sem exceder a cota padrão usando um certificado curinga. Para obter mais informações, consulte [Nomes de domínio personalizados curinga](#http-wildcard-custom-domain-names).
## Pré-requisitos
Veja a seguir os pré-requisitos para criar um nome de domínio personalizado.
### Registrar um nome de domínio
É necessário ter um nome de domínio da Internet registrado para configurar nomes de domínio personalizados para as APIs. É possível registrar o domínio da internet usando o [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) ou um registrador de domínios de terceiros da sua escolha. O nome de domínio personalizado pode ser o nome de um subdomínio ou do domínio raiz (também conhecido como “ápex da zona”) de um domínio da internet registrado.
O nome de domínio deve seguir a especificação [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) e pode ter no máximo 63 octetos por etiqueta e 255 octetos no total.
### Certificados para nomes de domínio personalizados
Antes de configurar um nome de domínio personalizado para uma API, você deve ter um certificado SSL/TLS pronto no ACM. Se o ACM não estiver disponível na região da AWS onde você está criando o nome de domínio personalizado, será necessário importar um certificado para o API Gateway nessa região.
Para importar um certificado SSL/TLS, você deve fornecer o corpo do certificado SSL/TLS formatado em PEM, sua chave privada e a cadeia de certificado para o nome de domínio personalizado.
Cada certificado armazenado no ACM é identificado por seu ARN. Com certificados emitidos pelo ACM, não é necessário se preocupar em expor detalhes de certificados confidenciais, como a chave privada. Para usar um certificado gerenciado pela AWS para um nome de domínio, basta fazer referência ao seu ARN.
Se o seu aplicativo usa a fixação de certificados, às vezes chamada de fixação SSL, para fixar um certificado do ACM, talvez o aplicativo não consiga se conectar ao seu domínio após a AWS renovar o certificado. Para ter mais informações, consulte [Problemas de fixação do certificado](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) no *Guia do usuário do AWS Certificate Manager*.
## Nomes de domínio personalizados curinga
Com nomes de domínio personalizados curinga, você pode suportar um número quase infinito de nomes de domínio sem exceder a [cota padrão](limits.md). Por exemplo, você pode dar a cada um de seus clientes seu próprio nome de domínio `customername.api.example.com`.
Para criar um nome de domínio personalizado curinga, especifique um curinga (`*`) como o primeiro subdomínio de um domínio personalizado que representa todos os subdomínios possíveis de um domínio raiz.
Por exemplo, o nome de domínio personalizado curinga `*.example.com` resulta em subdomínios, como `a.example.com`, `b.example.com` e `c.example.com`, que são todos roteados para o mesmo domínio.
Os nomes de domínio personalizados curinga oferecem suporte a configurações distintas dos nomes de domínio personalizados padrão do API Gateway. Por exemplo, em uma única conta da AWS, é possível configurar `*.example.com` e `a.example.com` para se comportarem de forma diferente.
Para criar um nome de domínio personalizado curinga, é necessário fornecer um certificado emitido pelo ACM que foi validado usando o DNS ou o método de validação por e-mail.
**nota**
Não é possível criar um nome de domínio personalizado curinga se uma conta da AWS diferente tiver criado um nome de domínio personalizado que esteja em conflito com o nome de domínio personalizado curinga. Por exemplo, se a conta A tiver criado `a.example.com`, a conta B não poderá criar o nome de domínio personalizado curinga `*.example.com`.
Se a conta A e a conta B compartilham um proprietário, entre em contato com a [Central de Suporte da AWS](https://console.aws.amazon.com/support/home#/) para solicitar uma exceção.
## Próximas etapas para nomes de domínio personalizados
Para configurar um nome de domínio personalizado para uma API HTTP, use a documentação da seção API REST do Guia do desenvolvedor do API Gateway.
Primeiro, especifique o certificado para o nome de domínio personalizado. Para obter mais informações, consulte [Preparar certificados no AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). Depois, crie um nome de domínio regional personalizado. Para obter mais informações, consulte [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md).
# Mapear estágios de API para um nome de domínio personalizado para APIs HTTP
Você usa mapeamentos de API para conectar estágios de API a um nome de domínio personalizado. Depois de criar um nome de domínio e configurar registros DNS, você usa mapeamentos de API para enviar tráfego para as suas APIs utilizando o seu nome de domínio personalizado.
Um mapeamento de API especifica uma API, um estágio e, opcionalmente, um caminho a usar para o mapeamento. Por exemplo, você pode mapear o estágio `production` de uma API para `https://api.example.com/orders`.
Você pode mapear os estágios da API HTTP e REST para o mesmo nome de domínio personalizado.
Antes de criar um mapeamento de API, você deve ter uma API, um estágio e um nome de domínio personalizado. Para saber mais sobre como criar um nome de domínio personalizado, consulte [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md).
## Rotear solicitações de API
Você pode configurar mapeamentos de API com vários níveis, por exemplo, `orders/v1/items` e `orders/v2/items`.
Para mapeamentos de API com vários níveis, o API Gateway encaminha as solicitações ao mapeamento de API que tem o prefixo correspondente mais longo. Para selecionar a API para invocar, o API Gateway considera apenas os caminhos configurados para mapeamentos de API, e não rotas de API. Se nenhum caminho corresponder à solicitação, o API Gateway enviará a solicitação para a API que você mapeou para o caminho vazio `(none)`.
Para nomes de domínio personalizados que usam mapeamentos de API com vários níveis, o API Gateway encaminha as solicitações ao mapeamento de API que tem o prefixo correspondente mais longo.
Por exemplo, considere um nome de domínio personalizado `https://api.example.com` com os seguintes mapeamentos de API:
1. `(none)` mapeado para a API 1.
1. `orders` mapeado para a API 2.
1. `orders/v1/items` mapeado para a API 3.
1. `orders/v2/items` mapeado para a API 4.
1. `orders/v2/items/categories` mapeado para a API 5.
| Solicitação | API selecionada | Explicação |
| --- | --- | --- |
| `https://api.example.com/orders` | `API 2` | A solicitação apresenta correspondência exata a esse mapeamento de API. |
| `https://api.example.com/orders/v1/items` | `API 3` | A solicitação apresenta correspondência exata a esse mapeamento de API. |
| `https://api.example.com/orders/v2/items` | `API 4` | A solicitação apresenta correspondência exata a esse mapeamento de API. |
| `https://api.example.com/orders/v1/items/123` | `API 3` | O API Gateway escolhe o mapeamento com o caminho correspondente mais longo. O `123` no final da solicitação não afeta a seleção. |
| `https://api.example.com/orders/v2/items/categories/5` | `API 5` | O API Gateway escolhe o mapeamento com o caminho correspondente mais longo. |
| `https://api.example.com/customers` | `API 1` | O API Gateway usa o mapeamento vazio como um catch-all. |
| `https://api.example.com/ordersandmore` | `API 2` | O API Gateway escolhe o mapeamento com o prefixo correspondente mais longo. Para um nome de domínio personalizado configurado com mapeamentos de nível único, como somente `https://api.example.com/orders` e `https://api.example.com/`, o API Gateway escolheria `API 1`, pois não há um caminho correspondente com `ordersandmore`. |
## Restrições
+ Em um mapeamento de API, o nome de domínio personalizado e as APIs mapeadas devem estar na mesma conta da AWS.
+ Os mapeamentos de API devem conter apenas letras, números e os caracteres a seguir: `$-_.+!*'()/`.
+ O comprimento máximo para o caminho em um mapeamento de API é de 300 caracteres.
+ É possível ter 200 mapeamentos de API com vários níveis para cada nome de domínio. Esse limite não inclui mapeamento de API com um único nível, como `/prod`.
+ Você só pode mapear APIs HTTP para um nome de domínio personalizado regional com a política de segurança TLS 1.2.
+ Você não pode mapear APIs WebSocket para o mesmo nome de domínio personalizado que uma API HTTP ou API REST.
+ Se você criar mapeamentos de API com vários níveis, o API Gateway mudará todos os nomes de cabeçalho para minúsculas.
## Crie um mapeamento de API
Para criar um mapeamento de API, você deve primeiro criar um nome de domínio personalizado, uma API e um estágio. Para obter informações sobre como criar um nome de domínio personalizado, consulte [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md).
Para obter exemplos de modelos do AWS Serverless Application Model que criam todos os recursos, consulte [Sessões com SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) no GitHub.
------
#### [ Console de gerenciamento da AWS ]
**Para criar um mapeamento de API**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom domain names** (Nomes de domínios personalizados).
1. Selecione um nome de domínio personalizado que você já criou.
1. Escolha **API mappings** (Mapeamentos de API).
1. Escolha **Configure API mappings (Configurar mapeamentos de API)**.
1. Escolha **Add new mapping (Adicionar novo mapeamento)**.
1. Insira uma **API**, um **Estágio** e, opcionalmente, um **Caminho**.
1. Escolha **Salvar**.
------
#### [ AWS CLI ]
O comando [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) a seguir cria um mapeamento de API. Neste exemplo, o API Gateway envia solicitações para `api.example.com/v1/orders` para a API e o estágio especificados.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
O exemplo de CloudFormation a seguir cria um mapeamento de API.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# Desabilitar o endpoint padrão para APIs HTTP
Por padrão, os clientes podem invocar sua API usando o endpoint `execute-api` gerado pelo API Gateway para sua API. Para garantir que os clientes possam acessar sua API somente usando um nome de domínio personalizado, desabilite o endpoint `execute-api` padrão. Quando o endpoint padrão é desabilitado, ele afeta todos os estágios de uma API.
O procedimento a seguir mostra como desabilitar o endpoint padrão de uma API HTTP.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Selecione uma API HTTP.
1. Escolha o ID da API para abrir a página **Detalhes da API**.
1. Em **Detalhes da API**, escolha **Editar**.
1. Em **Endpoint padrão**, selecione **Desabilitar**.
1. Escolha **Salvar**.
Se você ativar as implantações automáticas no estágio, não será necessário reimplantar a API para que a alteração entre em vigor. Caso contrário, você deverá reimplantar a API.
1. (Opcional) Selecione **Implantar** e reimplante a API ou crie uma etapa para que a alteração entre em vigor.
------
#### [ AWS CLI ]
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) indicado abaixo desabilita o endpoint padrão para uma API HTTP:
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
Depois de desabilitar o endpoint padrão, é necessário implantar sua API para que a alteração entre em vigor, a menos que as implantações automáticas estejam habilitadas.
O seguinte comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) cria uma implantação:
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# Tipos de endereço IP para nomes de domínio personalizados para APIs HTTP
Ao criar uma API, você especifica o tipo de endereços IP que podem invocar seu domínio. É possível escolher IPv4 para resolver endereços IPv4 e invocar seu domínio ou escolher pilha dupla para permitir que endereços IPv4 e IPv6 invoquem seu domínio. Recomendamos que você defina o tipo de endereço IP como pilha dupla para aliviar o esgotamento do espaço IP ou para seu procedimento de segurança. Para ter mais informações sobre os benefícios de um tipo de endereço IP de pilha dupla, consulte [IPv6 na AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Considerações sobre tipos de endereço IP
As considerações a seguir podem afetar o uso de tipos de endereço IP.
+ O tipo de endereço IP padrão para nomes de domínio personalizados do API Gateway é IPv4.
+ Seu nome de domínio personalizado não precisa ter o mesmo tipo de endereço IP para todas as APIs associadas a ele. Se você desabilitar seu endpoint de API padrão, isso poderá afetar como os chamadores podem invocar sua API.
## Alterar o tipo de endereço IP de um nome de domínio personalizado
É possível alterar o tipo de endereço IP atualizando a configuração do endpoint do domínio. É possível atualizar a configuração do endpoint do domínio usando o Console de gerenciamento da AWS, a AWS CLI, o CloudFormation ou um SDK da AWS.
------
#### [ Console de gerenciamento da AWS ]
**Como alterar o tipo de endereço IP de um nome de domínio personalizado**
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha um nome de domínio personalizado público.
1. Escolha **Configurações de endpoint**.
1. Em Tipo de endereço IP, escolha **IPv4** ou **Pilha dupla**.
1. Escolha **Salvar**.
------
#### [ AWS CLI ]
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) a seguir atualiza uma API para ter um tipo de endereço IP de pilha dupla:
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
A saída será exibida da seguinte forma:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------
# Proteger as APIs HTTP no API Gateway
O API Gateway fornece várias maneiras de proteger sua API de determinadas ameaças, como usuários mal-intencionados ou picos de tráfego. É possível proteger a sua API com estratégias como configurar alvos de controle de utilização e habilitar o TLS mútuo. Nesta seção, você pode aprender a habilitar esses recursos usando o API Gateway.
**Topics**
+ [Controle de utilização das solicitações das APIs HTTP para ter um melhor throughput no API Gateway](http-api-throttling.md)
+ [Como ativar a autenticação do TLS mútuo para APIs HTTP no API Gateway](http-api-mutual-tls.md)
# Controle de utilização das solicitações das APIs HTTP para ter um melhor throughput no API Gateway
Você pode configurar o controle de utilização para as suas APIs para ajudar a protegê-las da sobrecarga de numerosas solicitações. Os controles de utilização são aplicados de acordo com o melhor esforço e devem ser considerados alvos, e não limites máximos garantidos de solicitações.
O API Gateway controla a utilização das solicitações para a sua API usando o algoritmo do bucket de token, em que um token equivale a uma solicitação. Especificamente, o API Gateway analisa a taxa e uma intermitência de envios de solicitações de todas as APIs na sua conta, por região. No algoritmo do bucket de token, uma intermitência pode permitir a saturação predefinida desses limites, mas há alguns casos em que outros fatores também podem exceder tais limites.
Quando os envios de solicitações excederem a taxa de solicitação de estado fixo e os limites de intermitência, o API Gateway iniciará o controle de utilização de solicitações. Neste momento, pode ser que os clientes recebam respostas de erro `429 Too Many Requests`. Ao capturar essas exceções, o cliente poderá reenviar as solicitações com falha de uma forma que restrinja as taxas.
Como desenvolvedor de APIs, você pode definir os limites alvo para estágios ou rotas de APIs particulares para melhorar a performance geral em todas as APIs na sua conta.
## Controle de utilização no nível da conta por região
Por padrão, o API Gateway controla a utilização das solicitações de estado fixo por segundo (RPS) em todas as APIs de uma conta da AWS, por região. Ele também limita a intermitência (ou seja, o tamanho máximo do bucket) em todas as APIs de uma conta da AWS, por região. No API Gateway, o limite de intermitência representa o número máximo alvo de envios simultâneos de solicitações que ele fará antes de retornar respostas de erro `429 Too Many Requests`. Para obter mais informações sobre cotas de controle de utilização, consulte [Cotas do Amazon API Gateway](limits.md).
Os limites por conta são aplicados a todas as APIs em uma conta em uma região especificada. O limite de taxas no nível da conta pode ser aumentado por meio de uma solicitação; é possível obter limites mais altos com APIs com tempos limite mais curtos e cargas úteis menores. Para solicitar um aumento nos limites de controle de utilização no nível da conta por região, entre em contato com a [Central de Suporte da AWS](https://console.aws.amazon.com/support/home#/). Para obter mais informações, consulte [Cotas do Amazon API Gateway](limits.md). Observe que tais limites não podem ser superiores aos limites de controle de utilização da AWS.
## Limitação em nível de rota
Você pode definir a limitação no nível da rota para substituir as limitações de solicitação no nível da conta para um estágio específico ou para rotas individuais em sua API. Os limites de controle de utilização da rota padrão não podem exceder os limites de taxa em nível de conta.
É possível configurar o controle de utilização de nível de rota usando a AWS CLI. O comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) indicado abaixo configura o controle de utilização personalizado para o estágio especificado e a rota de uma API:
```
aws apigatewayv2 update-stage \
--api-id a1b2c3d4 \
--stage-name dev \
--route-settings '{"GET /pets":{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}'
```
# Como ativar a autenticação do TLS mútuo para APIs HTTP no API Gateway
A autenticação TLS mútua requer autenticação bidirecional entre o cliente e o servidor. Com TLS mútuo, os clientes devem apresentar certificados X.509 para verificar sua identidade a fim de acessar sua API. O TLS mútuo é um requisito comum para a Internet das Coisas (IoT) e aplicações business-to-business.
É possível usar o TLS mútuo juntamente com outras [operações de autorização e autenticação](apigateway-control-access-to-api.md) compatíveis com o API Gateway. O API Gateway encaminha os certificados que os clientes fornecem aos autorizadores do Lambda e às integrações de backend.
**Importante**
Por padrão, os clientes podem invocar sua API usando o endpoint `execute-api` gerado pelo API Gateway para sua API. Para garantir que os clientes possam acessar sua API somente usando um nome de domínio personalizado com TLS mútuo, desabilite o endpoint `execute-api` padrão. Para saber mais, consulte [Desabilitar o endpoint padrão para APIs HTTP](http-api-disable-default-endpoint.md).
## Pré-requisitos do TLS mútuo
Para configurar o TLS mútuo, você precisa de:
+ Um nome de domínio personalizado
+ Pelo menos um certificado configurado no AWS Certificate Manager para o seu nome de domínio personalizado
+ Um armazenamento de confiança configurado e carregado no Amazon S3
### Nomes de domínios personalizados
Para habilitar o TLS mútuo para uma API HTTP, é necessário configurar um nome de domínio personalizado para sua API. Você pode habilitar o TLS mútuo para um nome de domínio personalizado e, depois, fornecer o nome de domínio personalizado aos clientes. Para acessar uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado, os clientes devem apresentar certificados confiáveis em solicitações de API. Você pode encontrar essas informações em [Nomes de domínio personalizados para APIs HTTP no API Gateway](http-api-custom-domain-names.md).
### Uso de certificados emitidos pelo AWS Certificate Manager
É possível solicitar um certificado publicamente confiável diretamente do ACM ou importar certificados públicos ou autoassinados. Para configurar um certificado no ACM, acesse o [ACM](https://console.aws.amazon.com/acm/). Para importar um certificado, continue lendo na seção a seguir.
### Usar um certificado importado ou Autoridade de Certificação Privada da AWS
Para usar um certificado importado para o ACM ou um certificado do Autoridade de Certificação Privada da AWS com TLS mútuo, o API Gateway precisa de um `ownershipVerificationCertificate` emitido pela ACM. Esse certificado de propriedade é utilizado apenas para verificar você se tem permissões para utilizar o nome de domínio. Ele não é usado para o handshake TLS. Se você ainda não tem um `ownershipVerificationCertificate`, acesse [https://console.aws.amazon.com/acm/](https://console.aws.amazon.com/acm/) para configurar um.
Você precisará manter esse certificado válido durante todo o tempo de vida do seu nome de domínio. Se um certificado expirar e a renovação automática falhar, todas as atualizações do nome de domínio serão bloqueadas. Você precisará atualizar o `ownershipVerificationCertificateArn` com um `ownershipVerificationCertificate` válido antes de poder fazer outras alterações. O `ownershipVerificationCertificate` não pode ser usado como um certificado de servidor para outro domínio de TLS mútuo no API Gateway. Se um certificado for reimportado diretamente para o ACM, o emissor deverá permanecer o mesmo.
### Configuração do armazenamento de confiança
Os armazenamentos de confiança são arquivos de texto com extensão `.pem`. Eles são uma lista confiável de certificados de autoridades de certificação. Para usar TLS mútuo, crie um armazenamento confiável de certificados X.509 que podem acessar sua API.
Você deve incluir a cadeia de confiança completa, começando pelo certificado da autoridade de certificação emissora até o certificado CA, em seu armazenamento de confiança. O API Gateway aceita certificados de cliente emitidos por qualquer autoridade de certificação presente na cadeia de confiança. Os certificados podem ser de autoridades de certificação públicas ou privadas. Eles podem ter um tamanho máximo de cadeia de quatro. Você também pode fornecer certificados autoassinados. Os seguintes algoritmos de hash são aceitos no armazenamento de confiança:
+ SHA-256 ou mais forte
+ RSA-2048 ou mais forte
+ ECDSA-256 ou mais forte
O API Gateway valida várias propriedades de certificado. É possível usar autorizadores do Lambda para executar verificações adicionais quando um cliente invoca uma API, incluindo verificar se um certificado foi revogado. O API Gateway valida as seguintes propriedades:
| Validação | Descrição |
| --- | --- |
| Sintaxe X.509 | O certificado deve atender aos requisitos da sintaxe X.509. |
| Integridade | O conteúdo do certificado não pode ter sido alterado do assinado pela autoridade de certificação do armazenamento confiável. |
| Validity | O período de validade do certificado deve ser atual. |
| Encadeamento de nomes/encadeamento de chaves | Os nomes e os assuntos dos certificados devem formar uma cadeia ininterrupta. Eles podem ter um tamanho máximo de cadeia de quatro. |
### Fazer upload do armazenamento de confiança para um bucket do Amazon S3 em um único arquivo
**Example certificates.pem**
```
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
...
```
O comando [cp](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html) da AWS CLI indicado abaixo carrega `certificates.pem` em seu bucket do Amazon S3.
```
aws s3 cp certificates.pem s3://bucket-name
```
## Configurar o TLS mútuo para um nome de domínio personalizado
Para configurar o TLS mútuo para uma API HTTP, é necessário usar um nome de domínio personalizado regional para sua API, com uma versão do TLS mínima de 1.2. Para saber mais sobre como criar e configurar um nome de domínio personalizado, consulte [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md).
**nota**
O TLS mútuo não é suportado para APIs privadas.
Depois de fazer upload do armazenamento de confiança para o Amazon S3, você pode configurar o nome de domínio personalizado para usar TLS mútuo. O comando [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html) indicado abaixo cria um nome de domínio personalizado com TLS mútuo:
```
aws apigatewayv2 create-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=s3://bucket-name/key-name
```
Depois de criar o nome de domínio, é necessário configurar registros DNS e mapeamentos de caminho base para operações da API. Para saber mais, consulte [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md).
## Invocar uma API usando um nome de domínio personalizado que requer TLS mútuo
Para invocar uma API com TLS mútuo habilitado, os clientes precisam apresentar um certificado confiável na solicitação de API. Quando um cliente tenta invocar a API, o API Gateway procura o emissor do certificado de cliente no seu armazenamento de confiança. Para que o API Gateway prossiga com a solicitação, o emissor do certificado e a cadeia de confiança completa até o certificado CA raiz devem estar no seu armazenamento de confiança.
O comando `curl` demonstrativo a seguir envia uma solicitação para `api.example.com,` que inclui `my-cert.pem` na solicitação. `my-key.key` é a chave privada para o certificado.
```
curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com
```
Sua API será invocada somente se o seu armazenamento de confiança confiar no certificado. As seguintes condições farão com que o API Gateway falhe no handshake TLS e negue a solicitação com um código de status `403`. Se seu certificado:
+ não é confiável
+ expirou
+ não usa um algoritmo compatível
**nota**
O API Gateway não verifica se um certificado foi revogado.
## Atualizar o armazenamento de confiança
Para atualizar os certificados no armazenamento de confiança, faça upload de um novo pacote de certificados para o Amazon S3. Em seguida, você poderá atualizar o nome de domínio personalizado para usar o certificado atualizado.
Use o [Versionamento do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) para manter várias versões do armazenamento de confiança. Quando o nome de domínio personalizado é atualizado para usar uma nova versão de armazenamento de confiança, o API Gateway exibirá avisos se os certificados forem inválidos.
O API Gateway produz avisos de certificado somente quando o nome de domínio é atualizado. O API Gateway não o notificará se um certificado carregado anteriormente expirar.
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) indicado abaixo atualiza um nome de domínio personalizado para usar uma nova versão do armazenamento de confiança:
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreVersion='abcdef123'
```
## Desativar o TLS mútuo
Para desativar o TLS mútuo para um nome de domínio personalizado, remova o armazenamento de confiança do nome de domínio personalizado, conforme mostrado no comando a seguir.
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) indicado abaixo atualiza um nome de domínio personalizado para remover o armazenamento de confiança do seu nome de domínio personalizado:
```
aws apigatewayv2 update-domain-name \
--domain-name api.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--mutual-tls-authentication TruststoreUri=''
```
## Solucionar problemas de TLS mútuo para a API HTTP
O tópico a seguir fornece orientações para a solução de erros e problemas que você pode encontrar ao ativar o TLS mútuo.
### Solução de problemas de avisos de certificado
Ao criar um nome de domínio personalizado com TLS mútuo, o API Gateway exibirá avisos se os certificados no armazenamento de confiança não forem válidos. Isso também pode ocorrer ao atualizar um nome de domínio personalizado para usar um novo armazenamento de confiança. Os avisos indicam o problema com o certificado e o assunto que produziu o aviso. O TLS mútuo ainda está habilitado para sua API, mas alguns clientes podem não conseguir acessar a API.
Para identificar o certificado que produziu o aviso, é necessário decodificar os certificados em seu armazenamento de confiança. É possível usar ferramentas como `openssl` para decodificar os certificados e identificar os assuntos.
O comando a seguir exibe o conteúdo de um certificado, incluindo o assunto.
```
openssl x509 -in certificate.crt -text -noout
```
Atualize ou remova os certificados que produziram avisos e, depois, faça upload de um novo armazenamento de confiança para o Amazon S3. Após o upload do novo armazenamento de confiança, atualize o nome de domínio personalizado para usar o novo armazenamento de confiança.
### Solução de problemas de conflitos de nomes de domínios
O erro `"The certificate subject conflicts with an existing certificate from a different issuer."` significa que mais de uma autoridade de certificação emitiu um certificado para esse domínio. Para cada entidade no certificado, pode haver somente um emissor no API Gateway para domínios do TLS mútuos. Você precisará obter todos os seus certificados para esse assunto por meio de um único emissor. Se o problema for com um certificado sobre o qual você não tem controle, e você é capaz de provar que é o dono do nome de domínio, [entre em contato com Suporte](https://console.aws.amazon.com/support/cases#/create) para abrir um ticket.
### Solução de problemas de mensagens de status de nomes de domínio
`PENDING_CERTIFICATE_REIMPORT`: isso significa que você reimportou um certificado para o ACM e ele falhou na validação porque o novo certificado tem um SAN (nome alternativo de entidade) que não é coberto pelo `ownershipVerificationCertificate` ou o assunto ou os SANs no certificado não cobrem o nome de domínio. Algo pode estar configurado incorretamente ou um certificado inválido foi importado. Você precisa reimportar um certificado válido para o ACM. Para obter mais informações sobre a validação, consulte [Validação da propriedade de domínios](https://docs.aws.amazon.com/acm/latest/userguide/domain-ownership-validation.html).
`PENDING_OWNERSHIP_VERIFICATION`: isso significa que seu certificado verificado anteriormente expirou e o ACM não conseguiu renová-lo automaticamente. Você precisará renovar o certificado ou solicitar um novo certificado. Mais informações sobre renovação de certificados podem ser encontradas no guia [Solução de problemas de renovação de certificados gerenciados do ACM](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-renewal.html).
# Monitorar APIs HTTP no API Gateway
É possível usar métricas do CloudWatch e CloudWatch Logs para monitorar APIs HTTP. Combinando logs e métricas, você pode registrar erros em log e monitorar o desempenho da API.
**nota**
O API Gateway pode não gerar logs e métricas nos seguintes casos:
Erros 413 de entidade de solicitação muito grande
Erros 429 de muitas solicitações excessivos
Erros da série 400 de solicitações enviadas a um domínio personalizado que não tem mapeamento de API
Erros da série 500 causados por falhas internas
**Topics**
+ [Monitorar métricas do CloudWatch para APIs HTTP no API Gateway](http-api-metrics.md)
+ [Configurar registro em log para APIs HTTP no API Gateway](http-api-logging.md)
# Monitorar métricas do CloudWatch para APIs HTTP no API Gateway
É possível monitorar a execução da API usando o CloudWatch, que coleta e processa dados brutos do API Gateway em métricas legíveis, quase em tempo real. Essas estatísticas são registradas para um período de 15 meses, de forma que você possa acessar informações históricas e ganhar uma perspectiva melhor sobre como seu serviço ou aplicativo web está se saindo. Por padrão, os dados de métricas do API Gateway são enviados automaticamente para o CloudWatch em períodos de um minuto. Para monitorar suas métricas, crie um painel do CloudWatch para sua API. Para ter mais informações sobre como criar um painel do CloudWatch, consulte [Criar um painel do CloudWatch ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create_dashboard.html) no *Guia do usuário do Amazon CloudWatch*. Para obter mais informações, consulte [O que é o Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) no *Guia do usuário do Amazon CloudWatch*.
As métricas a seguir são compatíveis com APIs HTTP. Você também pode habilitar métricas detalhadas para gravar métricas de nível de rota no Amazon CloudWatch.
| Métrica | Descrição |
| --- | --- |
| 4xx | O número de erros no lado do cliente capturados em um determinado período. |
| 5xx | O número de erros do servidor capturados em um período determinado. |
| Contagem | O número total de solicitações de API em um determinado período. |
| IntegrationLatency | O tempo que o API Gateway leva para receber uma resposta do backend depois de retransmitir uma solicitação para o backend. |
| Latência | O tempo que o API Gateway leva para devolver uma resposta para um cliente depois de receber uma solicitação do cliente. A latência inclui a latência de integração e outras despesas gerais do API Gateway. |
| DataProcessed | A quantidade de dados processados em bytes. |
É possível usar as dimensões na tabela a seguir para filtrar métricas do API Gateway.
| Dimensão | Descrição |
| --- | --- |
| ApiId | Filtra as métricas do API Gateway para uma API com o ID de API especificado. |
| ID da API, estágio | Filtra métricas do API Gateway para um estágio de API com o ID da API especificada e o ID do estágio. |
| ApiId, método, recurso, estágio | Filtra métricas do API Gateway para um método de API com o ID da API especificada, ID do estágio, caminho do recurso e ID da rota. O API Gateway não enviará essas métricas a menos que você tenha habilitado explicitamente métricas detalhadas do CloudWatch. Isso pode ser feito ao chamar a ação [UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html) da API REST V2 do API Gateway para atualizar a propriedade `detailedMetricsEnabled` como `true`. Como alternativa, você pode chamar o comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) da AWS CLI para atualizar a propriedade `DetailedMetricsEnabled` para `true`. Permitir essas métricas incorrerá em cobranças adicionais na conta. Para obter informações de definição de preço, consulte [Definição de preço do Amazon CloudWatch](https://aws.amazon.com/cloudwatch/pricing/). |
# Configurar registro em log para APIs HTTP no API Gateway
É possível ativar o registro em log para gravar logs no CloudWatch Logs. Você pode usar [variáveis de registro em log](http-api-logging-variables.md) para personalizar o conteúdo de seus logs.
Para melhorar seu procedimento de segurança, recomendamos que você grave logs no CloudWatch Logs referentes a todos os estágios da sua API HTTP. Você pode precisar fazer isso para cumprir vários requisitos de conformidade. Para ter mais informações, consulte [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) no *Guia do usuário do AWS Security Hub*.
Para ativar o registro em log para uma API HTTP, é necessário fazer o seguinte.
1. Seu usuário deve ter as permissões necessárias para ativar o registro em log.
1. Crie um grupo de logs do CloudWatch Logs.
1. Forneça o ARN do grupo de logs do CloudWatch Logs para um estágio de sua API.
## Permissões para ativar o registro em log
Para ativar o registro em log para uma API, seu usuário deve ter as permissões a seguir.
**Example**
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:GetLogEvents",
"logs:FilterLogEvents"
],
"Resource": "arn:aws:logs:us-east-2:123456789012:log-group:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogDelivery",
"logs:PutResourcePolicy",
"logs:UpdateLogDelivery",
"logs:DeleteLogDelivery",
"logs:CreateLogGroup",
"logs:DescribeResourcePolicies",
"logs:GetLogDelivery",
"logs:ListLogDeliveries"
],
"Resource": "*"
}
]
}
```
## Criar um grupo de logs e ativar o registro em log para APIs HTTP
É possível criar um grupo de logs e ativar o registro em log de acesso usando o Console de gerenciamento da AWS ou a AWS CLI.
------
#### [ Console de gerenciamento da AWS ]
1. Crie um grupo de logs.
Para saber como criar um grupo de logs usando o console, consulte [Criar um grupo de logs no Guia do usuário do Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html).
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Selecione uma API HTTP.
1. Na guia **Monitor** no painel de navegação principal, selecione **Logging** (Registro em log).
1. Selecione um estágio para ativar o registro em log e **Select** (Selecionar).
1. Selecione **Edit** (Editar) para ativar o registro em log de acesso.
1. Ative **Access logging** (Registro em log de acesso), insira um CloudWatch Logs e selecione um formato de log.
1. Escolha **Salvar**.
------
#### [ AWS CLI ]
O comando [create-log-group](https://docs.aws.amazon.com/cli/latest/reference/logs/create-log-group.html) indicado abaixo cria um grupo de logs:
```
aws logs create-log-group --log-group-name my-log-group
```
Você precisa do nome do recurso da Amazon (ARN) do seu grupo de logs para ativar o registro em log. O formato do ARN é arn:aws:logs:*region*:*account-id*:log-group:*log-group-name*.
O comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) indicado abaixo ativa o registro em log para o estágio `$default` de uma API HTTP:
```
aws apigatewayv2 update-stage --api-id abcdef \
--stage-name '$default' \
--access-log-settings '{"DestinationArn": "arn:aws:logs:region:account-id:log-group:log-group-name", "Format": "$context.identity.sourceIp - - [$context.requestTime] \"$context.httpMethod $context.routeKey $context.protocol\" $context.status $context.responseLength $context.requestId"}'
```
------
## Formatos de log demonstrativos
Alguns formatos demonstrativos de log de acesso usados com frequência estão disponíveis no console do API Gateway e são listados a seguir.
+ `CLF` ([Formato de log comum](https://httpd.apache.org/docs/current/logs.html#common)):
```
$context.identity.sourceIp - - [$context.requestTime] "$context.httpMethod $context.routeKey $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId
```
+ `JSON`:
```
{ "requestId":"$context.requestId", "ip": "$context.identity.sourceIp", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod","routeKey":"$context.routeKey", "status":"$context.status","protocol":"$context.protocol", "responseLength":"$context.responseLength", "extendedRequestId": "$context.extendedRequestId" }
```
+ `XML`:
```
$context.identity.sourceIp $context.requestTime $context.httpMethod $context.routeKey $context.status $context.protocol $context.responseLength $context.extendedRequestId
```
+ `CSV` (valores separados por vírgula):
```
$context.identity.sourceIp,$context.requestTime,$context.httpMethod,$context.routeKey,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId
```
# Personalizar logs de acesso à API HTTP
É possível usar as variáveis a seguir para personalizar logs de acesso para APIs HTTP. Para saber mais sobre logs de acesso para APIs HTTP, consulte [Configurar registro em log para APIs HTTP no API Gateway](http-api-logging.md).
| Parâmetro | Descrição |
| --- | --- |
| \$1context.accountId | O ID da conta da AWS do proprietário da API |
| \$1context.apiId | O identificador que o API Gateway atribui à sua API. |
| \$1context.authorizer.claims.property | Uma propriedade das declarações retornadas do JSON Web Token (JWT) depois que o chamador do método é autenticado com êxito, como `$context.authorizer.claims.username`. Para obter mais informações, consulte [Controlar o acesso a APIs HTTP com autorizadores JWT no API Gateway](http-api-jwt-authorizer.md). Chamar `$context.authorizer.claims` retorna um valor nulo. |
| \$1context.authorizer.error | A mensagem de erro retornada de um autorizador. |
| \$1context.authorizer.property | O valor do par de chave/valor especificado do mapa `context` retornado por uma função de autorizador do Lambda do API Gateway. Por exemplo, se o autorizador retornar o seguinte mapa `context`: "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} chamar `$context.authorizer.key` retorna a string `"value"`, chamar `$context.authorizer.numKey` retorna `1` e chamar `$context.authorizer.boolKey` retorna `true`. |
| \$1context.awsEndpointRequestId | O ID da solicitação do endpoint da AWS do cabeçalho `x-amz-request-id` ou `x-amzn-requestId`. |
| \$1context.awsEndpointRequestId2 | O ID da solicitação do endpoint da AWS do cabeçalho `x-amz-id-2`. |
| \$1context.customDomain.basePathMatched | O caminho para um mapeamento da API correspondente a uma solicitação de entrada. Aplicável quando um cliente usa um nome de domínio personalizado para acessar uma API. Por exemplo, se um cliente enviar uma solicitação para `https://api.example.com/v1/orders/1234` e a solicitação corresponder ao mapeamento da API com o caminho `v1/orders`, o valor será `v1/orders`. Para saber mais, consulte [Mapear estágios de API para um nome de domínio personalizado para APIs HTTP](http-api-mappings.md). |
| \$1context.dataProcessed | A quantidade de dados processados em bytes. |
| \$1context.domainName | O nome de domínio completo usado para invocar a API. Ele deve ser o mesmo que o cabeçalho `Host` de entrada. |
| \$1context.domainPrefix | O primeiro rótulo do `$context.domainName`. |
| \$1context.error.message | Uma string que contém uma mensagem de erro do API Gateway. |
| \$1context.error.messageString | O valor citado de \$1context.error.message, ou seja, "\$1context.error.message". |
| \$1context.error.responseType | Um tipo de `GatewayResponse`. Para obter mais informações, consulte [Monitorar a execução de APIs de WebSocket com métricas do CloudWatch](apigateway-websocket-api-logging.md) e [Configurar respostas do gateway para personalizar respostas de erro](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.extendedRequestId | Equivale a \$1context.requestId. |
| \$1context.httpMethod | O método HTTP utilizado. Os valores válidos incluem: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` e `PUT`. |
| \$1context.identity.accountId | O ID da conta da AWS associado à solicitação. Compatível com rotas que usam a autorização do IAM. |
| \$1context.identity.caller | O identificador da entidade do autor da chamada que assinou a solicitação. Compatível com rotas que usam a autorização do IAM. |
| \$1context.identity.cognitoAuthenticationProvider | Uma lista separada por vírgulas de todos os provedores de autenticação do Amazon Cognito usados pelo autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. Por exemplo, para uma identidade de um grupo de usuários do Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Consulte informações sobre os provedores de autenticação do Amazon Cognito disponível em [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) no *Guia do desenvolvedor do Amazon Cognito*. |
| \$1context.identity.cognitoAuthenticationType | O tipo de autenticação do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. Os valores possíveis incluem `authenticated` para identidades autenticadas e `unauthenticated` para identidades não autenticadas. |
| \$1context.identity.cognitoIdentityId | O ID de identidade do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | O ID do grupo de identidades do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. |
| \$1context.identity.principalOrgId | O [ID da organização da AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). Compatível com rotas que usam a autorização do IAM. |
| \$1context.identity.clientCert.clientCertPem | O certificado de cliente codificado por PEM que o cliente apresentou durante a autenticação TLS mútua. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. |
| \$1context.identity.clientCert.subjectDN | O nome distinto do assunto do certificado apresentado por um cliente. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. |
| \$1context.identity.clientCert.issuerDN | O nome distinto do emissor do certificado apresentado por um cliente. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. |
| \$1context.identity.clientCert.serialNumber | O número de série do certificado. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. |
| \$1context.identity.clientCert.validity.notBefore | A data antes da qual o certificado é inválido. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. |
| \$1context.identity.clientCert.validity.notAfter | A data após a qual o certificado é inválido. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. |
| \$1context.identity.sourceIp | O endereço IP de origem da conexão TCP mais próxima que está fazendo a solicitação para o endpoint do API Gateway. |
| \$1context.identity.user | O identificador da entidade do usuário que será autorizado contra o acesso a recursos. Compatível com rotas que usam a autorização do IAM. |
| \$1context.identity.userAgent | O cabeçalho [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) do autor da chamada da API. |
| \$1context.identity.userArn | O Nome do Recurso Amazon (ARN) do usuário efetivo identificado após a autenticação. Compatível com rotas que usam a autorização do IAM. Para obter mais informações, consulte [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). |
| \$1context.integration.error | A mensagem de erro retornada de uma integração. Equivale a \$1context.integrationErrorMessage. |
| \$1context.integration.integrationStatus | Para a integração de proxy do Lambda, o código de status retornado pelo AWS Lambda, e não pelo código de função do Lambda de backend. |
| \$1context.integration.latency | A latência de integração em ms. Equivale a \$1context.integrationLatency. |
| \$1context.integration.requestId | O ID da solicitação do endpoint da AWS. Equivale a \$1context.awsEndpointRequestId. |
| \$1context.integration.status | O código de status retornado de uma integração. Para integrações de proxy do Lambda, esse é o código de status que seu código de função do Lambda retorna. |
| \$1context.integrationErrorMessage | Uma string que contém uma mensagem de erro de integração. |
| \$1context.integrationLatency | A latência de integração em ms. |
| \$1context.integrationStatus | Para a integração de proxy do Lambda, esse parâmetro representa o código de status retornado pelo AWS Lambda, e não pela função do Lambda de backend. |
| \$1context.path | O caminho da solicitação. Por exemplo, /\$1stage\$1/root/child. |
| \$1context.protocol | O protocolo de solicitação, por exemplo, , HTTP/1.1. As APIs do API Gateway podem aceitar solicitações HTTP/2, mas o API Gateway envia solicitações para integrações de back-end usando HTTP/1.1. Como resultado, o protocolo de solicitação é registrado como HTTP/1.1 mesmo se um cliente enviar uma solicitação que usa HTTP/2. |
| \$1context.requestId | O ID que o API Gateway atribui à solicitação de API. |
| \$1context.requestTime | O horário da solicitação [CLF](https://httpd.apache.org/docs/current/logs.html#common) formatado (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | O horário da solicitação [Epoch](https://en.wikipedia.org/wiki/Unix_time) formatado. |
| \$1context.responseLatency | A latência da resposta em ms. |
| \$1context.responseLength | O tamanho da carga de resposta em bytes. |
| \$1context.routeKey | A chave de rota da solicitação da API, por exemplo, `/pets`. |
| \$1context.stage | O estágio de implantação da solicitação de API (por exemplo, `beta` ou `prod`). |
| \$1context.status | O status de resposta do método. |
# Solução de problemas com APIs HTTP no API Gateway
Os tópicos a seguir fornecem orientações para a solução de erros e problemas que podem ser encontrados durante o uso de APIs HTTP.
**Topics**
+ [Solução de problemas com integrações do Lambda para APIs HTTP](http-api-troubleshooting-lambda.md)
+ [Solução de problemas com os autorizadores JWT da API HTTP](http-api-troubleshooting-jwt.md)
# Solução de problemas com integrações do Lambda para APIs HTTP
O tópico a seguir fornece orientações para a solução de erros e problemas que podem ser encontrados durante o uso de [AWS LambdaIntegrações do ](http-api-develop-integrations-lambda.md) com APIs HTTP.
## Problema: minha API com uma integração do Lambda retorna `{"message":"Internal Server Error"}`
Para solucionar o erro interno do servidor, adicione a `$context.integrationErrorMessage` [variável de registro em log](http-api-logging-variables.md) ao formato de log e visualize os logs da API HTTP. Para conseguir isso, faça o seguinte:
**Como criar um grupo de logs usando o Console de gerenciamento da AWS**
1. Abra o console do CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Escolha **Grupos de logs**.
1. Escolha **Criar grupo de logs**.
1. Insira um nome para o grupo de logs e escolha **Criar**.
1. Anote o nome de recurso da Amazon (ARN) do grupo de logs. O formato do ARN é arn:aws:logs:*region*: *account-id*:log-group:*log-group-name*. O ARN do grupo de logs é necessário para habilitar o registro de acesso em logs para a API HTTP.
**Como adicionar a variável de registro em log `$context.integrationErrorMessage`**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha sua API HTTP.
1. Em **Monitor**, escolha **Registro em log**.
1. Selecione um estágio da API.
1. Escolha **Editar** e habilite o registro de acesso em logs.
1. Para o **destino do log**, insira o ARN do grupo de log que você criou na etapa anterior.
1. Em **Formato de log**, escolha **CLF**. O API Gateway cria um exemplo de formato de log.
1. Adicione `$context.integrationErrorMessage` ao final do formato de log.
1. Escolha **Save** (Salvar).
**Como visualizar os logs da API**
1. Gere os logs. Use um navegador ou `curl` para invocar a API.
```
$curl https://api-id.execute-api.us-west-2.amazonaws.com/route
```
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha sua API HTTP.
1. Em **Monitor**, escolha **Registro em log**.
1. Selecione o estágio da API para o qual você habilitou o registro em log.
1. Escolha **View logs in CloudWatch (Exibir logs no CloudWatch)**.
1. Escolha o stream de logs mais recente para visualizar os logs da API HTTP.
1. A entrada de log deve ser semelhante à seguinte:
![\[Entrada de log do CloudWatch Logs mostrando a mensagem de erro de integração do Lambda.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/troubleshoot-http-api-logs.png)
Como adicionamos `$context.integrationErrorMessage` ao formato de log, vemos uma mensagem de erro nos logs que resume o problema.
Os logs podem incluir uma mensagem de erro diferente que indica que há um problema com o código de função do Lambda. Nesse caso, confira o código de função do Lambda e verifique se a função do Lambda retorna uma resposta no [formato necessário](http-api-develop-integrations-lambda.md#http-api-develop-integrations-lambda.response). Se os logs não incluírem uma mensagem de erro, adicione `$context.error.message` e `$context.error.responseType` ao seu formato de log para obter mais informações para ajudar a solucionar problemas.
Nesse caso, os logs mostram que o API Gateway não tinham as permissões necessárias para invocar a função do Lambda.
Quando você cria uma integração do Lambda no console do API Gateway, este configura automaticamente as permissões para invocar a função do Lambda. Ao criar uma integração do Lambda usando a AWS CLI, CloudFormation ou um SDK, você deve conceder permissões para o API Gateway invocar a função. Os comandos [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) indicados abaixo concedem permissões para possibilitar que diferentes rotas da API HTTP invoquem uma função do Lambda.
**Example Exemplo: para o estágio `$default` e a rota `$default` de uma API HTTP**
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-invoke-permissions \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/\$default/\$default"
```
**Example Exemplo: para o estágio `prod` e a rota `test` de uma API HTTP**
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-invoke-permissions \
--action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/prod/*/test"
```
[Confirme a política de função](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html) na guia **Permissions (Permissões)** do console do Lambda.
Tente invocar a API novamente. Você deverá ver a resposta da função do Lambda.
# Solução de problemas com os autorizadores JWT da API HTTP
O tópico a seguir fornece orientações para a solução de erros e problemas que podem ser encontrados durante o uso dos autorizadores JSON Web Token (JWT) com APIs HTTP.
## Problema: minha API retorna `401 {"message":"Unauthorized"}`
Verifique o cabeçalho `www-authenticate` na resposta da API.
O comando a seguir usa `curl` para enviar uma solicitação para uma API com um autorizador de JWT que usa `$request.header.Authorization` como sua origem de identidade.
```
$curl -v -H "Authorization: token" https://api-id.execute-api.us-west-2.amazonaws.com/route
```
A resposta da API inclui um cabeçalho `www-authenticate`.
```
...
< HTTP/1.1 401 Unauthorized
< Date: Wed, 13 May 2020 04:07:30 GMT
< Content-Length: 26
< Connection: keep-alive
< www-authenticate: Bearer scope="" error="invalid_token" error_description="the token does not have a valid audience"
< apigw-requestid: Mc7UVioPPHcEKPA=
<
* Connection #0 to host api-id.execute-api.us-west-2.amazonaws.com left intact
{"message":"Unauthorized"}}
```
Nesse caso, o cabeçalho `www-authenticate` mostra que o token não foi emitido para um público válido. Para o API Gateway autorizar uma solicitação, a declaração `aud` ou `client_id` do JWT deve corresponder a uma das entradas de público configuradas para o autorizador. O API Gateway valida `client_id` somente se `aud` não estiver presente. Quando `aud` e `client_id` estão presentes, o API Gateway avalia `aud`.
Também é possível decodificar um JWT e verificar se ele corresponde ao emissor, ao público e aos escopos que a API exige. O site [jwt.io](https://jwt.io/) pode depurar JWTs no navegador. A OpenID Foundation mantém uma [lista de bibliotecas para trabalhar com JWTs](https://openid.net/developers/jwt-jws-jwe-jwk-and-jwa-implementations/).
Para saber mais sobre os autorizadores JWT, consulte [Controlar o acesso a APIs HTTP com autorizadores JWT no API Gateway](http-api-jwt-authorizer.md).