Amazon API Gateway
Entwicklerhandbuch

Einrichten von Lambda-Proxy-Integrationen in API Gateway

Grundlegendes zur API Gateway Lambda-Proxy-Integration

Die Amazon API Gateway Lambda-Proxy-Integration ist ein einfacher, leistungsstarker und schlanker Mechanismus für die Entwicklung einer API über die Einrichtung einer einzelnen API-Methode. Die Lambda-Proxy-Integration bietet dem Client die Möglichkeit, eine einzige Lambda-Funktion im Backend aufzurufen. Die Funktion greift auf viele Ressourcen oder Funktionen von anderen AWS-Services zu, einschließlich Aufrufen anderer Lambda Funktionen.

Wenn ein Client in einer Lambda-Proxy-Integration eine API-Anforderung sendet, übergibt API Gateway die Raw-Anforderung an die integrierte Lambda-Funktion unverändert. Lediglich die Reihenfolge der Anforderungsparameter wird nicht beibehalten. Diese Anforderungsdaten umfassen die Abfrage-Header, Parameter für Abfragezeichenfolgen, die URL-Pfadvariablen, die Nutzlast und API-Konfigurationsdaten. Die Konfigurationsdaten können den aktuellen Bereitstellungsstufennamen, Stufenvariablen, die Benutzeridentität oder den Autorisierungskontext (falls vorhanden) umfassen. Die Backend-Lambda-Funktion analysiert die eingehenden Anforderungsdaten, um die eigene Antwort zu bestimmen. Damit API Gateway die LambdaAusgabe erfolgreich als API-Antwort an den Client übergeben kann, muss die Lambda-Funktion das Ergebnis in diesem Format ausgeben.

Da API Gateway bei der Lambda-Proxy-Integration nicht sehr viel zwischen dem Client und der Backend-LambdaFunktion eingreift, können der Client und die integrierte Lambda-Funktion bei Änderungen gegenseitig angepasst werden, ohne dass die vorhandene Integration der API zerstört wird. Hierzu muss der Client den Anwendungsprotokollen der Backend-Lambda-Funktion folgen.

Sie können eine Lambda-Proxy-Integration für alle API-Methoden einrichten. Aber eine Lambda-Proxy-Integration ist leistungsstärker, wenn sie über eine allgemeine Proxy-Ressource für eine API-Methode konfiguriert wird. Die allgemeine Proxy-Ressource kann durch eine spezielle Vorlagenpfadvariable {proxy+}, den Catch-All-ANY-Methodenplatzhalter oder beides angegeben werden. Der Client kann die Eingabe an die Backend-Lambda-Funktion in der eingehenden Anforderung als Anforderungsparameter oder als entsprechende Nutzlast übergeben. Zu den Anforderungsparametern gehören Header-, URL-Pfadvariablen, Abfragezeichenfolgenparameter und die entsprechende Nutzlast. Die integrierte Lambda-Funktion prüft alle Eingangsquellen vor ihrer Verarbeitung und der Antwort an den Client mit sinnvollen Fehlermeldungen, falls die erforderliche Eingabe fehlt.

Beim Aufrufen einer mit der allgemeinen HTTP-Methode ANY und der allgemeinen Ressource {proxy+} integrierten API-Methode sendet der Client eine Anforderung mit einer bestimmten HTTP-Methode statt mit ANY. Der Client gibt zudem einen bestimmten URL-Pfad statt {proxy+} an und umfasst alle erforderlichen Header, Abfragezeichenfolgenparameter oder eine anwendbare Nutzlast.

