Erstellen von AWS Lambda-Proxy-Integrationen für HTTP-APIs in API Gateway - Amazon API Gateway
NutzlastformatversionAntwortformat der Lambda-Funktion

Erstellen von AWS Lambda-Proxy-Integrationen für HTTP-APIs in API Gateway

Eine Lambda-Proxy-Integration ermöglicht es Ihnen, eine API-Route in eine Lambda-Funktion zu integrieren. Wenn ein Client Ihre API aufruft, sendet API Gateway die Anfrage an die Lambda-Funktion und gibt die Antwort der Funktion an den Client zurück. Beispiele zum Erstellen einer HTTP-API finden Sie unter Erstellen einer HTTP-API.

Nutzlastformatversion

Die Nutzlastformatversion gibt das Format des Ereignisses an, das API Gateway an eine Lambda-Integration sendet und wie API Gateway die Lambda-Antwort interpretiert. Wenn Sie keine Nutzlastformatversion angeben, verwendet die AWS Management Console standardmäßig die neueste Version. Wenn Sie eine Lambda-Integration mithilfe der AWS CLI, AWS CloudFormation oder eines SDK erstellen, müssen Sie eine payloadFormatVersion angeben. Die unterstützten Werte sind 1.0 und 2.0.

Weitere Informationen zum Einrichten von payloadFormatVersion, finden Sie unter create-integration. Weitere Informationen zur Ermittlung des payloadFormatVersion einer vorhandenen Integration finden Sie unter get-integration

Nutzlastformatunterschiede

In der folgenden Liste sehen Sie die Unterschiede zwischen den Payload-Formatversionen 1.0 und 2.0:

  • Das Format 2.0 hat keine multiValueHeaders- oder multiValueQueryStringParameters-Felder. Doppelte Header werden mit Kommas kombiniert und in das headers-Feld aufgenommen. Doppelte Abfragezeichenfolgen werden mit Kommas kombiniert und in das queryStringParameters-Feld aufgenommen.

  • Das Format 2.0 hat rawPath. Wenn Sie eine API-Zuordnung verwenden, um Ihre Stufe mit einem benutzerdefinierten Domainnamen zu verbinden, stellt rawPath den API-Zuordnungswert nicht bereit. Verwenden Sie die Formate 1.0 und path, um auf die API-Zuordnung für Ihren benutzerdefinierten Domainnamen zuzugreifen.

  • Das Format 2.0 enthält ein neues cookies-Feld. Alle Cookie-Header in der Anforderung werden mit Kommas kombiniert und dem cookies-Feld hinzugefügt. In der Antwort an den Client wird jedes Cookie zu einem set-cookie-Header.

Nutzdatenformatstruktur

Die folgenden Beispiele zeigen die Struktur jeder Nutzlastformatversion. Alle Header-Namen werden in Kleinbuchstaben angegeben.

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
}

Antwortformat der Lambda-Funktion

Die Nutzlastformatversion bestimmt die Struktur der Antwort, die Ihre Lambda-Funktion zurückgeben muss.

Lambda-Funktionsantwort für Format 1.0

Bei der 1.0-Formatversion müssen Lambda-Integrationen eine Antwort im folgenden JSON-Format zurückgeben.

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

Lambda-Funktionsantwort für Format 2.0

Bei der 2.0-Formatversion kann API Gateway das Antwortformat für Sie ableiten. API Gateway geht von den folgenden Annahmen aus, wenn Ihre Lambda-Funktion gültigen JSON-Code und keinen zurückgib statusCode:

  • isBase64Encoded ist false.

  • statusCode ist 200.

  • content-type ist application/json.

  • body ist die Antwort der Funktion.

Die folgenden Beispiele zeigen die Ausgabe einer Lambda-Funktion und die Interpretation von API Gateway.

Lambda-Funktionsausgabe API Gateway-Interpretation 
"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"
  }
}

Um die Antwort anzupassen, sollte Ihre Lambda-Funktion eine Antwort im folgenden Format zurückgeben.

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