Como soluciono problemas de integração do API Gateway para funções do Lambda?

Resolução

Ative o registro em log de API

Conclua as etapas a seguir:

1. Abra o console do API Gateway.
2. No painel de navegação, clique em APIs e selecione sua API.
3. No painel de navegação, clique em Estágios e selecione seu estágio.
4. Em Logs e rastreamento, clique em Editar.
5. Em CloudWatch Logs, selecione um nível no menu suspenso.<br id=hardline_break/> Observação: para logs completos de solicitações e respostas, selecione a opção Rastreamento de dados com o nível de registro em log definido como Logs de erros e informações. É uma prática recomendada não ativar o Rastreamento de dados para APIs de produção, pois ele pode registrar dados sensíveis.
6. Selecione Métricas detalhadas.
7. Em Registro em log de acesso personalizado, conclua as seguintes etapas:<br id=hardline_break/> Clique em Ativar registro em log de acesso.<br id=hardline_break/> Em ARN de destino de log de acesso, insira o nome do recurso da Amazon (ARN) de um Amazon Data Firehose ou de um Grupo de logs do CloudWatch.<br id=hardline_break/> Observação: somente as APIs REST oferecem suporte ao ARN do Firehose.
8. Insira um formato de log.
9. Clique em Salvar.

Determine os tipos de integração, verifique os erros e dê os próximos passos para resolver

Conclua as etapas a seguir:

1. Verifique se uma integração de proxy do Lambda ou uma integração personalizada do Lambda está configurada no API Gateway. Para verificar o tipo de integração, verifique o valor da integração de proxy do Lambda em Solicitação de integração.

2. Verifique se os erros no API Gateway correspondem aos erros no Lambda. Execute a seguinte consulta do CloudWatch Logs Insights para encontrar um código de status de erro durante um período especificado:

   parse @message '(*) *' as reqId, message
       | filter message like /Method completed with status: \d\d\d/
       | parse message 'Method completed with status: *' as status
       | filter status != 200
       | sort @timestamp asc
       | limit 50

3. Execute a seguinte consulta do CloudWatch Logs Insights para pesquisar logs de erro do Lambda durante o mesmo período:

   fields @timestamp, @message
       | filter @message like /(?i)(Exception|error|fail)/
       | sort @timestamp desc
       | limit 20