Die folgende Liste enthält eine Zusammenfassung des Laufzeitverhaltens verschiedener API-Methoden bei der Lambda-Proxy-Integration:

  • ANY /{proxy+}: Der Client muss eine bestimmte HTTP-Methode auswählen, eine bestimmte Ressourcenpfadhierarchie festlegen und kann alle Header, Parameter für Abfragezeichenfolgen und die Nutzlast für die Eingabe an die integrierte Lambda-Funktion festlegen.

  • ANY /res: Der Client muss eine bestimmte HTTP-Methode auswählen und kann alle Header, Parameter für Abfragezeichenfolgen und die Nutzlast für die Eingabe an die integrierte Lambda-Funktion festlegen.

  • GET|POST|PUT|... /{proxy+}: Der Client kann eine bestimmte Ressourcenpfadhierarchie festlegen und kann alle Header, Parameter für Abfragezeichenfolgen und die Nutzlast für die Eingabe an die integrierte Lambda-Funktion festlegen.

  • GET|POST|PUT|... /res/{path}/...: Der Client muss ein bestimmtes Pfadsegment (für die {path}-Variable) festlegen und kann alle Anforderungs-Header, Parameter für Abfragezeichenfolgen und die Nutzlast für die Eingabedaten an die integrierte Lambda-Funktion festlegen.

  • GET|POST|PUT|... /res: Der Client kann bestimmte Anforderungs-Header auswählen und kann alle Header, Parameter für Abfragezeichenfolgen und die Nutzlast für die Eingabedaten an die integrierte Lambda-Funktion festlegen.

Sowohl die Proxy-Ressource {proxy+} und die benutzerdefinierte Ressource {custom} werden als Vorlagenpfadvariablen ausgedrückt. Allerdings kann {proxy+} auf alle Ressourcen in einer Pfadhierarchie verweisen, während sich {custom} nur auf ein bestimmtes Pfadsegment bezieht. Beispielsweise könnte ein Lebensmittelgeschäft sein Online-Produktsortiment nach Abteilungsnamen, Kategorien und Produktarten organisieren. Die Website des Lebensmittelgeschäfts kann dann verfügbare Produkte über die folgenden Vorlagenpfadvariablen darstellen: /{department}/{produce-category}/{product-type}. Zum Beispiel werden Äpfel mit /produce/fruit/apple und Karotten mit /produce/vegetables/carrot dargestellt. Es kann auch /{proxy+} als Platzhalter für eine beliebige Abteilung, eine beliebige Kategorie oder einen Produkttyp verwendet werden, nach dem ein Kunde im Online-Shop suchen kann. Beispielsweise kann /{proxy+} auf eines der folgenden Elemente verweisen:

  • /produce

  • /produce/fruit

  • /produce/vegetables/carrot

Um Kunden nach den verfügbaren Produkten, der Kategorie und der zugeordneten Abteilung suchen zu lassen, können Sie eine einzelne GET /{proxy+}-Methode mit Leseberechtigungen bereitstellen. Um einem Supervisor das Aktualisieren des produce Abteilungsbestands zu ermöglichen, können Sie eine andere, einzelne PUT /produce/{proxy+}-Methode mit Lese-/Schreibberechtigungen hinzufügen. Um einem Kassierer das Aktualisieren der Gesamtsumme einer Gemüsesorte zu ermöglichen, können Sie eine POST /produce/vegetables/{proxy+}-Methode mit Lese-/Schreibberechtigungen einrichten. Wenn ein Shop-Manager sämtliche möglichen Aktionen für beliebige verfügbare Produkte durchführen soll, kann der Online-Shop-Entwickler die ANY /{proxy+} Methode mit Lese-/Schreibberechtigungen hinzufügen. In jedem Fall muss der Kunde oder der Mitarbeiter zur Laufzeit ein bestimmtes Produkt eines bestimmten Typs in einer bestimmten Abteilung, eine bestimmte Kategorie in einer bestimmten Abteilung, oder eine bestimmte Abteilung auswählen.

Weitere Informationen zur Einrichtung der API Gateway-Proxy-Integrationen finden Sie unter Einrichten der Proxy-Integration mit einer Proxy-Ressource.

Die Proxy-Integration erfordert, dass der Client über detaillierte Kenntnisse der Backend-Anforderungen verfügt. Aus diesem Grund muss der Backend-Entwickler die Anforderungen des Backends klar an den Client-Entwickler kommunizieren. Er muss einen robusten Feedback-Mechanismus für nicht erfüllte Anforderungen bereitstellen.

Unterstützung für mehrwertige Header- und Abfragezeichenfolgenparameter

API Gateway unterstützt jetzt mehrere Header- und Abfragezeichenfolgenparameter, die denselben Namen haben. Mehrwertige Header sowie einwertige Header und Parameter können in denselben Anforderungen und Antworten kombiniert werden. Weitere Informationen finden Sie unter Eingabeformat einer Lambda-Funktion für Proxy-Integration und Ausgabeformat einer Lambda-Funktion für Proxy-Integration.

