# Invocar uma função do Lambda usando um endpoint do Amazon API Gateway
É possível criar uma API da Web com um endpoint HTTP para a função do Lambda usando o Amazon API Gateway. O API Gateway fornece ferramentas para criar e documentar APIs da Web que direcionam as solicitações HTTP para as funções do Lambda. É possível proteger o acesso à sua API com controles de autenticação e autorização. Suas APIs podem veicular o tráfego pela Internet ou podem ser acessadas somente dentro da VPC.
**dica**
O Lambda fornece duas maneiras de invocar uma função por meio de um endpoint HTTP: API Gateway e URLs de funções do Lambda. Se não tiver certeza de qual é o melhor método para seu caso de uso, consulte [Seleção de um método para invocar a função do Lambda usando uma solicitação HTTP](apig-http-invoke-decision.md).
Os recursos em sua API definem um ou mais métodos, como GET ou POST. Os métodos têm uma integração que direciona solicitações para uma função do Lambda ou outro tipo de integração. É possível definir cada recurso e método individualmente ou usar tipos especiais de recurso e método para corresponder todas as solicitações que se enquadram em um padrão. Um [recurso proxy](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html) captura todos os caminhos abaixo de um recurso. O método `ANY` captura todos os métodos HTTP.
**Topics**
+ [Escolher um tipo de API](#services-apigateway-apitypes)
+ [Adicionar um endpoint público à sua função do Lambda](#apigateway-add)
+ [Integração de proxy](#apigateway-proxy)
+ [Formato de eventos](#apigateway-example-event)
+ [Formato de resposta](#apigateway-types-transforms)
+ [Permissões](#apigateway-permissions)
+ [Aplicação de exemplo](#services-apigateway-samples)
+ [O manipulador de eventos do Powertools para AWS Lambda](#services-apigateway-powertools)
+ [Tutorial: Uso do Lambda com API Gateway](services-apigateway-tutorial.md)
+ [Tratamento de erros do Lambda com uma API do API Gateway](services-apigateway-errors.md)
+ [Seleção de um método para invocar a função do Lambda usando uma solicitação HTTP](apig-http-invoke-decision.md)
## Escolher um tipo de API
O API Gateway é compatível com três tipos de API que invocam as funções do Lambda:
+ [API HTTP](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html): uma API RESTful leve e de baixa latência.
+ [API REST](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html): uma API RESTful personalizável e com muitos recursos.
+ [API de WebSocket](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html): uma API da Web que mantém conexões persistentes com clientes para uma comunicação duplex completa.
As APIs HTTP e REST são ambas APIs RESTful que processam solicitações de HTTP e retornam respostas. As APIs HTTP são mais recentes e são criadas com a versão 2 da API do API Gateway. Os recursos abaixo são novos para APIs HTTP:
**Recursos da API HTTP**
+ **Implantações automáticas**: quando você modifica rotas ou integrações, as alterações são implantadas automaticamente em estágios com implantação automática habilitada.
+ **Estágio padrão**: você pode criar um estágio padrão (`$default`) para veicular solicitações no caminho raiz do URL da API. Para estágios nomeados, você deve incluir o nome do estágio no início do caminho.
+ **Configuração de CORS**: você pode configurar sua API para adicionar cabeçalhos CORS às respostas de saída em vez de adicioná-las manualmente no código da função.
As APIs REST são APIs RESTful clássicas às quais o API Gateway oferece suporte desde o lançamento. As APIs REST têm atualmente mais recursos de personalização, integração e gerenciamento.
**Recursos da API REST**
+ **Tipos de integração**: APIs REST são compatíveis com integrações personalizadas do Lambda. Com uma integração personalizada, você pode enviar apenas o corpo da solicitação para a função ou aplicar um modelo de transformação ao corpo da solicitação antes de enviá-la para a função.
+ **Controle de acesso**: as APIs REST oferecem suporte a mais opções de autenticação e autorização.
+ **Monitoramento e rastreamento**: as APIs REST oferecem suporte ao monitoramento do AWS X-Ray e a outras opções de log.
Para obter uma comparação detalhada, consulte [Escolher entre APIs HTTP e REST](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html) no *Guia do desenvolvedor do API Gateway*.
As APIs WebSocket também usam a API do API Gateway versão 2 e oferecem suporte a um conjunto de recursos semelhante. Use uma API WebSocket para aplicativos que se beneficiam de uma conexão persistente entre o cliente e a API. As APIs WebSocket oferecem uma comunicação duplex completa, o que significa que tanto o cliente quanto a API podem enviar mensagens continuamente sem esperar por uma resposta.
As APIs HTTP oferecem suporte a um formato de evento simplificado (versão 2.0). Para obter um exemplo de um evento de API HTTP, consulte [Criação integrações de proxy AWS Lambda para APIs HTTP no API Gateway](https://docs.aws.amazon.com//apigateway/latest/developerguide/http-api-develop-integrations-lambda.html).
Para obter mais informações, consulte [Criar integrações de proxy do AWS Lambda para APIs HTTP no API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html).
## Adicionar um endpoint público à sua função do Lambda
**Como adicionar um endpoint público à sua função do Lambda**
1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda.
1. Escolha uma função.
1. Em **Visão geral da função**, escolha **Adicionar gatilho**.
1. Selecione **API Gateway**.
1. Escolher **Create an API** (Criar uma API) ou **Use an existing API** (Usar uma API existente).
1. **New API** (Nova API): para **API type** (Tipo de API), escolha **HTTP API**. Para obter mais informações, consulte [Escolher um tipo de API](#services-apigateway-apitypes).
1. **Existing API**: selecione a API na lista suspensa ou insira seu ID (por exemplo, r3pmxmplak).
1. Em **Security (Segurança)**, escolha **Open (Abrir)**.
1. Escolha **Adicionar**.
## Integração de proxy
As APIs do API Gateway são compostas por estágios, recursos, métodos e integrações. O estágio e o recurso determinam o caminho do endpoint:
**Formato do caminho da API**
+ `/prod/`: o estágio e o recurso raiz de `prod`.
+ `/prod/user`: o estágio de `prod` e o recurso de `user`.
+ `/dev/{proxy+}`: qualquer rota no estágio de `dev`.
+ `/`: (APIs HTTP) o estágio padrão e o recurso raiz.
Uma integração do Lambda mapeia uma combinação de caminho e método de HTTP para uma função do Lambda. É possível configurar o API Gateway para transmitir o corpo da solicitação de HTTP no estado em que se encontra (integração personalizada) ou para encapsular o corpo da solicitação em um documento que inclui todas as informações de solicitação, inclusive cabeçalhos, recursos, caminho e método.
Para obter mais informações, consulte [Integrações de proxy do Lambda no API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html).
## Formato de eventos
O Amazon API Gateway invoca sua função [de modo síncrono](invocation-sync.md) com um evento que contém uma representação JSON da solicitação de HTTP. Para uma integração personalizada, o evento é o corpo da solicitação. Para uma integração de proxy, o evento tem uma estrutura definida. Para ver um exemplo de um evento de proxy de uma API REST do API Gateway, consulte [Formato de entrada de uma função do Lambda para integração de proxy](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format) no *Guia do desenvolvedor do API Gateway*.
## Formato de resposta
O API Gateway aguarda uma resposta de sua função e retransmite o resultado para o chamador. Para uma integração personalizada, defina uma resposta de integração e uma resposta de método para converter a saída da função em uma resposta de HTTP. Para uma integração de proxy, a função deve responder com uma representação da resposta em um formato específico.
O exemplo abaixo mostra um objeto de resposta de uma função Node.js. O objeto de resposta representa uma resposta de HTTP bem-sucedida que contém um documento JSON.
**Example index.mjs: objeto de resposta de integração de proxy (Node.js)**
```
var response = {
"statusCode": 200,
"headers": {
"Content-Type": "application/json"
},
"isBase64Encoded": false,
"multiValueHeaders": {
"X-Custom-Header": ["My value", "My other value"],
},
"body": "{\n \"TotalCodeSize\": 104330022,\n \"FunctionCount\": 26\n}"
}
```
O runtime do Lambda serializa o objeto de resposta em JSON e o envia para a API. A API analisa a resposta e a utiliza para criar uma resposta de HTTP que, então, é enviada para o cliente que fez a solicitação original.
**Example Resposta HTTP**
```
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 55
< Connection: keep-alive
< x-amzn-RequestId: 32998fea-xmpl-4268-8c72-16138d629356
< X-Custom-Header: My value
< X-Custom-Header: My other value
< X-Amzn-Trace-Id: Root=1-5e6aa925-ccecxmplbae116148e52f036
<
{
"TotalCodeSize": 104330022,
"FunctionCount": 26
}
```
## Permissões
O Amazon API Gateway recebe permissão para invocar sua função por meio da [política baseada em recursos](access-control-resource-based.md) da função. É possível conceder permissão de invocar a uma API inteira ou conceder acesso limitado a um estágio, recurso ou método.
Ao adicionar uma API à sua função usando o console do Lambda, o console do API Gateway ou em um modelo de AWS SAM, a política baseada em recursos da função é atualizada automaticamente. Veja abaixo um exemplo de política de função.
**Example política de função**
****
```
{
"Version":"2012-10-17",
"Id": "default",
"Statement": [
{
"Sid": "nodejs-apig-functiongetEndpointPermissionProd-BWDBXMPLXE2F",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "lambda:InvokeFunction",
"Resource": "arn:aws:lambda:us-east-2:{{111122223333}}:function:nodejs-apig-function-1G3MXMPLXVXYI",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:execute-api:us-east-2:{{111122223333}}:ktyvxmpls1/*/GET/"
}
}
}
]
}
```
É possível gerenciar manualmente as permissões da política de função com as seguintes operações da API:
+ [AddPermission](https://docs.aws.amazon.com/lambda/latest/api/API_AddPermission.html)
+ [RemovePermission](https://docs.aws.amazon.com/lambda/latest/api/API_RemovePermission.html)
+ [GetPolicy](https://docs.aws.amazon.com/lambda/latest/api/API_GetPolicy.html)
Para conceder permissão de invocação a uma API existente, use o comando `add-permission`. Exemplo:
```
aws lambda add-permission \
--function-name my-function \
--statement-id apigateway-get --action lambda:InvokeFunction \
--principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:us-east-2:123456789012:mnh1xmpli7/default/GET/"
```
A seguinte saída deverá ser mostrada:
```
{
"Statement": "{\"Sid\":\"apigateway-test-2\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"apigateway.amazonaws.com\"},\"Action\":\"lambda:InvokeFunction\",\"Resource\":\"arn:aws:lambda:us-east-2:123456789012:function:my-function\",\"Condition\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:execute-api:us-east-2:123456789012:mnh1xmpli7/default/GET\"}}}"
}
```
**nota**
Se a sua função e a API estiverem em Regiões da AWS diferentes, o identificador de região no ARN de origem deverá corresponder à região da função, e não à região da API. Quando o API Gateway invoca uma função, ele usa um ARN de recurso baseado no ARN da API, mas modificado para corresponder à região da função.
O ARN de origem no exemplo concede permissão a uma integração no método GET do recurso raiz no estágio padrão de uma API com o ID `mnh1xmpli7`. É possível usar um asterisco no ARN de origem para conceder permissões a vários estágios, métodos ou recursos.
**Padrões de recursos**
+ `mnh1xmpli7/*/GET/*`: método GET em todos os recursos, em todos os estágios.
+ `mnh1xmpli7/prod/ANY/user`: método ANY no recurso `user` no estágio `prod`.
+ `mnh1xmpli7/*/*/*`: qualquer método em todos os recursos, em todos os estágios.
Para obter detalhes sobre como exibir a política e remover instruções, consulte [Visualizar políticas do IAM baseadas em recurso no Lambda](access-control-resource-based.md).
## Aplicação de exemplo
O aplicativo de exemplo de [API Gateway com Node.js](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/nodejs-apig) inclui uma função com um modelo do AWS SAM que cria uma API REST com o rastreamento do AWS X-Ray habilitado. Ele também inclui scripts para implantar, invocar a função, testar a API e fazer a limpeza.
## O manipulador de eventos do Powertools para AWS Lambda
O manipulador de eventos do kit de ferramentas Powertools para AWS Lambda fornece roteamento, middleware, configuração CORS, geração de especificações da OpenAPI, validação de solicitações, tratamento de erros e outros recursos úteis ao escrever funções do Lambda invocadas por um endpoint do API Gateway (HTTP ou REST). O utilitário de manipulador de eventos está disponível para Python e TypeScript/JavaScript. Para obter mais informações, consulte a [API REST do manipulador de eventos](https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/api_gateway/) na documentação do *Powertools para AWS Lambda (Python)* e a [API HTTP do manipulador de eventos na documentação do *Powertools para AWS Lambda (TypeScript)*. ](https://docs.aws.amazon.com/powertools/typescript/latest/features/event-handler/http/)
### Python
```
from aws_lambda_powertools import Logger
from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools.utilities.typing.lambda_context import LambdaContext
app = APIGatewayRestResolver()
logger = Logger()
@app.get("/healthz")
def ping():
return {"message": "health status ok"}
@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
def lambda_handler(event: dict, context: LambdaContext) -> dict:
return app.resolve(event, context)
```
### Typescript
```
import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
import { Logger } from '@aws-lambda-powertools/logger';
import {
correlationPaths,
search,
} from '@aws-lambda-powertools/logger/correlationId';
import type { Context } from 'aws-lambda/handler';
const logger = new Logger({
correlationIdSearchFn: search,
});
const app = new Router({ logger });
app.get("/healthz", async () => {
return { message: "health status ok" };
});
export const handler = async (event: unknown, context: Context) => {
// You can continue using other utilities just as before
logger.addContext(context);
logger.setCorrelationId(event, correlationPaths.API_GATEWAY_REST);
return app.resolve(event, context);
};
```