Verwenden von AWS Lambda mit Amazon API Gateway - AWS Lambda

Verwenden von AWS Lambda mit Amazon API Gateway

Sie können eine Web-API mit einem HTTP-Endpunkt für Ihre Lambda Funktion erstellen, indem Sie Amazon API Gateway verwenden. API Gateway bietet Tools zum Erstellen und Dokumentieren von Web-APIs, die HTTP-Anforderungen an Lambda-Funktionen weiterleiten. Sie können den Zugriff auf Ihre API mit Authentifizierungs- und Autorisierungskontrollen sichern. Ihre APIs können Datenverkehr über das Internet bereitstellen oder nur innerhalb Ihrer VPC zugänglich sein.

Ressourcen in Ihrer API definieren mindestens eine Methode, z. B. GET oder POST. Methoden haben eine Integration, die Anfragen an eine Lambda-Funktion oder einen anderen Integrationstyp weiterleitet. Sie können jede Ressource und jede Methode einzeln definieren oder spezielle Ressourcen- und Methodenarten verwenden, um alle Anforderungen abzugleichen, die einem Muster entsprechen. Eine Proxy-Ressource fängt alle Pfade unter einer Ressource ab. Die ANY-Methode fängt alle HTTP-Methoden ab.

Hinzufügen eines Endpunkts zur Lambda-Funktion

So fügen Sie Ihrer Lambda-Funktion einen öffentlichen Endpunkt hinzu
  1. Öffnen Sie die Seite Funktionen der Lambda-Konsole.

  2. Wählen Sie eine Funktion aus.

  3. Wählen Sie unter Function overview (Funktionsübersicht) die Option Add trigger (Trigger hinzufügen).

  4. Wählen Sie API Gateway aus.

  5. Wählen Sie Create an API (API erstellen) oder Use an existing API (Vorhandene API verwenden).

    1. Neue API: Wählen Sie als API type (API-Typ) HTTP API aus. Weitere Informationen finden Sie unter API-Typen.

    2. Vorhandene API: Wählen Sie die API aus dem Dropdown-Menü aus oder geben Sie die API-ID ein (z. B. r3pmxmplak).

  6. Wählen Sie unter Security (Sicherheit) die Option Open (Öffnen) aus.

  7. Wählen Sie Add aus.

Proxy-Integration

API-Gateway-APIs bestehen aus Phasen, Ressourcen, Methoden und Integrationen. Die Phase und die Ressource bestimmen den Pfad des Endpunkts:

API-Pfadformat
  • /prod/ – Die prod-Phase und die Root-Ressource.

  • /prod/user – Die prod-Phase und die user-Ressource.

  • /dev/{proxy+} – Jede Route in der dev-Phase.

  • / – (HTTP-APIs) Die Standardphase und die Root-Ressource.

Eine Lambda-Integration ordnet einer Lambda-Funktion eine Pfad- und HTTP-Methodenkombination zu. Sie können API Gateway so konfigurieren, dass der Hauptteil der HTTP-Anforderung unverändert (benutzerdefinierte Integration) übergeben oder der Anforderungstext in einem Dokument mit allen Anforderungsinformationen, einschließlich Header, Ressource, Pfad und Methode, gekapselt wird.

Ereignisformat

Amazon API Gateway ruft Ihre Funktion synchron mit einem Ereignis auf, das eine JSON-Darstellung der HTTP-Anforderung enthält. Bei einer benutzerdefinierten Integration ist das Ereignis der Text der Anforderung. Bei einer Proxy-Integration hat das Ereignis eine definierte Struktur. Das folgende Beispiel zeigt ein Proxy-Ereignis aus einer API-Gateway-REST-API.