Einrichten der Proxy-Integration mit einer LambdaProxy-Ressource

Erstellen Sie zum Einrichten einer Proxy-Ressource mit dem Lambda-Proxy-Integrationstyp eine API-Ressource mit einem Greedy-Pfadparameter (z. B. /parent/{proxy+}) und integrieren Sie diese Ressource mit einem Lambda-Funktions-Backend (z. B. arn:aws:lambda:us-west-2:123456789012:function:SimpleLambda4ProxyResource) für die Methode ANY. Der Greedy-Pfadparameter muss am Ende des API-Ressourcenpfads stehen. Genau wie eine Nicht-Proxy-Ressource können Sie auch die Proxy-Ressource einrichten, indem Sie die API Gateway-Konsole verwenden, eine OpenAPI-Definitionsdatei importieren oder die API Gateway-REST-API direkt aufrufen.

Die folgende OpenAPI-API-Definitionsdatei zeigt ein Beispiel für eine API mit einer Proxyressource, die mit der Lambda-Funktion SimpleLambda4ProxyResource integriert wird.

OpenAPI 3.0OpenAPI 2.0
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" } } } } }

Mit der Lambda-Proxyintegration weist API Gateway zur Laufzeit dem Eingabeparameter event der Lambda-Funktion eine eingehende Anforderung zu. Die Eingabe umfasst die Anforderungsmethode, den Pfad, Header, jegliche Zeichenparameter, jegliche Nutzlast, zugehörigen Kontext und alle definierten Stufenvariablen. Eine Beschreibung des Eingabeformats finden Sie unter Eingabeformat einer Lambda-Funktion für Proxy-Integration. Damit API Gateway die Lambda-Ausgabe erfolgreich HTTP-Antworten zuweisen kann, muss die Lambda-Funktion das Ergebnis in dem unter beschriebenen Format Ausgabeformat einer Lambda-Funktion für Proxy-Integrationausgeben.

Bei der Lambda-Proxyintegration einer Proxyressource über die Methode ANY dient die einzelne Backend-Lambda-Funktion als Ereignishandler für alle Anforderungen über die Proxyressource. Beispielsweise können Sie zum Protokollieren der Datenverkehrsmuster ein Mobilgerät veranlassen, seinen Standort mit Angaben zu Bundesland, Stadt, Straße und Gebäude zu senden, indem Sie eine Anforderung mit /state/city/street/house im URL-Pfad für die Proxy-Ressource übermitteln. Die Backend-Lambda-Funktion kann dann den URL-Pfad analysieren und die Standort-Tupel in eine DynamoDB-Tabelle einfügen.

Einrichten von Lambda-Proxy-Integrationen mithilfe der AWS CLI

In diesem Abschnitt zeigen wir, wie Sie mit AWS CLI eine API mit der Lambda-Proxy-Integration einrichten.

Anmerkung

Detaillierte Anweisungen zum Verwenden der API Gateway-Konsole zur Konfiguration einer Proxy-Ressource mit der Lambda-Proxy-Integration finden Sie unter TUTORIAL: Erstellen einer Hello World-API mit Lambda-Proxy-Integration.

Beispielsweise verwenden wir die folgende Lambda-Beispielfunktion als Backend der API-Funktion:

exports.handler = function(event, context, callback) { 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 + "!"; callback(null, res); };

Im Vergleich mit der benutzerdefinierten Einrichtung der Lambda-Integration kann die Eingabe an diese Lambda-Funktion in den Parametern und im Textkörper der Anforderungen angegeben werden. Sie haben mehr Spielraum, um dem Client die Weitergabe der gleichen Eingabedaten zu ermöglichen. Hier kann der Client den Namen von "greeter" als Abfragezeichenfolgeparameter, Kopfzeile oder Texteigenschaft übergeben. Die Funktion unterstützt auch die benutzerdefinierte Lambda-Integration. Die API-Einrichtung ist einfacher. Sie müssen keine Methoden- oder Integrationsantwort konfigurieren.

