HTTPAPIs在API閘道中建立 AWS Lambda 代理整合 - Amazon API Gateway
裝載格式版本Lambda 函數回應格式

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

HTTPAPIs在API閘道中建立 AWS Lambda 代理整合

Lambda 代理整合可讓您將API路由與 Lambda 函數整合。當用戶端呼叫您的時候API，APIGateway 會將請求傳送至 Lambda 函數，並將函數的回應傳回給用戶端。如需建立的範例 HTTPAPI，請參閱創建一個 HTTP API。

裝載格式版本

承載格式版本指定API閘道傳送至 Lambda 整合的事件格式，以及API閘道如何解譯 Lambda 的回應。如果您未指定承載格式版本，預設 AWS Management Console 會使用最新版本。如果您使用 AWS CLI、 AWS CloudFormation或建立 Lambda 整合SDK，則必須指定payloadFormatVersion. 支援的值為 1.0 和 2.0。

如需如何設定的詳細資訊payloadFormatVersion，請參閱建立整合。如需如何判斷現有整合payloadFormatVersion的詳細資訊，請參閱取得整合

裝載格式差異

下列清單顯示1.0和2.0裝載格式版本之間的差異：

  • 格式 2.0 沒有 multiValueHeaders 或 multiValueQueryStringParameters 欄位。重複的標題與逗號相結合，並包含在 headers 欄位中。重複的查詢字串與逗號相結合，並包含在 queryStringParameters 欄位中。

  • 格式2.0有rawPath. 如果您使用API映射將舞台連接到自定義域名，則rawPath不會提供API映射值。使用格式1.0和存path取您自訂網域名稱的API對應。

  • 格式 2.0 包括新的 cookies 欄位。請求中的所有 Cookie 標頭都與逗號相結合並新增到該 cookies 欄位中。在對用戶端地回應中，每個 Cookie 都會變成 set-cookie 標題。

裝載格式結構

下列範例顯示每個裝載格式版本的結構。所有標題名稱都是小寫字母。

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
}

Lambda 函數回應格式

承載格式版本會決定 Lambda 函數必須傳回的回應結構。

格式 1.0 的 Lambda 函數回應

使用1.0格式版本時，Lambda 整合必須以下列JSON格式傳回回應：

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

格式 2.0 的 Lambda 函數回應

使用2.0格式版本，APIGateway 可以為您推斷響應格式。API如果您的 Lambda 函數傳回有效JSON且未傳回，閘道會進行下列假設statusCode：

  • isBase64Encoded 是 false。

  • statusCode 是 200。

  • content-type 是 application/json。

  • body 是函數的回應。

下列範例顯示 Lambda 函數和API閘道解譯的輸出。

Lambda 函數輸出 API閘道解釋 
"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"
  }
}

若要自定義回應，您的 Lambda 函數應該會傳回下列格式的回應。

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