Uso do AWS Lambda com o Amazon API Gateway - AWS Lambda

Uso do AWS Lambda com o Amazon API Gateway

Você pode criar uma API da web com um endpoint de 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 de 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.

Como adicionar um endpoint público à sua função do Lambda

  1. Abra a página Funções do console do Lambda.

  2. Escolha uma função.

  3. Em Designer, escolha Add trigger (Adicionar trigger).

  4. Escolha API Gateway.

  5. Em API, escolha Create an API (Criar uma API).

  6. Em Security (Segurança), escolha Open (Abrir).

  7. Escolha Add (Adicionar).

Com o trigger API Gateway selecionado no designer, escolha o endpoint para invocar a função com o API Gateway.


      Um endpoint de API do API Gateway anexado a uma função do Lambda.

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 user.

  • /dev/{proxy+} – qualquer rota no estágio de dev.

  • / – (APIs de 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.

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 event.json API Gateway evento de proxy (API REST)

{ "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 }

O exemplo mostra um evento de uma solicitação GET para o caminho raiz do estágio Prod de uma API REST. A forma e o conteúdo do evento variam de acordo com o tipo de API e a configuração.

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.js – 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 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 }

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.

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. O exemplo abaixo mostra uma política de função com uma instrução que foi adicionada por um modelo do AWS SAM.

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:123456789012:function:nodejs-apig-function-1G3MXMPLXVXYI", "Condition": { "ArnLike": { "AWS:SourceArn": "arn:aws:execute-api:us-east-2:123456789012:ktyvxmpls1/*/GET/" } } } ] }

Confirme a política de função na guia Permissions (Permissões) do console do Lambda.

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/" { "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 recurso user no estágio de 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 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 retornará um erro 502. Em ambos os casos, o corpo da resposta do API Gateway é {"message": "Internal server error"}.

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.


        Mapa de rastreamento para um erro de função com o API Gateway.

Para personalizar a resposta de erro, é necessário detectar erros no código e formatar uma resposta no formato necessário.

exemplo index.js – erro de formatação

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.


        Mapa de rastreamento para um erro formatado com o API Gateway.

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.

  • API WebSocket – 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 APIs REST 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). O exemplo abaixo mostra um evento de uma API HTTP.

exemplo event-v2.json – evento de proxy do API Gateway (API HTTP)

{ "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.

Aplicativos de exemplo

O repositório do GitHub desse guia fornece o seguinte aplicativo de exemplo para o gateway da API.

  • Gateway da API 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 um aplicativo de gateway da API no console do Lambda.