Einrichten einer Lambda-Proxy-Integration mithilfe der AWS CLI

  1. Rufen Sie den Befehl create-rest-api auf, um eine API zu erstellen:

    aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)' --region us-west-2

    Notieren Sie den in der Antwort für die API-id angegebenen Wert (te6si5ach7).

    { "name": "HelloWorldProxy (AWS CLI)", "id": "te6si5ach7", "createdDate": 1508461860 }

    Sie benötigen die API-id in diesem Abschnitt.

  2. Rufen Sie den Befehl get-resources auf, um die id der Stammressource zu ermitteln.

    aws apigateway get-resources --rest-api-id te6si5ach7 --region us-west-2

    Die erfolgreiche Antwort wird wie folgt angezeigt:

    { "items": [ { "path": "/", "id": "krznpq9xpg" } ] }

    Notieren Sie den id-Wert (krznpq9xpg) der Ressource. Sie benötigen diese in den nächsten Schritten.

  3. Rufen Sie create-resource zum Erstellen der API Gateway-Ressource /greeting auf:

    aws apigateway create-resource --rest-api-id te6si5ach7 \ --region us-west-2 \ --parent-id krznpq9xpg \ --path-part {proxy+}

    Eine erfolgreiche Antwort ähnelt dem folgenden Beispiel:

    { "path": "/{proxy+}", "pathPart": "{proxy+}", "id": "2jf6xt", "parentId": "krznpq9xpg" }

    Notieren Sie den ausgegebenen {proxy+}-Wert (id) der 2jf6xt-Ressource. Sie benötigen die ID, um im nächsten Schritt eine Methode auf der /{proxy+}-Ressource zu erstellen.

  4. Rufen Sie put-method zum Erstellen einer ANY-Methodenanforderung ANY /{proxy+} auf:

    aws apigateway put-method --rest-api-id te6si5ach7 \ --region us-west-2 \ --resource-id 2jf6xt \ --http-method ANY \ --authorization-type "NONE"

    Eine erfolgreiche Antwort ähnelt dem folgenden Beispiel:

    { "apiKeyRequired": false, "httpMethod": "ANY", "authorizationType": "NONE" }

    Diese API-Methode gestattet dem Client, Grüße über die Lambda-Funktion am Backend zu empfangen oder zu senden.

  5. Rufen Sie put-integration auf, um die Integration der ANY /{proxy+}-Methode mit der Lambda-Funktion HelloWorld einzurichten. Diese Funktion beantwortet die Anforderung mit der Nachricht "Hello, {name}!", sofern der greeter-Parameter angegeben wurde, oder "Hello, World!", wenn kein Abfragezeichenfolgeparameter festgelegt wurde.

    aws apigateway put-integration \ --region us-west-2 --rest-api-id vaz7da96z6 \ --resource-id 2jf6xt \ --http-method ANY \ --type AWS_PROXY \ --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 \ --credentials arn:aws:iam::123456789012:role/apigAwsProxyRole

    Wichtig

    Für Lambda-Integrationen müssen Sie die HTTP-Methode POST für die Integrationsanforderung verwenden, entsprechend der -Spezifikation der Lambda-Service-Aktion für Funktionsaufrufe. Die IAM-Rolle der apigAwsProxyRole muss über Richtlinien verfügen, die dem apigateway-Service den Aufruf von Lambda-Funktionen gestattet. Weitere Informationen zu IAM-Berechtigungen finden Sie unter API Gateway-Berechtigungsmodell zum Aufrufen einer API.

    Im Erfolgsfall sieht die Ausgabe folgendermaßen oder ähnlich aus:

    { "passthroughBehavior": "WHEN_NO_MATCH", "cacheKeyParameters": [], "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:1234567890:function:HelloWorld/invocations", "httpMethod": "POST", "cacheNamespace": "vvom7n", "credentials": "arn:aws:iam::1234567890:role/apigAwsProxyRole", "type": "AWS_PROXY" }

    Anstatt eine IAM-Rolle für credentials bereitzustellen, können Sie den Befehl add-permission aufrufen, um ressourcenbasierte Berechtigungen hinzuzufügen. Genau das macht die API Gateway-Konsole.

  6. Rufen Sie create-deployment auf, um die API für eine test-Stufe bereitzustellen:

    aws apigateway create-deployment --rest-api-id te6si5ach7 --stage-name test
  7. Testen Sie die API mithilfe der folgenden cURL-Befehle in einem Terminal.

    API-Aufruf mit dem Abfragezeichenfolgeparameter ?greeter=jane:

    curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=jane' \ -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'

    API-Aufruf mit einem Header-Parameter greeter:jane:

    curl -X GET https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \ -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' \ -H 'content-type: application/json' \ -H 'greeter: jane'

    API-Aufruf mit einem Textkörper-Parameter {"greeter":"jane"}:

    curl -X POST https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test \ -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' -H 'content-type: application/json' \ -d '{ "greeter": "jane" }'

    In allen Fällen ist die Ausgabe eine Antwort mit dem folgenden Antworttext: 200

    Hello, jane!

