Como faço para mapear os códigos de status de resposta para as integrações do API Gateway em APIs REST?

Resolução

Quando você quiser substituir seus códigos de status de resposta de back-end, use os modelos de mapeamento do API Gateway ou as expressões regulares para mapear os códigos de status. Você pode fazer isso em integrações proxy e não proxy com a API REST.

Integrações proxy e não proxy são usadas para mapear os códigos de status de resposta na API REST. Quando há uma resposta proxy, o API Gateway recebe os códigos de status à medida que são enviados pelo backend. Em uma integração proxy do Lambda, o API Gateway exige que a função de backend do Lambda retorne a seguinte saída no formato JSON:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode, 
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": “…”65411
}

Em uma integração proxy com uma função do Lambda, um código de status é passado diretamente para o API Gateway de uma função de backend do Lambda. Um código de status não pode ser passado diretamente da função do Lambda em uma integração não proxy.

Quando o API Gateway invoca com êxito uma função do Lambda, o código de status de resposta padrão é 200. Os códigos de status também são retornados quando o Lambda apresenta erros. Você pode personalizar os códigos de resposta do API Gateway. Use uma integração não proxy e um modelo de mapeamento quando precisar criar um código de resposta personalizado.

Configurar um método de resposta com código personalizado

Siga estas etapas para configurar um método e responder com código de resposta personalizado do API Gateway:

1.    No console do API Gateway, crie uma API REST pública.

2.    Crie um recurso e um método para o recurso.

3.    Configure uma resposta de método que inclua o código de status que você deseja que o API Gateway retorne.

4.    Configure uma resposta de integração do Lambda.

• Para o Lambda Error Regex, informe o padrão de expressão regular para a mensagem de erro retornada pela função do Lambda.
  Observação: você também pode encontrar a regex de erro HTTP para as respostas HTTP.
• Para o status de resposta do método, informe o código de status que deve ser retornado pelo API Gateway.
• Escolha uma opção de gerenciamento de conteúdo para definir como o corpo da resposta é tratado antes que a resposta seja enviada ao cliente.
• Defina o padrão do código de status para 200.

5.    Depois de terminar de configurar a resposta de integração, salve, teste e implante suas alterações.

Mapear códigos de status para valores estáticos

Para que o API Gateway capture um grupo de códigos de status retornados do seu backend, mapeie os códigos de status para valores estáticos:

1.    Acesse o recurso que tiver o código de status que você deseja alterar.

2.    Configure uma resposta de método para retornar 400 como o código de resposta do API Gateway.

3.    Volte para as configurações de recursos e configure uma resposta de integração.

4.    Os valores em HTTP status regex capturam o status retornado pelo seu backend. O status é então mapeado para o código de resposta definido na Etapa 2.

Quando o regex de status do HTTP tiver um valor padrão de “-” e estiver mapeado para 200 como o status de resposta do método, todos os códigos de status serão capturados e retornados pelo seu mapa de backend para 200. Você pode alterar os valores do regex do status HTTP para 2\ d\ {2} a fim de capturar todas as respostas 2xx e mapeá-las para 200.

5.    Escolha Add integration response (Adicionar resposta de integração) para capturar os outros códigos de status.

Para 4xx, em HTTP status regex, adicione 4\ d\ {2}. Em Method response status (Status de resposta do método), escolha 400. Isso foi definido na Etapa 2.

6.    Implante a API. Quando a API retorna qualquer código de status 2xx, eles são mapeados para o código de status 200. Se a API retornar códigos de status 4xx, eles serão mapeados para o código de status 400.

As expressões regulares podem ser formatadas de várias maneiras. Por exemplo:

• .*([01][0-9][0-9]|2[0-4][0-9]|25[0-5]).* corresponde aos códigos de status entre 100 e 199, 200 e 249 ou 250 e 255.
• .*5\ d\ d.* corresponde a um código de status, como 5xx.

O código de exemplo a seguir é para testar uma função do Lambda:

def lambda_handler(event, context):
    if "error" not in event or event['error'] == "":
        return("Pass")
    elif event['error'] == 'sample 400':
        raise Exception({"errorMessage": "Error: Raising 400 from within the Lambda function","errorType": "Exception"})
    elif event['error'] == 'sample 500':
        raise Exception({"errorMessage": "Error: Raising 500 from within the Lambda function","errorType": "Exception"})
    else:
        return("Error Value in the json request should either be 400 or 500 to demonstrate")

No exemplo, o código verifica se o valor do erro enviado pelo API Gateway é um erro 400 ou 500. Quando for um erro 400 ou 500, o código Lambda gerará uma exceção com uma mensagem de erro. Quando o API Gateway recebe a resposta, o serviço verifica se a mensagem de erro corresponde a algum padrão configurado na resposta de integração. O API Gateway responderá adequadamente se o padrão de regex do Lambda for compatível.

7.    Depois de uma configuração bem-sucedida, os códigos de status podem ser testados usando o console do API Gateway.

Mapear códigos de status com modelos de mapeamento

O exemplo anterior usa expressões regulares, mas também pode usar modelos de mapeamento. O exemplo a seguir substitui o código de status 200 do backend para aplicar o código de status 400:

1.    Crie uma função do Lambda com o seguinte código de exemplo:

----------------------
def lambda_handler(event, context):
    # TODO implement print(event)
    return { 'statusCode': 200, 'body': "customerror" }
-----------------------

2.    Crie uma API com integração não proxy do Lambda usando a função do Lambda anterior para o backend.

3.    Siga as etapas 6 a 10 descritas no tutorial Substituir o código de status de resposta de uma API pelo console do API Gateway.

Neste exemplo, use o seguinte modelo de mapeamento:

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

4.    Salve, teste e implante a API.

---

Informações relacionadas

Trabalhar com modelos e modelos de mapeamento

Transformar solicitações e respostas da API

Guia do desenvolvedor do Amazon API Gateway