As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Usar o AWS Lambda com o Amazon API Gateway
Você pode 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. Você pode 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.
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. Você pode 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 captura todos os caminhos abaixo de um recurso. O método ANY captura todos os métodos HTTP.
Esta seção explica informações gerais sobre como escolher um tipo de API e adicionar um endpoint à sua função do Lambda, além de fornecer informações sobre eventos, permissões, respostas e tratamento de erros.
Seções
Adicionar um endpoint público à sua função do Lambda
Como adicionar um endpoint público à sua função do Lambda
Abra a página Funções
do console do Lambda. -
Escolha uma função.
-
Em Visão geral da função, escolha Adicionar gatilho.
-
Selecione API Gateway.
-
Escolher Create an API (Criar uma API) ou Use an existing API (Usar uma API existente).
-
New API (Nova API): para API type (Tipo de API), escolha HTTP API. Para saber mais, consulte Tipos de APIs.
-
Existing API (API existente): selecione a API no menu suspenso ou insira seu ID (como r3pmxmplak).
-
-
Em Security (Segurança), escolha Open (Abrir).
-
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 deprod. -
/prod/user: o estágio deprode o recurso deuser. -
/dev/{proxy+}: qualquer rota no estágio dedev. -
/: (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. Você pode 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.
Formato de eventos
O Amazon API Gateway invoca sua função de modo síncrono 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. O exemplo abaixo mostra um evento de proxy de uma API REST do API Gateway.
exemplo Evento de proxy event.json
{ "resource": "/", "path": "/", "httpMethod": "GET", "requestContext": { "resourcePath": "/", "httpMethod": "GET", "path": "/Prod/", ... }, "headers": { "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "accept-encoding": "gzip, deflate, br", "Host": "70ixmpl4fl.execute-api.us-east-2.amazonaws.com", "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.132 Safari/537.36", "X-Amzn-Trace-Id": "Root=1-5e66d96f-7491f09xmpl79d18acf3d050", ... }, "multiValueHeaders": { "accept": [ "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9" ], "accept-encoding": [ "gzip, deflate, br" ], ... }, "queryStringParameters": null, "multiValueQueryStringParameters": null, "pathParameters": null, "stageVariables": null, "body": null, "isBase64Encoded": false }
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.
exemplo index.mjs
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 tempo de execução 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.
exemplo 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 da função. Você pode 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.
exemplo 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/" } } } ] }
Você pode gerenciar manualmente as permissões da política de função com as seguintes operações da API:
Para conceder permissão de invocação a uma API existente, use o comando add-permission.
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 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, ela 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. Você pode 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 recursouserno estágioprod. -
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 Limpar políticas baseadas em recursos.
Tratamento de erros com uma API do API Gateway
O API Gateway trata todos os erros de invocação e função como erros internos. Se a API do Lambda rejeitar a solicitação de invocação, o API Gateway retornará um código de erro 500. Se a função é executada, mas retorna um erro ou retorna uma resposta no formato errado, o API Gateway retorna um código de erro 502. Em ambos os casos, o corpo da resposta do API Gateway é {"message":
"Internal server error"}.
nota
O API Gateway não tenta novamente nenhuma invocação do Lambda. Se o Lambda retornar um erro, o API Gateway retornará uma resposta de erro ao cliente.
O exemplo a seguir mostra um mapa de rastreamento do X-Ray para uma solicitação que resultou em um erro de função e um erro 502 do API Gateway. O cliente recebe a mensagem de erro genérica.
Para personalizar a resposta de erro, é necessário detectar erros no código e formatar uma resposta no formato necessário.
exemplo index.mjs
var formatError = function(error){ var response = { "statusCode": error.statusCode, "headers": { "Content-Type": "text/plain", "x-amzn-ErrorType": error.code }, "isBase64Encoded": false, "body": error.code + ": " + error.message } return response }
O API Gateway converte essa resposta em um erro HTTP com um código de status e um corpo personalizado. No mapa de rastreamento, o nó da função é verde porque ele tratou o erro.
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: uma API RESTful leve e de baixa latência.
-
API REST: uma API RESTful personalizável e com muitos recursos.
-
WebSocket API — Uma API da web que mantém conexões persistentes com clientes para comunicação full-duplex.
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 no Guia do desenvolvedor do API Gateway.
WebSocket As APIs também usam a API API Gateway versão 2 e oferecem suporte a um conjunto de recursos semelhante. Use uma WebSocket API para aplicativos que se beneficiam de uma conexão persistente entre o cliente e a API. WebSocket As APIs fornecem comunicação full-duplex, 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). O exemplo abaixo mostra um evento de uma API HTTP.
exemplo event-v2.json
{ "version": "2.0", "routeKey": "ANY /nodejs-apig-function-1G3XMPLZXVXYI", "rawPath": "/default/nodejs-apig-function-1G3XMPLZXVXYI", "rawQueryString": "", "cookies": [ "s_fid=7AABXMPL1AFD9BBF-0643XMPL09956DE2", "regStatus=pre-register" ], "headers": { "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "accept-encoding": "gzip, deflate, br", ... }, "requestContext": { "accountId": "123456789012", "apiId": "r3pmxmplak", "domainName": "r3pmxmplak.execute-api.us-east-2.amazonaws.com", "domainPrefix": "r3pmxmplak", "http": { "method": "GET", "path": "/default/nodejs-apig-function-1G3XMPLZXVXYI", "protocol": "HTTP/1.1", "sourceIp": "205.255.255.176", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.132 Safari/537.36" }, "requestId": "JKJaXmPLvHcESHA=", "routeKey": "ANY /nodejs-apig-function-1G3XMPLZXVXYI", "stage": "default", "time": "10/Mar/2020:05:16:23 +0000", "timeEpoch": 1583817383220 }, "isBase64Encoded": true }
Para obter mais informações, consulte Integrações do AWS Lambda no Guia do desenvolvedor do API Gateway.
Aplicações de exemplo
O GitHub repositório deste guia fornece o seguinte exemplo de aplicativo para o API Gateway.
-
API Gateway com Node.js
: uma função com um modelo do AWS SAM que cria uma API REST com o rastreamento do AWS X-Ray habilitado. Ele inclui scripts para implantar, invocar a função, testar a API e limpar.
O Lambda também fornece esquemas e modelos que você pode usar para criar uma aplicação do API Gateway no console do Lambda.