Eingabeformat einer Lambda-Funktion für Proxy-Integration

Bei der Lambda-Proxyintegration, weist API Gateway die gesamte Clientanforderung wie folgt dem Eingabeparamater event der Backend-Lambda-Funktion zu:

{ "resource": "Resource path", "path": "Path parameter", "httpMethod": "Incoming request's method name" "headers": {String containing incoming request headers} "multiValueHeaders": {List of strings containing incoming request headers} "queryStringParameters": {query string parameters } "multiValueQueryStringParameters": {List of query string parameters} "pathParameters": {path parameters} "stageVariables": {Applicable stage variables} "requestContext": {Request context, including authorizer-returned key-value pairs} "body": "A JSON string of the request payload." "isBase64Encoded": "A boolean flag to indicate if the applicable request payload is Base64-encode" }

Anmerkung

Wählen Sie im Bereich

  • Der headersSchlüssel kann nur einwertige Header enthalten

  • Der multiValueHeadersSchlüssel kann mehrwertige Header sowie einwertige Header enthalten.

  • Wenn Sie Werte für headers und multiValueHeaders angeben, werden diese von API Gateway in eine einzelne Liste zusammengeführt. Wenn in beiden das gleiche Schlüssel / Wert-Paar angegeben ist, werden nur die Werte von in der multiValueHeaderszusammengeführten Liste angezeigt.

Es folgt eine Veranschaulichung mithilfe der folgenden POST-Anforderung, die eine API zeigt, die für testStage mit der Stufenvariable stageVariableName=stageVariableValue bereitgestellt wurde:

POST /testStage/hello/world?name=me HTTP/1.1 Host: gy415nuibc.execute-api.us-east-1.amazonaws.com Content-Type: application/json headerName: headerValue { "a": 1 }

Diese Anforderung erzeugt die folgende Antwortnutzlast, die die von der Lambda-Backend-Funktion zurückgegebene Ausgabe enthält, wobei input auf den Parameter event der Lambda-Funktion festgelegt wurde.

