Criar integrações de proxy AWS Lambda para APIs HTTP no API Gateway - Amazon API Gateway
Versão do formato da carga útilFormato de resposta da função do Lambda

Criar integrações de proxy AWS Lambda para APIs HTTP no API Gateway

Uma integração de proxy do Lambda permite integrar uma rota de API com uma função do Lambda. Quando um cliente chama sua API, o API Gateway envia a solicitação para a função do Lambda e retorna a resposta da função para o cliente. Para obter exemplos de criação de uma API HTTP, consulte Criar uma API HTTP.

Versão do formato da carga útil

A versão do formato de carga útil especifica o formato do evento que o API Gateway envia para uma integração do Lambda e como o API Gateway interpreta a resposta do Lambda. Por padrão, se você não especificar uma versão de formato de carga útil, o AWS Management Console usará a versão mais recente. Se você criar uma integração do Lambda usando a AWS CLI, o AWS CloudFormation ou um SDK, será necessário especificar um payloadFormatVersion. Os valores suportados são 1.0 e 2.0.

Para saber mais sobre como definir opayloadFormatVersion, consulte create-integration. Para saber mais sobre como determinar a payloadFormatVersion de uma integração existente, consulte get-integration.

Diferenças do formato da carga útil

A lista a seguir mostra as diferenças entre as versões do formato da carga útil 1.0 e 2.0:

  • O formato 2.0 não tem campos multiValueHeaders ou multiValueQueryStringParameters. Os cabeçalhos duplicados são combinados com vírgulas e incluídos no campo headers. As strings de consulta duplicadas são combinadas com vírgulas e incluídas no campo queryStringParameters.

  • O formato 2.0 tem rawPath. Se você usar um mapeamento de API para associar o estágio a um nome de domínio personalizado, rawPath não fornecerá o valor do mapeamento de API. Use o formato 1.0 e path para acessar o mapeamento da API de seu nome de domínio personalizado.

  • O formato 2.0 inclui um novo campo cookies. Todos os cabeçalhos de cookie na solicitação são combinados com vírgulas e adicionados ao campo cookies. Na resposta ao cliente, cada cookie torna-se um cabeçalho set-cookie.

Estrutura do formato da carga útil

Os exemplos a seguir mostram a estrutura de cada versão do formato de carga útil. Todos os nomes de cabeçalho ficam em letras minúsculas.

2.0
{
  "version": "2.0",
  "routeKey": "$default",
  "rawPath": "/my/path",
  "rawQueryString": "parameter1=value1&parameter1=value2&parameter2=value",
  "cookies": [
    "cookie1",
    "cookie2"
  ],
  "headers": {
    "header1": "value1",
    "header2": "value1,value2"
  },
  "queryStringParameters": {
    "parameter1": "value1,value2",
    "parameter2": "value"
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "api-id",
    "authentication": {
      "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"
        }
      }
    },
    "authorizer": {
      "jwt": {
        "claims": {
          "claim1": "value1",
          "claim2": "value2"
        },
        "scopes": [
          "scope1",
          "scope2"
        ]
      }
    },
    "domainName": "id.execute-api.us-east-1.amazonaws.com",
    "domainPrefix": "id",
    "http": {
      "method": "POST",
      "path": "/my/path",
      "protocol": "HTTP/1.1",
      "sourceIp": "192.0.2.1",
      "userAgent": "agent"
    },
    "requestId": "id",
    "routeKey": "$default",
    "stage": "$default",
    "time": "12/Mar/2020:19:03:58 +0000",
    "timeEpoch": 1583348638390
  },
  "body": "Hello from Lambda",
  "pathParameters": {
    "parameter1": "value1"
  },
  "isBase64Encoded": false,
  "stageVariables": {
    "stageVariable1": "value1",
    "stageVariable2": "value2"
  }
}
1.0
{
  "version": "1.0",
  "resource": "/my/path",
  "path": "/my/path",
  "httpMethod": "GET",
  "headers": {
    "header1": "value1",
    "header2": "value2"
  },
  "multiValueHeaders": {
    "header1": [
      "value1"
    ],
    "header2": [
      "value1",
      "value2"
    ]
  },
  "queryStringParameters": {
    "parameter1": "value1",
    "parameter2": "value"
  },
  "multiValueQueryStringParameters": {
    "parameter1": [
      "value1",
      "value2"
    ],
    "parameter2": [
      "value"
    ]
  },
  "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": "192.0.2.1",
      "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
}

Formato de resposta da função do Lambda

A versão do formato da carga determina a estrutura da resposta que a função do Lambda deve retornar.

Resposta de função do Lambda para o formato 1.0

Com a versão do formato 1.0, as integrações do Lambda devem retornar uma resposta no formato JSON a seguir:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headername": "headervalue", ... },
    "multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
    "body": "..."
}

Resposta de função do Lambda para o formato 2.0

Com a versão de formato 2.0, o API Gateway pode inferir o formato de resposta para você. O API Gateway fará as suposições a seguir se sua função do Lambda retornar JSON válido e não retornar um statusCode:

  • isBase64Encoded é false.

  • statusCode é 200.

  • content-type é application/json.

  • body é a resposta da função.

Os exemplos a seguir mostram a saída de uma função do Lambda e a interpretação do API Gateway.

Saída da função do Lambda Interpretação do API Gateway 
"Hello from Lambda!"
 
{
  "isBase64Encoded": false,
  "statusCode": 200,
  "body": "Hello from Lambda!",
  "headers": {
    "content-type": "application/json"
  }
}
 
{ "message": "Hello from Lambda!" }
 
{
  "isBase64Encoded": false,
  "statusCode": 200,
  "body": "{ \"message\": \"Hello from Lambda!\" }",
  "headers": {
    "content-type": "application/json"
  }
}

Para personalizar a resposta, a função do Lambda deve retornar uma resposta com o formato a seguir.

{
    "cookies" : ["cookie1", "cookie2"],
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headername": "headervalue", ... },
    "body": "Hello from Lambda!"
}