Beispiel event.json API-Gateway-Proxy-Ereignis (REST-API)
{ "resource": "/", "path": "/", "httpMethod": "GET", "requestContext": { "resourcePath": "/", "httpMethod": "GET", "path": "/Prod/", ... }, "headers": { "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "accept-encoding": "gzip, deflate, br", "Host": "70ixmpl4fl.execute-api.us-east-2.amazonaws.com", "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.132 Safari/537.36", "X-Amzn-Trace-Id": "Root=1-5e66d96f-7491f09xmpl79d18acf3d050", ... }, "multiValueHeaders": { "accept": [ "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9" ], "accept-encoding": [ "gzip, deflate, br" ], ... }, "queryStringParameters": null, "multiValueQueryStringParameters": null, "pathParameters": null, "stageVariables": null, "body": null, "isBase64Encoded": false }

Reaktionsformat

API Gateway wartet auf eine Antwort von Ihrer Funktion und leitet das Ergebnis an den Aufrufer weiter. Für eine benutzerdefinierte Integration definieren Sie eine Integrationsantwort und eine Methodenantwort, um die Ausgabe von der Funktion in eine HTTP-Antwort zu konvertieren. Für eine Proxy-Integration muss die Funktion mit einer Darstellung der Antwort in einem bestimmten Format antworten.

Das folgende Beispiel zeigt ein Antwortobjekt aus einer Node.js-Funktion. Das Antwortobjekt stellt eine erfolgreiche HTTP-Antwort dar, die ein JSON-Dokument enthält.

Beispiel index.js – Antwortobjekt der Proxy-Integration (Node.js)
var response = { "statusCode": 200, "headers": { "Content-Type": "application/json" }, "isBase64Encoded": false, "multiValueHeaders": { "X-Custom-Header": ["My value", "My other value"], }, "body": "{\n \"TotalCodeSize\": 104330022,\n \"FunctionCount\": 26\n}" }

Die Lambda-Laufzeit serialisiert das Antwortobjekt in JSON und sendet es an die API. Die API analysiert die Antwort und verwendet sie zur Erstellung einer HTTP-Antwort verwendet, die sie dann an den Client sendet, der die ursprüngliche Anforderung gestellt hat.

Beispiel HTTP-Antwort
< HTTP/1.1 200 OK < Content-Type: application/json < Content-Length: 55 < Connection: keep-alive < x-amzn-RequestId: 32998fea-xmpl-4268-8c72-16138d629356 < X-Custom-Header: My value < X-Custom-Header: My other value < X-Amzn-Trace-Id: Root=1-5e6aa925-ccecxmplbae116148e52f036 < { "TotalCodeSize": 104330022, "FunctionCount": 26 }

Berechtigungen

Amazon API Gateway erhält die Berechtigung zum Aufrufen Ihrer Funktion über die ressourcenbasierte Richtlinie der Funktion. Sie können eine Aufrufberechtigung für eine gesamte API erteilen oder einen eingeschränkten Zugriff auf eine Phase, eine Ressource oder eine Methode gewähren.

Wenn Sie Ihrer Funktion mithilfe der Lambda-Konsole, mithilfe der API-Gateway-Konsole oder in einer AWS SAM-Vorlage eine API hinzufügen, wird die ressourcenbasierte Richtlinie der Funktion automatisch aktualisiert. Es folgt eine Beispiel-Funktionsrichtlinie.

Beispiel Funktionsrichtlinie
{ "Version": "2012-10-17", "Id": "default", "Statement": [ { "Sid": "nodejs-apig-functiongetEndpointPermissionProd-BWDBXMPLXE2F", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "lambda:InvokeFunction", "Resource": "arn:aws:lambda:us-east-2:111122223333:function:nodejs-apig-function-1G3MXMPLXVXYI", "Condition": { "StringEquals": { "aws:SourceAccount": "111122223333" }, "ArnLike": { "aws:SourceArn": "arn:aws:execute-api:us-east-2:111122223333:ktyvxmpls1/*/GET/" } } } ] }

Sie können Funktionsrichtlinienberechtigungen manuell mit den folgenden API-Operationen verwalten:

Mit dem add-permission-Befehl können Sie einer vorhandenen API Aufrufberechtigung erteilen.

aws lambda add-permission --function-name my-function \ --statement-id apigateway-get --action lambda:InvokeFunction \ --principal apigateway.amazonaws.com \ --source-arn "arn:aws:execute-api:us-east-2:123456789012:mnh1xmpli7/default/GET/"

Die Ausgabe sollte folgendermaßen aussehen:

{ "Statement": "{\"Sid\":\"apigateway-test-2\",\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"apigateway.amazonaws.com\"},\"Action\":\"lambda:InvokeFunction\",\"Resource\":\"arn:aws:lambda:us-east-2:123456789012:function:my-function\",\"Condition\":{\"ArnLike\":{\"AWS:SourceArn\":\"arn:aws:execute-api:us-east-2:123456789012:mnh1xmpli7/default/GET\"}}}" }
Anmerkung

Wenn sich Ihre Funktion und Ihre API in unterschiedlichen Regionen befinden, muss die Regions-ID im Quell-ARN mit der Region der Funktion, nicht mit der Region der API übereinstimmen. Bei Aufruf einer API-Gateway-Funktion verwendet diese einen Ressourcen-ARN, der auf dem ARN der API basiert, aber so geändert wird, dass er dem Bereich der Funktion entspricht.

Der Quell-ARN in diesem Beispiel erteilt eine Berechtigung für eine Integration in die GET-Methode der Root-Ressource in der Standardphase einer API mit ID mnh1xmpli7. Sie können ein Sternchen im Quell-ARN verwenden, um Berechtigungen für mehrere Phasen, Methoden oder Ressourcen zu erteilen.

Ressourcenmuster
  • mnh1xmpli7/*/GET/* – GET-Methode bei allen Ressourcen in allen Phasen.

  • mnh1xmpli7/prod/ANY/user – JEDE Methode bei der user-Ressource in der prod-Phase.

  • mnh1xmpli7/*/*/* – Jede Methode bei allen Ressourcen in allen Phasen.

Weitere Informationen zum Anzeigen der Richtlinie und zum Entfernen von Anweisungen finden Sie unter Bereinigen von ressourcenbasierten Richtlinien.

Fehlerbehandlung mit einer API-Gateway-API

API Gateway behandelt alle Aufruf- und Funktionsfehler als interne Fehler. Wenn die Lambda-API die Aufruf-Anforderung ablehnt, gibt API Gateway einen 500-Fehlercode zurück. Wenn die Funktion ausgeführt wird, aber einen Fehler oder eine Antwort im falschen Format zurückgibt, gibt API Gateway den Fehlercode 502 zurück. In beiden Fällen lautet der Text der Antwort von API Gateway „{"message": "Internal server error"}“.

Anmerkung

API Gateway wiederholt keine Lambda-Aufrufe. Wenn Lambda einen Fehler zurückgibt, gibt API Gateway eine Fehlerantwort an den Client zurück.

Das folgende Beispiel zeigt eine X-Ray-Ablaufverfolgungszuordnung für eine Anforderung, die zu einem Funktionsfehler und einen 502-Fehler von API Gateway führte. Der Client erhält die generische Fehlermeldung.


        Ablaufverflogungszuweisung für einen Funktionsfehler mit API Gateway.

Um die Fehlerantwort anzupassen, müssen Sie Fehler im Code abfangen und eine Antwort im erforderlichen Format formatieren.

Beispiel index.js – Formatierfehler
var formatError = function(error){ var response = { "statusCode": error.statusCode, "headers": { "Content-Type": "text/plain", "x-amzn-ErrorType": error.code }, "isBase64Encoded": false, "body": error.code + ": " + error.message } return response }

API Gateway konvertiert diese Antwort in einen HTTP-Fehler mit einem benutzerdefinierten Statuscode und Text. In der Ablaufverfolgungszuweisung ist der Funktionsknoten grün, da er den Fehler behandelt hat.


        Ablaufverfolgungszuweisung für einen formatierten Fehler mit API Gateway.

Auswählen eines API-Typs

API Gateway unterstützt drei Arten von APIs, die Lambda-Funktionen aufrufen:

  • HTTP API – eine leichte RESTful-API mit geringer Latenz.

  • REST-API – eine anpassbare, funktionsreiche RESTful-API.

  • WebSocket-API – eine Web-API, die persistente Verbindungen mit Clients für die Vollduplex-Kommunikation unterhält.

HTTP-APIs und REST-APIs sind beides RESTful-APIs, die HTTP-Anforderungen verarbeiten und Antworten zurückgeben. HTTP-APIs sind neuer und werden mit der API der API-Gateway-Version 2 erstellt. Die folgenden Funktionen sind neu bei HTTP-APIs:

HTTP-API-Funktionen
  • Automatische Bereitstellungen – wenn Sie Routen oder Integrationen ändern, werden Änderungen automatisch in Phasen bereitgestellt, bei denen die automatische Bereitstellung aktiviert ist.

  • Standardphase – Sie können eine Standardphase ($default) erstellen, um Anforderungen am Stammpfad der URL Ihrer API zu bedienen. Bei benannten Phasen müssen Sie den Schrittnamen am Anfang des Pfades angeben.

  • CORS-Konfiguration – Sie können Ihre API so konfigurieren, dass ausgehenden Antworten CORS-Header hinzugefügt werden, anstatt sie manuell in Ihrem Funktionscode hinzufügen zu müssen.

REST-APIs sind die klassischen RESTful-APIs, die von API Gateway seit dem Start unterstützt wurden. REST-APIs verfügen derzeit über mehr Anpassungs-, Integrations- und Verwaltungsfunktionen.

REST-API-Funktionen
  • Integrationstypen – REST-APIs unterstützen benutzerdefinierte Lambda-Integrationen. Mit einer benutzerdefinierten Integration können Sie nur den Text der Anforderung an die Funktion senden oder eine Transformationsvorlage auf den Anforderungstext anwenden, bevor Sie sie an die Funktion senden.

  • Zugriffskontrolle – REST-APIs unterstützen weitere Optionen für die Authentifizierung und Autorisierung.

  • Überwachung und Ablaufverfolgung – REST-APIs unterstützen AWS X-Ray-Ablaufverfolgung und zusätzliche Protokollierungsoptionen.

Einen detaillierten Vergleich finden Sie unter Auswählen zwischen HTTP-APIs und REST-APIs im API-Gateway-Entwicklerhandbuch.

WebSocket-APIs verwenden auch die API der API-Gateway-Version 2 und unterstützen einen ähnlichen Funktionssatz. Verwenden Sie eine WebSocket-API für Anwendungen, die von einer persistenten Verbindung zwischen Client und API profitieren. WebSocket-APIs bieten Vollduplex-Kommunikation. Das bedeutet, dass sowohl der Client als auch die API Nachrichten kontinuierlich senden können, ohne auf eine Antwort warten zu müssen.

HTTP-APIs unterstützen ein vereinfachtes Ereignisformat (Version 2.0). Das folgende Beispiel zeigt ein Ereignis aus einer HTTP-API.

Beispiel event-v2.json API-Gateway-Proxy-Ereignis (HTTP-API)
{ "version": "2.0", "routeKey": "ANY /nodejs-apig-function-1G3XMPLZXVXYI", "rawPath": "/default/nodejs-apig-function-1G3XMPLZXVXYI", "rawQueryString": "", "cookies": [ "s_fid=7AABXMPL1AFD9BBF-0643XMPL09956DE2", "regStatus=pre-register" ], "headers": { "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9", "accept-encoding": "gzip, deflate, br", ... }, "requestContext": { "accountId": "123456789012", "apiId": "r3pmxmplak", "domainName": "r3pmxmplak.execute-api.us-east-2.amazonaws.com", "domainPrefix": "r3pmxmplak", "http": { "method": "GET", "path": "/default/nodejs-apig-function-1G3XMPLZXVXYI", "protocol": "HTTP/1.1", "sourceIp": "205.255.255.176", "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.132 Safari/537.36" }, "requestId": "JKJaXmPLvHcESHA=", "routeKey": "ANY /nodejs-apig-function-1G3XMPLZXVXYI", "stage": "default", "time": "10/Mar/2020:05:16:23 +0000", "timeEpoch": 1583817383220 }, "isBase64Encoded": true }

Weitere Informationen finden Sie unter AWS Lambda-Integrationen im API Gateway-Entwicklerhandbuch.

Beispielanwendungen

Das GitHub-Repository für dieses Handbuch enthält die folgende Beispielanwendung für API-Gateway.

  • API-Gateway mit Node.js – Eine Funktion mit einer AWS SAM-Vorlage, die eine REST-API erstellt, für die AWS X-Ray-Protokollierung aktiviert ist. Es enthält Skripte zum Bereitstellen und Aufrufen der Funktion sowie zum Testen der API und zum Bereinigen.

Lambda stellt außerdem Baupläne und Vorlagen bereit, mit denen Sie eine API-Gateway-Anwendung in der Lambda-Konsole erstellen können.