{ "message": "Hello me!", "input": { "resource": "/{proxy+}", "path": "/hello/world", "httpMethod": "POST", "headers": { "Accept": "*/*", "Accept-Encoding": "gzip, deflate", "cache-control": "no-cache", "CloudFront-Forwarded-Proto": "https", "CloudFront-Is-Desktop-Viewer": "true", "CloudFront-Is-Mobile-Viewer": "false", "CloudFront-Is-SmartTV-Viewer": "false", "CloudFront-Is-Tablet-Viewer": "false", "CloudFront-Viewer-Country": "US", "Content-Type": "application/json", "headerName": "headerValue", "Host": "gy415nuibc.execute-api.us-east-1.amazonaws.com", "Postman-Token": "9f583ef0-ed83-4a38-aef3-eb9ce3f7a57f", "User-Agent": "PostmanRuntime/2.4.5", "Via": "1.1 d98420743a69852491bbdea73f7680bd.cloudfront.net (CloudFront)", "X-Amz-Cf-Id": "pn-PWIJc6thYnZm5P0NMgOUglL1DYtl0gdeJky8tqsg8iS_sgsKD1A==", "X-Forwarded-For": "54.240.196.186, 54.182.214.83", "X-Forwarded-Port": "443", "X-Forwarded-Proto": "https" }, "multiValueHeaders":{ 'Accept':[ "*/*" ], 'Accept-Encoding':[ "gzip, deflate" ], 'cache-control':[ "no-cache" ], 'CloudFront-Forwarded-Proto':[ "https" ], 'CloudFront-Is-Desktop-Viewer':[ "true" ], 'CloudFront-Is-Mobile-Viewer':[ "false" ], 'CloudFront-Is-SmartTV-Viewer':[ "false" ], 'CloudFront-Is-Tablet-Viewer':[ "false" ], 'CloudFront-Viewer-Country':[ "US" ], '':[ "" ], 'Content-Type':[ "application/json" ], 'headerName':[ "headerValue" ], 'Host':[ "gy415nuibc.execute-api.us-east-1.amazonaws.com" ], 'Postman-Token':[ "9f583ef0-ed83-4a38-aef3-eb9ce3f7a57f" ], 'User-Agent':[ "PostmanRuntime/2.4.5" ], 'Via':[ "1.1 d98420743a69852491bbdea73f7680bd.cloudfront.net (CloudFront)" ], 'X-Amz-Cf-Id':[ "pn-PWIJc6thYnZm5P0NMgOUglL1DYtl0gdeJky8tqsg8iS_sgsKD1A==" ], 'X-Forwarded-For':[ "54.240.196.186, 54.182.214.83" ], 'X-Forwarded-Port':[ "443" ], 'X-Forwarded-Proto':[ "https" ] }, "queryStringParameters": { "name": "me", "multivalueName": "me" }, "multiValueQueryStringParameters":{ "name":[ "me" ], "multivalueName":[ "you", "me" ] }, "pathParameters": { "proxy": "hello/world" }, "stageVariables": { "stageVariableName": "stageVariableValue" }, "requestContext": { "accountId": "12345678912", "resourceId": "roq9wj", "stage": "testStage", "requestId": "deef4878-7910-11e6-8f14-25afc3e9ae33", "identity": { "cognitoIdentityPoolId": null, "accountId": null, "cognitoIdentityId": null, "caller": null, "apiKey": null, "sourceIp": "192.168.196.186", "cognitoAuthenticationType": null, "cognitoAuthenticationProvider": null, "userArn": null, "userAgent": "PostmanRuntime/2.4.5", "user": null }, "resourcePath": "/{proxy+}", "httpMethod": "POST", "apiId": "gy415nuibc" }, "body": "{\r\n\t\"a\": 1\r\n}", "isBase64Encoded": false } }

In der Eingabe für die Lambda-Funktion im Backend ist das requestContext-Objekt eine Zuordnung von Schlüssel-Wert-Paaren. In jedem Paar ist der Schlüssel der Name einer $context-Variableneigenschaft, und der Wert ist der Wert dieser Eigenschaft. API Gateway kann der Zuweisung neue Schlüssel hinzufügen.

Abhängig von den aktivierten Funktionen kann die Zuweisung requestContext von API zu API unterschiedlich sein. Im obigen Beispiel ist z. B. kein Autorisierungstyp angegeben, sodass keine $context.authorizer.*- oder $context.identity.*-Eigenschaften vorhanden sind. Wenn ein Autorisierungstyp angegeben ist, gibt API Gateway autorisierte Benutzerinformationen an den Integrationsendpunkt in einem requestContext.identity-Objekt weiter, und zwar folgendermaßen:

  • Wenn der Autorisierungstyp AWS_IAM ist, enthalten die autorisierten Benutzerinformationen $context.identity.*-Eigenschaften.

  • Wenn der Autorisierungstyp COGNITO_USER_POOLS (Amazon Cognito-Genehmiger) ist, enthalten die autorisierten Benutzerinformationen $context.identity.cognito*- und $context.authorizer.claims.*-Eigenschaften.

  • Wenn der Autorisierungstyp CUSTOM (Lambda-Genehmiger) ist, enthalten die autorisierten Benutzerinformationen $context.authorizer.principalId- und andere relevante $context.authorizer.*-Eigenschaften.

Im Folgenden wird ein Beispiel für die Übergabe von requestContext an einen Lambda-Proxy-Integrationsendpunkt gezeigt, wenn der Autorisierungstyp auf AWS_IAMfestgelegt ist.

