# Integrações do Lambda para APIs REST no API Gateway
Você pode integrar um método de API a uma função do Lambda usando integração de proxy do Lambda ou integração sem proxy do Lambda (personalizada).
Na integração de proxy do Lambda, a configuração necessária é simples. Defina o método HTTP da integração como POST, o URI de endpoint de integração como o ARN da ação de invocação da função do Lambda de uma função específica do Lambda e conceda ao API Gateway permissão para chamar a função do Lambda em seu nome.
Na integração não proxy do Lambda, além das etapas de configuração da integração de proxy, você também especifica como os dados da solicitação de entrada serão mapeados para a solicitação de integração e como os dados da resposta de integração resultante serão mapeados para a resposta de método.
**Topics**
+ [Integrações de proxy do Lambda no API Gateway](set-up-lambda-proxy-integrations.md)
+ [Configurar integrações personalizadas do Lambda no API Gateway](set-up-lambda-custom-integrations.md)
+ [Configurar a invocação assíncrona da função do Lambda do backend](set-up-lambda-integration-async.md)
+ [Manipular erros do Lambda no API Gateway](handle-errors-in-lambda-integration.md)
# Integrações de proxy do Lambda no API Gateway
A seção a seguir mostra como usar uma integração de proxy do Lambda.
**Topics**
+ [Compreender a integração de proxy do Lambda do API Gateway](#api-gateway-create-api-as-simple-proxy)
+ [Suporte para cabeçalhos de vários valores e parâmetros de string de consulta](#apigateway-multivalue-headers-and-parameters)
+ [Formato de entrada de uma função do Lambda para integração de proxy](#api-gateway-simple-proxy-for-lambda-input-format)
+ [Formato de saída de uma função do Lambda para integração de proxy](#api-gateway-simple-proxy-for-lambda-output-format)
+ [Configurar a integração de proxy do Lambda para o API Gateway usando a AWS CLI](set-up-lambda-proxy-integration-using-cli.md)
+ [Configurar um recurso de proxy com a integração de proxy do Lambda com uma definição OpenAPI](api-gateway-set-up-lambda-proxy-integration-on-proxy-resource.md)
## Compreender a integração de proxy do Lambda do API Gateway
A integração de proxy do Lambda do Amazon API Gateway é um mecanismo simples, potente e ágil para criar uma API com uma configuração de um único método de API. A integração de proxy do Lambda permite que o cliente chame uma única função do Lambda no backend. A função acessa muitos recursos ou recursos de outros serviços da AWS, incluindo chamadas para outras funções do Lambda.
Na integração de proxy do Lambda, quando um cliente envia uma solicitação de API, o API Gateway repassa um [objeto do evento](#api-gateway-simple-proxy-for-lambda-input-format) para a função do Lambda integrada, exceto pelo fato de que a ordem dos parâmetros da solicitação não é preservada. Esses [dados de solicitação](#api-gateway-simple-proxy-for-lambda-input-format) incluem cabeçalhos de solicitação, parâmetros de strings de consulta, variáveis de caminho URL, carga e dados de configuração da API. Os dados de configuração podem incluir o nome do estágio de implantação atual, variáveis de estágio, identidade do usuário ou contexto de autorização (se houver). A função do Lambda do backend analisa os dados da solicitação recebida para determinar a resposta que ela retorna. Para que o API Gateway passe a saída do Lambda como a resposta da API para o cliente, a função do Lambda deve retornar o resultado [neste formato](#api-gateway-simple-proxy-for-lambda-output-format).
Como o API Gateway não interfere muito entre o cliente e a função do Lambda do backend para a integração de proxy do Lambda, o cliente e a função do Lambda integrada podem se adaptar às alterações mútuas sem quebrar a configuração de integração existente da API. Para permitir isso, o cliente deve seguir os protocolos de aplicação promulgados pela função do Lambda de backend.
É possível configurar uma integração de proxy do Lambda para qualquer método de API. Mas uma integração de proxy do Lambda é mais potente quando configurada para um método de API que envolve um recurso de proxy genérico. O recurso de proxy genérico pode ser identificado por um modelo variável de caminho especial de `{proxy+}`, pelo espaço reservado de método `ANY` ou ambos. O cliente pode passar a entrada da função do Lambda de backend na solicitação recebida como parâmetros da solicitação ou carga aplicável. Os parâmetros de solicitação incluem cabeçalhos, variáveis de caminho URL, parâmetros de string de consulta e a carga aplicável. A função do Lambda integrada verifica todas as fontes de entrada antes de processar a solicitação e responder ao cliente com mensagens de erro significativas se qualquer uma das entradas obrigatórias estiver ausente.
Ao chamar um método de API integrado ao método HTTP genérico de `ANY` e o recurso genérico de `{proxy+}`, o cliente envia uma solicitação com um método HTTP específico em vez de `ANY`. O cliente também especifica determinado caminho URL em vez de `{proxy+}`, e inclui todos os cabeçalhos necessários, parâmetros de strings de consulta ou uma carga aplicável.
A lista a seguir resume comportamentos de tempo de execução de diferentes métodos de API com a integração de proxy do Lambda:
+ `ANY /{proxy+}`: o cliente deve escolher determinado método HTTP, definir determinada hierarquia de caminho de recursos e pode definir todos os cabeçalhos, parâmetros de strings de consulta e carga aplicáveis para passar os dados como entrada para a função do Lambda integrada.
+ `ANY /res`: o cliente deve escolher determinado método HTTP e pode definir todos os cabeçalhos, parâmetros de strings de consulta e carga aplicáveis para passar os dados como entrada para a função do Lambda integrada.
+ `GET|POST|PUT|... /{proxy+}`: o cliente pode definir determinada hierarquia de caminho de recursos, cabeçalhos, parâmetros de strings de consulta e carga aplicáveis para passar os dados como entrada para a função do Lambda integrada.
+ `GET|POST|PUT|... /res/{path}/...`: o cliente deve escolher determinado segmento de caminho (para a variável `{path}`) e pode definir os cabeçalhos de solicitação, parâmetros de strings de consulta e carga aplicáveis para passar os dados de entrada para a função do Lambda integrada.
+ `GET|POST|PUT|... /res`: o cliente pode escolher os cabeçalhos de solicitação, parâmetros de strings de consulta e carga aplicáveis para passar dados de entrada para a função do Lambda integrada.
Tanto o recurso de proxy de `{proxy+}` quanto o recurso personalizado de `{custom}` são expressos como modelos de variáveis de caminho. No entanto, `{proxy+}` pode indicar qualquer recurso ao longo de uma hierarquia de caminho, enquanto `{custom}` refere-se apenas a determinado segmento de caminho. Por exemplo, um supermercado pode organizar seu inventário de produtos online por nomes de departamento, categorias de produtos e tipos de produtos. O site do supermercado pode representar os produtos disponíveis pelos seguintes modelos de variáveis de caminho de recursos personalizados: `/{department}/{produce-category}/{product-type}`. Por exemplo, maçãs são representadas por `/produce/fruit/apple` e cenouras por `/produce/vegetables/carrot`. Ele também pode usar `/{proxy+}` para representar qualquer departamento, categoria ou tipo de produto que o cliente pode procurar ao fazer compras na loja online. Por exemplo, `/{proxy+}` pode indicar qualquer um dos seguintes itens:
+ `/produce`
+ `/produce/fruit`
+ `/produce/vegetables/carrot`
Para permitir que os clientes procurem qualquer produto disponível, a categoria do produto e o departamento associado, você pode expor um único método de `GET /{proxy+}` com permissões somente leitura. Da mesma forma, para permitir que um supervisor atualize o inventário do departamento do `produce`, você pode configurar outro método único de `PUT /produce/{proxy+}` com as permissões de leitura/gravação. Para permitir que um caixa atualize o total de um vegetal, você pode configurar um método `POST /produce/vegetables/{proxy+}` com permissões de leitura/gravação. Para permitir que um gerente de loja realize qualquer ação possível em qualquer produto disponível, o desenvolvedor da loja online pode expor o método `ANY /{proxy+}` com permissões de leitura/gravação. Em qualquer caso, na ocasião da execução, o cliente ou o funcionário deve selecionar um produto específico de determinado tipo em um departamento escolhido, uma categoria de produto específica em um departamento escolhido ou um departamento específico.
Para obter mais informações sobre como configurar integrações de proxy do API Gateway, consulte [Configurar a integração de proxy com um recurso de proxy](api-gateway-set-up-simple-proxy.md).
A integração de proxy exige que o cliente tenha um conhecimento mais detalhado dos requisitos de backend. Portanto, para garantir uma melhor performance das aplicações e da experiência do usuário, o desenvolvedor de backend deve comunicar claramente ao desenvolvedor cliente os requisitos do backend e fornecer um mecanismo de feedback de erro robusto quando os requisitos não são atendidos.
## Suporte para cabeçalhos de vários valores e parâmetros de string de consulta
Agora o API Gateway oferece suporte a vários cabeçalhos e parâmetros de string de consulta que possuem o mesmo nome. Cabeçalhos de vários valores, bem como cabeçalhos e parâmetros de valor único, podem ser combinados nas mesmas solicitações e respostas. Para obter mais informações, consulte [Formato de entrada de uma função do Lambda para integração de proxy](#api-gateway-simple-proxy-for-lambda-input-format) e [Formato de saída de uma função do Lambda para integração de proxy](#api-gateway-simple-proxy-for-lambda-output-format).
## Formato de entrada de uma função do Lambda para integração de proxy
Com a integração de proxy do Lambda, o API Gateway mapeia toda a solicitação do cliente para o parâmetro `event` de entrada da função do Lambda de back-end. O exemplo a seguir mostra a estrutura de um evento que o API Gateway envia para uma integração de proxy do Lambda.
Neste exemplo, supomos que a invocação ao API Gateway tenha sido a seguinte:
```
curl 'https://a1b2c3.execute-api.us-east-1.amazonaws.com/my/path?parameter1=value1¶meter2=value1¶meter2=value2¶meter3=value1,value2' -H 'header1: value1' -H 'header2: value1' -H 'header2: value2' -H 'header3: value1,value2'
```
A saída será exibida como a seguir:
```
{
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"header1": "value1",
"header2": "value2",
"header3": "value1,value2"
},
"multiValueHeaders": {
"header1": ["value1"],
"header2": ["value1","value2"],
"header3": ["value1,value2"]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value2",
"parameter3": "value1,value2"
},
"multiValueQueryStringParameters": {
"parameter1": ["value1"],
"parameter2": ["value1","value2"],
"parameter3": ["value1,value2"]
},
"requestContext": {
"accountId": "123456789012",
"apiId": "id",
"authorizer": {
"claims": null,
"scopes": null
},
"domainName": "id.execute-api.us-east-1.amazonaws.com",
"domainPrefix": "id",
"extendedRequestId": "request-id",
"httpMethod": "GET",
"identity": {
"accessKey": null,
"accountId": null,
"caller": null,
"cognitoAuthenticationProvider": null,
"cognitoAuthenticationType": null,
"cognitoIdentityId": null,
"cognitoIdentityPoolId": null,
"principalOrgId": null,
"sourceIp": "IP",
"user": null,
"userAgent": "user-agent",
"userArn": null,
"clientCert": {
"clientCertPem": "CERT_CONTENT",
"subjectDN": "www.example.com",
"issuerDN": "Example issuer",
"serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
"validity": {
"notBefore": "May 28 12:30:02 2019 GMT",
"notAfter": "Aug 5 09:36:04 2021 GMT"
}
}
},
"path": "/my/path",
"protocol": "HTTP/1.1",
"requestId": "id=",
"requestTime": "04/Mar/2020:19:15:17 +0000",
"requestTimeEpoch": 1583349317135,
"resourceId": null,
"resourcePath": "/my/path",
"stage": "$default"
},
"pathParameters": null,
"stageVariables": null,
"body": "Hello from Lambda!",
"isBase64Encoded": false
}
```
**nota**
Na entrada:
A chave `headers` só pode conter cabeçalhos de valor único.
A chave `multiValueHeaders` pode conter cabeçalhos de vários valores e cabeçalhos de valor único.
Se você especificar valores para `headers` e `multiValueHeaders`, o API Gateway os mesclará em uma única lista. Se o mesmo de chave/valor for especificado em ambos, somente os valores de `multiValueHeaders` aparecerão na lista mesclada.
Na entrada para a função do Lambda do backend, o objeto `requestContext` é um mapa de pares de chave/valor. Em cada par, a chave é o nome de uma propriedade de variável [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference), e o valor é o valor dessa propriedade. O API Gateway pode adicionar novas chaves ao mapa.
Dependendo dos recursos que estão habilitados, o mapa `requestContext` pode variar de acordo com a API. Por exemplo, no exemplo anterior, nenhum tipo de autorização é especificado. Portanto, nenhuma propriedade `$context.authorizer.*` ou `$context.identity.*` está presente. Quando um tipo de autorização é especificado, isso faz com que o API Gateway repasse informações do usuário autorizado para o endpoint de integração em um objeto `requestContext.identity` da seguinte forma:
+ Quando o tipo de autorização é `AWS_IAM`, as informações do usuário autorizado incluem propriedades `$context.identity.*`.
+ Quando o tipo de autorização é `COGNITO_USER_POOLS` (autorizador do Amazon Cognito), as informações do usuário autorizado incluem propriedades `$context.identity.cognito*` e `$context.authorizer.claims.*`.
+ Quando o tipo de autorização é `CUSTOM` (autorizador do Lambda), as informações do usuário autorizado incluem propriedades `$context.authorizer.principalId` e outras `$context.authorizer.*` aplicáveis.
## Formato de saída de uma função do Lambda para integração de proxy
Na integração de proxy do Lambda, o API Gateway requer a função do Lambda do backend para retornar a saída de acordo com o seguinte formato JSON:
```
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headerName": "headerValue", ... },
"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
"body": "..."
}
```
Na saída:
+ As chaves `headers` e `multiValueHeaders` podem ser não especificadas se nenhum cabeçalho de resposta extra precisar ser retornado.
+ A chave `headers` só pode conter cabeçalhos de valor único.
+ A chave `multiValueHeaders` pode conter cabeçalhos de vários valores e cabeçalhos de valor único. Você pode usar a chave `multiValueHeaders` para especificar todos os seus cabeçalhos extras, incluindo os de valor único.
+ Se você especificar valores para `headers` e `multiValueHeaders`, o API Gateway os mesclará em uma única lista. Se o mesmo de chave/valor for especificado em ambos, somente os valores de `multiValueHeaders` aparecerão na lista mesclada.
Para ativar o CORS da integração de proxy do Lambda, você deve adicionar `Access-Control-Allow-Origin:domain-name` à saída `headers`. `domain-name` pode ser `*` para qualquer nome de domínio. A saída `body` é organizado para o front-end como a carga de resposta do método. Se `body` for um blob binário, você poderá codificá-lo como uma string codificada em Base64, definindo `isBase64Encoded` como `true` e configurando `*/*` como **Binary Media Type (Tipo de mídia binário)**. Caso contrário, será possível defini-lo como `false` ou deixá-lo sem especificação.
**nota**
Para obter mais informações sobre como habilitar o suporte a binários, consulte [Ativação do suporte binário usando o console do API Gateway](api-gateway-payload-encodings-configure-with-console.md). Para obter um exemplo de função do Lambda, consulte [Exibir mídia binária de uma integração do proxy do Lambda no API Gateway](lambda-proxy-binary-media.md).
Se a saída da função for de um formato diferente, o API Gateway retorna uma resposta de erro `502 Bad Gateway`.
Para retornar uma resposta em uma função do Lambda em Node.js, você poderá usar comandos como o seguinte:
+ Para retornar um resultado bem-sucedido, chame `callback(null, {"statusCode": 200, "body": "results"})`.
+ Para lançar uma exceção, chame `callback(new Error('internal server error'))`.
+ Para um erro no lado do cliente, (se, por exemplo, um parâmetro necessário estiver ausente), você poderá chamar `callback(null, {"statusCode": 400, "body": "Missing parameters of ..."})` para retornar o erro sem lançar uma exceção.
Em uma função do Lambda `async` no Node.js, a sintaxe equivalente seria:
+ Para retornar um resultado bem-sucedido, chame `return {"statusCode": 200, "body": "results"}`.
+ Para lançar uma exceção, chame `throw new Error("internal server error")`.
+ Para um erro no lado do cliente, (se, por exemplo, um parâmetro necessário estiver ausente), você poderá chamar `return {"statusCode": 400, "body": "Missing parameters of ..."}` para retornar o erro sem lançar uma exceção.
# Configurar a integração de proxy do Lambda para o API Gateway usando a AWS CLI
Nesta seção, mostramos como usar uma API com a integração de proxy do Lambda usando a AWS CLI. Para obter instruções detalhadas sobre como usar o console do API Gateway para configurar um recurso de proxy com a integração de proxy do Lambda, consulte [Tutorial: Crie uma API REST com uma integração de proxy do Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md).
Como exemplo, usamos a seguinte função do Lambda como o backend da API:
```
export const handler = async(event, context) => {
console.log('Received event:', JSON.stringify(event, null, 2));
var res ={
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
}
};
var greeter = 'World';
if (event.greeter && event.greeter!=="") {
greeter = event.greeter;
} else if (event.body && event.body !== "") {
var body = JSON.parse(event.body);
if (body.greeter && body.greeter !== "") {
greeter = body.greeter;
}
} else if (event.queryStringParameters && event.queryStringParameters.greeter && event.queryStringParameters.greeter !== "") {
greeter = event.queryStringParameters.greeter;
} else if (event.multiValueHeaders && event.multiValueHeaders.greeter && event.multiValueHeaders.greeter != "") {
greeter = event.multiValueHeaders.greeter.join(" and ");
} else if (event.headers && event.headers.greeter && event.headers.greeter != "") {
greeter = event.headers.greeter;
}
res.body = "Hello, " + greeter + "!";
return res
};
```
Comparando isso à configuração de integração personalizada do Lambda em [Configurar integrações personalizadas do Lambda no API Gateway](set-up-lambda-custom-integrations.md), a entrada para essa função do Lambda pode ser expressa nos parâmetros da solicitação e no corpo. Você tem mais latitude para permitir que o cliente transmita os mesmos dados de entrada. Aqui, o cliente pode transmitir o nome do greeter como um parâmetro de string de consulta, um cabeçalho ou uma propriedade de corpo. A função também pode oferecer suporte à integração personalizada do Lambda. A configuração da API é mais simples. Você não configura a resposta de método nem a resposta de integração.
**Como configurar uma integração de proxy do Lambda usando a AWS CLI**
1. Use o comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) indicado abaixo para criar uma API:
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
A saída será exibida da seguinte forma:
```
{
"name": "HelloWorldProxy (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
A API `id` (`te6si5ach7`) e o `rootResourceId` (`krznpq9xpg`) são usados em todo este exemplo.
1. Use o comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) indicado abaixo para criar um [recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) `/greeting` do API Gateway:
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part {proxy+}
```
A saída será exibida da seguinte forma:
```
{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
Na próxima etapa, você usa o valor `id` (`2jf6xt`) do recurso `{proxy+}` para criar um método no recurso `/{proxy+}`.
1. Use o comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo para criar uma solicitação de método `ANY` de `ANY /{proxy+}`:
```
aws apigateway put-method --rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method ANY \
--authorization-type "NONE"
```
A saída será exibida da seguinte forma:
```
{
"apiKeyRequired": false,
"httpMethod": "ANY",
"authorizationType": "NONE"
}
```
Esse método de API permite que o cliente receba ou envie saudações da função do Lambda no backend.
1. Use o comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) indicado abaixo para configurar a integração do método `ANY /{proxy+}` com uma função do Lambda denominada `HelloWorld`. Essa função responde à solicitação com uma mensagem de `"Hello, {name}!"`, se o parâmetro `greeter` for fornecido ou `"Hello, World!"`, se o parâmetro de string de consulta não for definido.
```
aws apigateway put-integration \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method ANY \
--type AWS_PROXY \
--integration-http-method POST \
--uri arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:HelloWorld/invocations \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole
```
**Importante**
Para integrações do Lambda, você deve usar o método HTTP de `POST` para a solicitação de integração, de acordo com a [especificação da ação do serviço do Lambda para invocações de função](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). A função do IAM de `apigAwsProxyRole` deve ter políticas que permitem ao serviço `apigateway` invocar funções do Lambda. Para obter mais informações sobre as permissões do IAM, consulte [Modelo de permissões do API Gateway para invocar uma API](permissions.md#api-gateway-control-access-iam-permissions-model-for-calling-api).
A saída será exibida da seguinte forma:
```
{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:1234567890:function:HelloWorld/invocations",
"httpMethod": "POST",
"cacheNamespace": "vvom7n",
"credentials": "arn:aws:iam::1234567890:role/apigAwsProxyRole",
"type": "AWS_PROXY"
}
```
Em vez de fornecer um perfil do IAM para `credentials`, você pode usar o comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) para adicionar permissões baseadas em recurso. Isso é o que o console do API Gateway faz.
1. Use o comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) indicado abaixo para implantar a API em um estágio `test`:
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. Teste a API usando os seguintes comandos cURL em um terminal.
Chamando a API com o parâmetro de string de consulta de `?greeter=jane`:
```
curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=jane'
```
Chamando a API com um parâmetro de cabeçalho de `greeter:jane`:
```
curl -X GET https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \
-H 'content-type: application/json' \
-H 'greeter: jane'
```
Chamando a API com um corpo de `{"greeter":"jane"}`:
```
curl -X POST https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \
-H 'content-type: application/json' \
-d '{ "greeter": "jane" }'
```
Em todos os casos, a saída é uma resposta 200 com o corpo de resposta a seguir:
```
Hello, jane!
```
# Configurar um recurso de proxy com a integração de proxy do Lambda com uma definição OpenAPI
Para configurar um recurso de proxy com o tipo de integração de proxy do Lambda, crie um recurso de API com um parâmetro de caminho voraz (por exemplo, `/parent/{proxy+}`) e integre esse recurso a um backend da função do Lambda (por exemplo, `arn:aws:lambda:us-west-2:123456789012:function:SimpleLambda4ProxyResource`) no método `ANY`. O parâmetro de caminho voraz deve estar no final do caminho do recurso da API. Como no caso de um recurso não proxy, é possível configurar o recurso de proxy usando o console do API Gateway, importando um arquivo de definição do OpenAPI ou chamando diretamente a API REST do API Gateway.
O seguinte arquivo de definição de API do OpenAPI mostra um exemplo de uma API com um recurso de proxy que está integrado à função do Lambda chamada `SimpleLambda4ProxyResource`.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"version": "2016-09-12T17:50:37Z",
"title": "ProxyIntegrationWithLambda"
},
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"cacheNamespace": "roq9wj",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "aws_proxy"
}
}
}
},
"servers": [
{
"url": "https://gy415nuibc.execute-api.us-east-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/testStage"
}
}
}
]
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-09-12T17:50:37Z",
"title": "ProxyIntegrationWithLambda"
},
"host": "gy415nuibc.execute-api.us-east-1.amazonaws.com",
"basePath": "/testStage",
"schemes": [
"https"
],
"paths": {
"/{proxy+}": {
"x-amazon-apigateway-any-method": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "proxy",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {},
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200"
}
},
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"cacheNamespace": "roq9wj",
"cacheKeyParameters": [
"method.request.path.proxy"
],
"type": "aws_proxy"
}
}
}
}
}
```
------
Na integração de proxy do Lambda, em tempo de execução, o API Gateway mapeia uma solicitação de entrada no parâmetro `event` de entrada da função do Lambda. A entrada inclui o método de solicitação, o caminho, os cabeçalhos, qualquer parâmetro de consulta, qualquer carga, o contexto associado e quaisquer variáveis de estágio definidas. O formato de entrada é explicado em [Formato de entrada de uma função do Lambda para integração de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). Para o API Gateway mapear a saída do Lambda para respostas HTTP com êxito, a função do Lambda deve processar a saída do resultado no formato descrito em [Formato de saída de uma função do Lambda para integração de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format).
Com a integração de proxy do Lambda de um recurso de proxy por meio do método `ANY`, a função do Lambda de backend única serve como o manipulador de eventos para todas as solicitações por meio do recurso de proxy. Por exemplo, para registrar padrões de tráfego, você pode fazer com que um dispositivo móvel envie suas informações de localização de estado, cidade, rua e edifício, enviando uma solicitação com `/state/city/street/house` no caminho da URL para o recurso de proxy. Dessa forma, a função do Lambda de backend pode analisar o caminho da URL e inserir as tuplas de localização em uma tabela do DynamoDB.
# Configurar integrações personalizadas do Lambda no API Gateway
Para mostrar como configurar a integração personalizada ou sem proxy do Lambda, criamos uma API do API Gateway para expor o método `GET /greeting?greeter={name}` para invocar uma função do Lambda. Use um dos exemplos de funções do Lambda a seguir para a API.
Use um dos seguintes exemplos de funções do Lambda:
------
#### [ Node.js ]
```
'use strict';
var days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
var times = ['morning', 'afternoon', 'evening', 'night', 'day'];
export const handler = async(event) => {
console.log(event);
// Parse the input for the name, city, time and day property values
let name = event.name === null || event.name === undefined || event.name === "" ? 'you' : event.name;
let city = event.city === undefined ? 'World' : event.city;
let time = times.indexOf(event.time)<0 ? 'day' : event.time;
let day = days.indexOf(event.day)<0 ? null : event.day;
// Generate a greeting
let greeting = 'Good ' + time + ', ' + name + ' of ' + city + '. ';
if (day) greeting += 'Happy ' + day + '!';
// Log the greeting to CloudWatch
console.log('Hello: ', greeting);
// Return a greeting to the caller
return greeting;
};
```
------
#### [ Python ]
```
import json
def lambda_handler(event, context):
print(event)
res = {
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
}
}
if event['greeter'] == "":
res['body'] = "Hello, World"
elif (event['greeter']):
res['body'] = "Hello, " + event['greeter'] + "!"
else:
raise Exception('Missing the required greeter parameter.')
return res
```
------
A função responde com uma mensagem de `"Hello, {name}!"` se o valor do parâmetro `greeter` for uma string não vazia. Ela retornará uma mensagem de `"Hello, World!"` se o valor `greeter` for uma string vazia. A função retornará uma mensagem de erro de `"Missing the required greeter parameter."` se o parâmetro do greeter não estiver definido na solicitação de entrada. Atribuímos o nome à funçã `HelloWorld`.
Ela pode ser criada no console do Lambda ou usando a AWS CLI. Nesta seção, fazemos referência a essa função usando o seguinte Nome de recurso da Amazon (ARN):
```
arn:aws:lambda:us-east-1:123456789012:function:HelloWorld
```
Com a função do Lambda definida no backend, configure a API.
**Como configurar a integração personalizada do Lambda usando a AWS CLI**
1. Use o comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) indicado abaixo para criar uma API:
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
A saída será exibida da seguinte forma:
```
{
"name": "HelloWorld (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
A API `id` (`te6si5ach7`) e o `rootResourceId` (`krznpq9xpg`) são usados em todo este exemplo.
1. Use o comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) indicado abaixo para criar um [recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) `/greeting` do API Gateway:
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part greeting
```
A saída será exibida da seguinte forma:
```
{
"path": "/greeting",
"pathPart": "greeting",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
Na próxima etapa, você usa o valor `id` (`2jf6xt`) do recurso `greeting` para criar um método no recurso `/greeting`.
1. Use o comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo para criar uma solicitação de método de API de `GET /greeting?greeter={name}`:
```
aws apigateway put-method --rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.querystring.greeter=false
```
A saída será exibida da seguinte forma:
```
{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE",
"requestParameters": {
"method.request.querystring.greeter": false
}
}
```
Esse método de API permite que o cliente receba uma saudação da função do Lambda no backend. O parâmetro `greeter` é opcional, pois o backend deve lidar com um autor da chamada anônimo ou um autor da chamada autoidentificado.
1. Use o comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) indicado abaixo para configurar a resposta `200 OK` à solicitação de método de `GET /greeting?greeter={name}`:
```
aws apigateway put-method-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200
```
1. Use o comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) indicado abaixo para configurar a integração do método `GET /greeting?greeter={name}` com uma função do Lambda denominada `HelloWorld`. A função responde à solicitação com uma mensagem de `"Hello, {name}!"`, se o parâmetro `greeter` for fornecido ou `"Hello, World!"`, se o parâmetro de string de consulta não for definido.
```
aws apigateway put-integration \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--type AWS \
--integration-http-method POST \
--uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations \
--request-templates '{"application/json":"{\"greeter\":\"$input.params('greeter')\"}"}' \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole
```
O modelo de mapeamento fornecido aqui converte o parâmetro de string de consulta `greeter` na propriedade `greeter` da carga útil JSON. Isso é necessário porque a entrada para uma função do Lambda deve ser expressa no corpo.
**Importante**
Para integrações do Lambda, você deve usar o método HTTP de `POST` para a solicitação de integração, de acordo com a [especificação da ação do serviço do Lambda para invocações de função](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). O parâmetro `uri` é o Nome de recurso da Amazon (ARN) da ação de invocação da função.
A saída será exibida da seguinte forma:
```
{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\"greeter\":\"$input.params('greeter')\"}"
},
"cacheNamespace": "krznpq9xpg",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"type": "AWS"
}
```
A função do IAM de `apigAwsProxyRole` deve ter políticas que permitem ao serviço `apigateway` invocar funções do Lambda. Em vez de fornecer uma função do IAM para `credentials`, você pode chamar o comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) para adicionar permissões baseadas em recurso. É assim que o console do API Gateway adiciona essas permissões.
1. Use o comando [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html) indicado abaixo para configurar a resposta de integração e transmitir a saída da função do Lambda ao cliente como a resposta de método `200 OK`.
```
aws apigateway put-integration-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200 \
--selection-pattern ""
```
Ao definir o padrão de seleção como uma string vazia, a resposta `200 OK` é o padrão.
A saída será exibida da seguinte forma:
```
{
"selectionPattern": "",
"statusCode": "200"
}
```
1. Use o comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) indicado abaixo para implantar a API em um estágio `test`:
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. Teste a API usando o seguinte comando cURL em um terminal:
```
curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=me' \
-H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751'
```
# Configurar a invocação assíncrona da função do Lambda do backend
Na integração não proxy do Lambda (personalizada), a função do Lambda do backend é invocada de forma síncrona por padrão. Este é o comportamento desejado para a maioria das operações da API REST. No entanto, alguns aplicativos exigem que o trabalho seja executado de forma assíncrona (como uma operação em lote ou uma operação de longa latência), normalmente por um componente de backend separado. Nesse caso, a função de backend do Lambda é invocada de forma assíncrona, o método da API REST do front-end não retorna o resultado.
É possível configurar a função do Lambda para que uma integração não proxy do Lambda seja invocada de forma assíncrona especificando `'Event'` como o [tipo de invocação do ](https://docs.aws.amazon.com/lambda/latest/dg/lambda-invocation.html). Isso é feito da seguinte forma:
## Configurar a invocação assíncrona do Lambda no console do API Gateway
Para que todas as invocações sejam assíncronas:
+ Em **Solicitação de integração**, adicione um cabeçalho `X-Amz-Invocation-Type` com um valor estático de `'Event'`.
Para que os clientes decidam se as invocações são assíncronas ou síncronas:
1. Em **Solicitação de método**, adicione um cabeçalho `InvocationType`.
1. Em **Solicitação de integração**, adicione um cabeçalho `X-Amz-Invocation-Type` com uma expressão de mapeamento de `method.request.header.InvocationType`.
1. Os clientes podem incluir o cabeçalho `InvocationType: Event` em solicitações de API para chamadas assíncronas ou `InvocationType: RequestResponse` para chamadas síncronas.
## Configurar a invocação assíncrona do Lambda usando o OpenAPI
Para que todas as invocações sejam assíncronas:
+ Adicione o cabeçalho `X-Amz-Invocation-Type` à seção **x-amazon-apigateway-integration**.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.X-Amz-Invocation-Type" : "'Event'"
},
"passthroughBehavior" : "when_no_match",
"contentHandling" : "CONVERT_TO_TEXT"
}
```
Para que os clientes decidam se as invocações são assíncronas ou síncronas:
1. Adicione o cabeçalho a seguir em qualquer [objeto de item de caminho do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject).
```
"parameters" : [ {
"name" : "InvocationType",
"in" : "header",
"schema" : {
"type" : "string"
}
} ]
```
1. Adicione o cabeçalho `X-Amz-Invocation-Type` à seção **x-amazon-apigateway-integration**.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.X-Amz-Invocation-Type" : "method.request.header.InvocationType"
},
"passthroughBehavior" : "when_no_match",
"contentHandling" : "CONVERT_TO_TEXT"
}
```
1. Os clientes podem incluir o cabeçalho `InvocationType: Event` em solicitações de API para chamadas assíncronas ou `InvocationType: RequestResponse` para chamadas síncronas.
## Configurar a invocação assíncrona do Lambda usando o CloudFormation
Os modelos CloudFormation a seguir mostram como configurar o `AWS::ApiGateway::Method` para invocações assíncronas.
Para que todas as invocações sejam assíncronas:
```
AsyncMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref AsyncResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
RequestParameters:
integration.request.header.X-Amz-Invocation-Type: "'Event'"
IntegrationResponses:
- StatusCode: '200'
IntegrationHttpMethod: POST
Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations
MethodResponses:
- StatusCode: '200'
```
Para que os clientes decidam se as invocações são assíncronas ou síncronas:
```
AsyncMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref AsyncResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
RequestParameters:
method.request.header.InvocationType: false
Integration:
Type: AWS
RequestParameters:
integration.request.header.X-Amz-Invocation-Type: method.request.header.InvocationType
IntegrationResponses:
- StatusCode: '200'
IntegrationHttpMethod: POST
Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations
MethodResponses:
- StatusCode: '200'
```
Os clientes podem incluir o cabeçalho `InvocationType: Event` em solicitações de API para chamadas assíncronas ou `InvocationType: RequestResponse` para chamadas síncronas.
# Manipular erros do Lambda no API Gateway
Para integrações personalizadas do Lambda, você deve mapear erros retornados pelo Lambda na resposta de integração para respostas de erro HTTP padrão para os seus clientes. Caso contrário, os erros do Lambda serão retornados como respostas `200 OK` por padrão, e o resultado não será intuitivo para os usuários da sua API.
Existem dois tipos de erros que o Lambda pode retornar: erros padrão e erros personalizados. Na sua API, você deve lidar com eles de maneira diferente.
Com a integração de proxy do Lambda, o Lambda precisa retornar uma saída com o seguinte formato:
```
{
"isBase64Encoded" : "boolean",
"statusCode": "number",
"headers": { ... },
"body": "JSON string"
}
```
Nessa saída, `statusCode` é normalmente `4XX` para um erro de cliente e `5XX` para um erro de servidor. O API Gateway lida com esses erros, mapeando o erro do Lambda para uma resposta de erro HTTP, de acordo com o especificad `statusCode`. Para que o API Gateway transmita o tipo de erro (por exemplo, `InvalidParameterException`) como parte da resposta ao cliente, a função do Lambda deve incluir um cabeçalho (por exemplo, `"X-Amzn-ErrorType":"InvalidParameterException"`) na propriedade `headers`.
**Topics**
+ [Manipule erros padrão do Lambda no API Gateway](#handle-standard-errors-in-lambda-integration)
+ [Manipule erros personalizados do Lambda no API Gateway](#handle-custom-errors-in-lambda-integration)
## Manipule erros padrão do Lambda no API Gateway
Um erro do AWS Lambda padrão tem o seguinte formato:
```
{
"errorMessage": "string",
"errorType": "string",
"stackTrace": [
"string",
...
]
}
```
Aqui, `errorMessage` é uma expressão de string do erro. O `errorType` é um erro ou tipo de exceção que depende da linguagem. O `stackTrace` é uma lista de expressões de string que mostra o rastreamento de pilha que leva à ocorrência do erro.
Por exemplo, considere a seguinte função do Lambda do JavaScript (Node.js).
```
export const handler = function(event, context, callback) {
callback(new Error("Malformed input ..."));
};
```
Essa função retorna o seguinte erro padrão do Lambda, contendo `Malformed input ...` como a mensagem de erro:
```
{
"errorMessage": "Malformed input ...",
"errorType": "Error",
"stackTrace": [
"export const handler (/var/task/index.js:3:14)"
]
}
```
Da mesma forma, considere a seguinte função do Lambda Python, que gera um `Exception` com a mesma mensagem de erro `Malformed input ...`.
```
def lambda_handler(event, context):
raise Exception('Malformed input ...')
```
Essa função retorna o seguinte erro padrão do Lambda:
```
{
"stackTrace": [
[
"/var/task/lambda_function.py",
3,
"lambda_handler",
"raise Exception('Malformed input ...')"
]
],
"errorType": "Exception",
"errorMessage": "Malformed input ..."
}
```
Observe que os valores de propriedade `errorType` e `stackTrace` são dependentes da linguagem. O erro-padrão também se aplica a qualquer objeto de erro que seja uma extensão do objeto `Error` ou uma subclasse da classe `Exception`.
Para mapear o erro padrão do Lambda para uma resposta de método, você deve primeiro decidir sobre um código de status HTTP para um determinado erro do Lambda. Depois, defina um padrão de expressão regular na propriedade `[selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern)` do recurso [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) associado ao código de status HTTP especificado. No console do API Gateway, este `selectionPattern` é indicado como **regex de erro do Lambda** na seção **Resposta de integração**, abaixo de cada resposta de integração.
**nota**
O API Gateway usa regexes de estilo padrão de Java para o mapeamento de resposta. Para obter mais informações, consulte [Padrão](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) na documentação do Oracle.
Por exemplo, use o comando [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html) indicado abaixo para definir uma nova expressão `selectionPattern`:
```
aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --http-method GET --status-code 400 --selection-pattern "Malformed.*" --region us-west-2
```
Certifique-se de configurar também o código de erro correspondente (`400`) na [resposta do método](api-gateway-method-settings-method-response.md#setup-method-response-status-code). Caso contrário, o API Gateway lançará uma resposta de erro de configuração inválida em tempo de execução.
**nota**
No tempo de execução, o API Gateway corresponde a `errorMessage` do erro do Lambda em relação ao padrão da expressão regular na propriedade `selectionPattern`. Se houver uma correspondência, o API Gateway retornará o erro do Lambda como uma resposta HTTP do código de status HTTP correspondente. Se não houver correspondência, o API Gateway retornará o erro como uma resposta padrão ou lançará uma exceção de configuração inválida se não houver uma resposta padrão configurada.
Definir o valor `selectionPattern` como `.*` para uma determinada resposta redefine essa resposta como a resposta padrão. Isso ocorre porque esse padrão de seleção corresponderá a todas as mensagens de erro, incluindo nulo, ou seja, qualquer mensagem de erro não especificado. O mapeamento resultante substitui o mapeamento padrão. Se você usar `.+` como o padrão de seleção para filtrar respostas, saiba que ele pode não corresponder a uma resposta que contém um caractere de nova linha (`\n`).
Para atualizar um valor `selectionPattern` existente usando a AWS CLI, chame a operação [update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html) para substituir o valor do caminho `/selectionPattern` pela expressão regex especificada do padrão `Malformed*`.
Para definir a expressão `selectionPattern` usando o console do API Gateway, digite a expressão na caixa de texto **Regex de erro do Lambda** ao configurar ou atualizar uma resposta de integração de um código de status HTTP especificado.
## Manipule erros personalizados do Lambda no API Gateway
Em vez do erro padrão descrito na seção anterior, o AWS Lambda permite retornar um objeto de erro personalizado como uma string JSON. O erro pode ser qualquer objeto JSON válido. Por exemplo, a seguinte função do Lambda do JavaScript (Node.js) retorna um erro personalizado:
```
export const handler = (event, context, callback) => {
...
// Error caught here:
var myErrorObj = {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
callback(JSON.stringify(myErrorObj));
};
```
Você deve transformar o objeto `myErrorObj` em uma string JSON antes de chamar `callback` para sair da função. Caso contrário, `myErrorObj` será retornado como uma string de `"[object Object]"`. Quando um método da sua API é integrado com a função do Lambda anterior, o API Gateway recebe uma resposta de integração com a seguinte carga:
```
{
"errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}"
}
```
Como ocorre com qualquer resposta de integração, é possível transmitir essa resposta de erro em seu estado inalterado como a reposta do método. Outra opção é fazer com que um modelo de mapeamento transforme a carga útil em um formato diferente. Por exemplo, considere o seguinte modelo de mapeamento de corpo para uma resposta de método do código de status `500`:
```
{
errorMessage: $input.path('$.errorMessage');
}
```
Esse modelo converte o corpo da resposta de integração que contém a string JSON no seguinte corpo de resposta de método. Esse corpo de resposta de método contém o objeto JSON de erro personalizado:
```
{
"errorMessage" : {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
};
```
Dependendo dos requisitos da sua API, talvez você precise transmitir algumas das propriedades do erro personalizado, ou todas elas, como parâmetros de cabeçalho da resposta de método. Isso pode ser feito aplicando os mapeamentos de erros personalizados do corpo da resposta de integração aos cabeçalhos da resposta de método.
Por exemplo, a seguinte extensão do OpenAPI define um mapeamento das propriedades `errorMessage.errorType`, `errorMessage.httpStatus`, `errorMessage.trace.function` e `errorMessage.trace` para os cabeçalhos `error_type`, `error_status`, `error_trace_function` e `error_trace`, respectivamente.
```
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.error_trace_function": "integration.response.body.errorMessage.trace.function",
"method.response.header.error_status": "integration.response.body.errorMessage.httpStatus",
"method.response.header.error_type": "integration.response.body.errorMessage.errorType",
"method.response.header.error_trace": "integration.response.body.errorMessage.trace"
},
...
}
}
}
```
Em tempo de execução, o API Gateway desserializa o parâmetro `integration.response.body` ao executar mapeamentos de cabeçalho. No entanto, essa desserialização aplica-se somente aos mapeamentos de corpo para cabeçalho de respostas de erro personalizado do Lambda, e não a mapeamentos de corpo para corpo usando `$input.body`. Com esses mapeamentos de corpo para cabeçalho de erro personalizado, o cliente recebe os seguintes cabeçalhos como parte da resposta de método, desde que os cabeçalhos `error_status`, `error_trace`, `error_trace_function` e `error_type` estejam declarados na solicitação do método.
```
"error_status":"500",
"error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}",
"error_trace_function":"abc()",
"error_type":"InternalServerError"
```
A propriedade `errorMessage.trace` do corpo da resposta de integração é uma propriedade complexa. Ela é mapeada para o cabeçalho `error_trace` como uma string JSON.