4. Com base no tipo de erro que você identificar em seus logs, selecione uma das seguintes opções:<br id=hardline_break/> Se você receber o erro a seguir, conclua as etapas na seção Resolver problemas de simultaneidade.

   (#####) Lambda invocation failed with status: 429. Lambda request id: ##########
   () Execution failed due to configuration error: Rate Exceeded.
   (#####) Method completed with status: 500

   Se você receber um dos seguintes erros, conclua as etapas na seção Resolver problemas de tempo limite.<br id=hardline_break/> Para uma integração personalizada do Lambda:

   < Integration timeout:
   (#####) Method response body after transformations: {"errorMessage":"2019-08-14T02:45:14.133Z ########-####-####-####-############ Task timed out after ##.01 seconds"}
   > Integration timeout:
   (#####) Execution failed due to a timeout error

   Para uma integração de proxy do Lambda:

   < Integration timeout:
   (#####) Endpoint response body before transformations: {"errorMessage":"2019-08-14T02:50:25.865Z ########-####-####-####-############ Task timed out after ##.01 seconds"}
   > Integration timeout:
   (#####) Execution failed due to a timeout error

   Se você receber o erro a seguir, conclua as etapas na seção Resolver erros de função.

   (#####) Execution failed due to configuration error: Malformed Lambda proxy response
   (#####) Method response body after transformations: {"errorMessage": "Syntax error in module 'lambda_function'"}

Resolva problemas de simultaneidade

Você recebe erros de controle de utilização 429 ou erros 500 quando solicitações adicionais chegam do API Gateway mais rápido do que sua função do Lambda consegue escalar.

Para resolver esses erros, analise as seguintes CloudWatch Metrics: Count (API Gateway), Throttles (Lambda) e ConcurrentExecutions (Lambda). Considere o seguinte:

• Count (API Gateway) é o número total de solicitações de API durante um período de tempo especificado.
• Throttles (Lambda) é o número de solicitações de invocação limitadas. Quando todas as instâncias da função processam solicitações e nenhuma simultaneidade está disponível para aumentar a escala verticalmente, o Lambda rejeita solicitações adicionais com o erro TooManyRequestsException. Solicitações limitadas e outros erros de invocação não contam como invocações ou erros.
• ConcurrentExecutions (Lambda) é o número de instâncias da função que processam eventos. Se esse número atingir sua cota de execuções simultâneas para a região da AWS, as solicitações de invocação adicionais serão limitadas. O Lambda também limita solicitações de invocação quando o número de instâncias da função atinge o limite de simultaneidade reservado que você configurou para a função.

Observação: para obter mais informações, consulte Métricas do API Gateway e Uso de métricas do CloudWatch com o Lambda.

Se você definir uma simultaneidade de reserva para sua função do Lambda, aumente o valor da simultaneidade de reserva. Ou remova o valor da simultaneidade de reserva da função do Lambda. Em seguida, a função acessa o grupo de execuções simultâneas sem reservas.

Se você não definir a simultaneidade de reserva na função do Lambda, verifique a métrica ConcurrentExecutions para descobrir o uso. Para obter mais informações, consulte Cotas Lambda.

Resolva problemas de tempo limite

O limite de tempo limite de integração padrão é de 29 segundos para todas as integrações do API Gateway. É possível enviar uma solicitação de cota para aumentar a cota de limite de tempo limite de integração padrão para mais de 29 segundos para APIs regionais e APIs privadas. No entanto, esse aumento pode exigir uma redução na sua cota de controle de utilização a nível regional na sua conta da AWS.

Observação: se você aumentar o limite de tempo limite de integração, certifique-se de alterar o valor de tempo limite padrão de 29 segundos para o novo valor. Por exemplo, altere o valor do tempo limite padrão de 29 segundos nas integrações em que você deseja aplicar o aumento. Em seguida, reimplante a API para que o novo limite de tempo limite de integração entre em vigor.

Ao criar uma API do API Gateway com integração com o Lambda, é possível encontrar um dos seguintes cenários:

• O valor do tempo limite é menor do que o valor do tempo limite de integração.
• O valor do tempo limite é maior do que o valor do tempo limite de integração.

Se seu tempo limite da função do Lambda for menor que 29 segundos, verifique seus logs do Lambda para investigar esse problema. Se sua função do Lambda precisar ser executada após 29 segundos, invoque a função do Lambda de forma assíncrona.

Para integração personalizada de invocação assíncrona do Lambda, conclua as seguintes etapas:

1. Abra o console do API Gateway.
2. No painel de navegação, clique em APIs e, em seguida, selecione sua API.
3. Clique em Recursos e, em seguida, selecione seu método.
4. Clique em Solicitação de integração.
5. Selecione Solicitação de método.
6. Expanda Cabeçalhos de solicitação HTTP.
7. Selecione Adicionar cabeçalho.
8. Em Nome, insira um nome para o seu cabeçalho. Por exemplo: X-Amz-Invocation-Type<br id=hardline_break/> Importante: você deve mapear seu cabeçalho a partir de 'Evento'. Você deve usar aspas simples.

Para a integração de proxy do Lambda, use duas funções do Lambda: função A e função B. O API Gateway primeiro invoca a função A de maneira síncrona. Em seguida, a função A invoca de forma assíncrona a função B. A função A pode retornar uma resposta bem-sucedida ao API Gateway quando a função B é invocada de forma assíncrona.

Se você usar uma integração de proxy do Lambda, é possível alterar a integração para uma integração personalizada. No entanto, para transformar a solicitação ou resposta em seu formato específico, você deve configurar os modelos de mapeamento. Para obter mais informações, consulte Configurar a invocação assíncrona da função do Lambda do backend.

Observação: como uma função do Lambda assíncrona é executada em segundo plano, seu cliente não pode receber dados diretamente de uma função do Lambda. Você deve ter um banco de dados intermediário para armazenar todos os dados persistentes.

Resolva erros de função

Se você receber um erro de função ao invocar sua API, verifique se há algum erro de sintaxe na sua função do Lambda. Esse erro também aparece se sua função do Lambda não tiver retornado um objeto JSON válido que o API Gateway espera para integrações de proxy.

Nos logs de execução do API Gateway, é possível analisar o valor do AWS Integration Endpoint RequestID nos logs:

(#####) AWS Integration Endpoint RequestId : YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY

Em seguida, é possível executar a seguinte consulta do CloudWatch Logs Insights para pesquisar logs do Lambda durante o mesmo período específico:

fields @timestamp, @message, @requestId, @logStream
| filter @requestId = 'YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY'
| sort @timestamp asc

Para resolver esse erro, conclua as etapas na seção Ative o registro em log para sua API e estágio.

Substitua respostas incorretas do código de status da API REST

Se o API Gateway retornar um código de status incorreto, crie um modelo de mapeamento para substituir o código de status incorreto pelo código de status correto. É possível substituir as respostas do código de status em integrações não proxy com APIs REST.

Observação: essa configuração do modelo de mapeamento se aplica somente às APIs REST. Para APIs HTTP, consulte How do I map the response status codes for API Gateway integrations in HTTP APIs? (Como mapear os códigos de status de resposta para integrações do API Gateway em APIs HTTP?)

Por exemplo, se o API Gateway retornar um código de status 200 em vez de 4## ou 5## de uma função do Lambda, conclua as seguintes etapas:

1. Abra o console do API Gateway e, no painel de navegação, clique em APIs.

2. Selecione sua API REST e, em seguida, clique na guia Resposta de integração.

3. Em Configurações de respostas de integração, clique em Editar.

4. Expanda Modelos de mapeamento e selecione Adicionar modelo de mapeamento.

5. Em Tipo de conteúdo, insira application/json.

6. No editor do modelo de mapeamento, insira o seguinte código:

   #set($inputRoot = $input.path('$'))
   $input.json("$")
   #if($inputRoot.toString().contains("error"))
   #set($context.responseOverride.status = 400)
   #end

7. Clique em Salvar.

O parâmetro $context.responseOverride.status substitui o código de status para 400 em vez do mapeamento padrão no painel de resposta da integração.

Para obter mais informações, consulte Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway.

Configure as integrações da sua API REST para retornar os cabeçalhos CORS necessários

Para retornar os cabeçalhos CORS necessários em sua resposta, configure sua função do Lambda de backend ou servidor proxy HTTP. Você deve incluir domínios permitidos no valor do cabeçalho Access-Control-Allow-Origin como uma lista.

Em integrações de proxy, não é possível configurar uma resposta de integração no API Gateway para modificar os parâmetros de resposta retornados pelo backend da sua API. Em uma integração de proxy, o API Gateway encaminha a resposta do backend diretamente ao cliente. Você deve configurar sua função do Lambda ou integração HTTP para retornar os cabeçalhos CORS necessários.

Em integrações não proxy, você deve configurar manualmente uma resposta de integração no API Gateway para retornar os cabeçalhos CORS necessários. Use o console do API Gateway para configurar o CORS. O console adiciona automaticamente os cabeçalhos CORS necessários ao recurso configurado.

Para obter mais informações, consulte Como solucionar erros de CORS da minha API do API Gateway?

Integrações de proxy do Lambda de carga útil binária

Uma carga útil binária é qualquer coisa que não seja uma carga útil de texto. Por exemplo, uma carga útil binária pode ser um arquivo .jpeg, um arquivo .gzip, etc. Isso inclui dados binários genéricos, como de uma aplicação em .pdf, imagem em .jpeg ou aplicação em .zip.

Para lidar com cargas úteis binárias em integrações de proxy do Lambda, você deve codificar em base64 a resposta da sua função e configurar os binaryMediaTypes para sua API. Para lidar com cargas úteis binárias em integrações não proxy, você deve adicionar os tipos de mídia à lista binaryMediaTypes do recurso RestApi.

Para obter mais informações, consulte Tipos de mídia binários para APIs REST no API Gateway.

Informações relacionadas

Manipule erros padrão do Lambda no API Gateway

Manipule erros personalizados do Lambda no API Gateway