{ ..., "requestContext": { "requestTime": "20/Feb/2018:22:48:57 +0000", "path": "/test/", "accountId": "123456789012", "protocol": "HTTP/1.1", "resourceId": "yx5mhem7ye", "stage": "test", "requestTimeEpoch": 1519166937665, "requestId": "3c3ecbaa-1690-11e8-ae31-8f39f1d24afd", "identity": { "cognitoIdentityPoolId": null, "accountId": "123456789012", "cognitoIdentityId": null, "caller": "AIDAJ........4HCKVJZG", "sourceIp": "51.240.196.104", "accessKey": "IAM_user_access_key", "cognitoAuthenticationType": null, "cognitoAuthenticationProvider": null, "userArn": "arn:aws:iam::123456789012:user/alice", "userAgent": "PostmanRuntime/7.1.1", "user": "AIDAJ........4HCKVJZG" }, "resourcePath": "/", "httpMethod": "GET", "apiId": "qr2gd9cfmf" }, ... }

Ausgabeformat einer Lambda-Funktion für Proxy-Integration

Bei der Lambda-Proxyintegration ist in API Gateway die Backend-Lambda-Funktion erforderlich, um Ausgaben gemäß dem folgenden JSON-Format zurückzugeben:

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

In der Konsolenausgabe:

  • Die Schlüssel headers und multiValueHeaders können nicht angegeben werden, wenn keine zusätzlichen Antwortheader zurückgegeben werden sollen.

  • Der headersSchlüssel kann nur einwertige Header enthalten

  • Der multiValueHeadersSchlüssel kann mehrwertige Header sowie einwertige Header enthalten. Sie können den multiValueHeadersSchlüssel verwenden, um alle zusätzlichen Header anzugeben, einschließlich einzelner Werte.

  • Wenn Sie Werte für headers und multiValueHeaders angeben, werden diese von API Gateway in eine einzelne Liste zusammengeführt. Wenn in beiden das gleiche Schlüssel / Wert-Paar angegeben ist, werden nur die Werte von in der multiValueHeaderszusammengeführten Liste angezeigt.

Zum Aktivieren von CORS für die Lambda-Proxy-Integration müssen Sie Access-Control-Allow-Origin:domain-name zur Ausgabe headers hinzufügen.domain-name kann für jeden *Domainnamen sein. Die Ausgabe body wird als Nutzlast der Methodenanforderung an das Frontend angeordnet Wenn body ein binärer Blob ist, können Sie ihn als Base64-kodierte Zeichenfolge codieren, indem Sie isBase64Encoded auf true festlegen und */* als Binary Media Type (Binärer Medientyp) konfigurieren. Andernfalls können Sie den Wert auf false festlegen oder keinen Wert angeben.

Anmerkung

Weitere Informationen zur Aktivierung der Unterstützung von Binärdateien finden Sie unter Aktivieren der Binärunterstützung in der API Gateway-Konsole.

Wenn die Funktionsausgabe ein anderes Format hat, gibt API Gateway eine Fehlerantwort 502 Bad Gateway zurück.

Um die Antwort einer Lambda-Funktion in Node.js zurückzugeben, können Sie Befehle wie die folgenden verwenden:

  • Um ein erfolgreiches Ergebnis zurückzugeben, rufen Sie callback(null, {"statusCode": 200, "body": "results"}) auf.

  • Rufen Sie zum Auslösen einer Ausnahme callback(new Error('internal server error')) auf.

  • Bei einem Fehler auf Clientseite, z. B. wenn ein erforderlicher Parameter fehlt, können Sie callback(null, {"statusCode": 400, "body": "Missing parameters of ..."}) aufrufen, um den Fehler zurückzugeben, ohne eine Ausnahme auszulösen.

In der Lambda-Funktion async in Node.js 8.10 würde die entsprechende Syntax verwendet werden:

  • Um ein erfolgreiches Ergebnis zurückzugeben, rufen Sie return {"statusCode": 200, "body": "results"} auf.

  • Rufen Sie zum Auslösen einer Ausnahme throw new Error("internal server error") auf.

  • Bei einem Fehler auf Clientseite, z. B. wenn ein erforderlicher Parameter fehlt, können Sie return {"statusCode": 400, "body": "Missing parameters of ..."} aufrufen, um den Fehler zurückzugeben, ohne eine Ausnahme auszulösen.