Amazon API Gateway
Entwicklerhandbuch

TUTORIAL: Erstellen einer Hello World-API mit Lambda-Proxy-Integration

Lambda-Proxy-Integration ist ein leichter, flexibler API Gateway-API-Integrationstyp, mit dem Sie eine API-Methode – oder eine gesamte API – mit einer Lambda-Funktion integrieren können. Die Lambda-Funktion kann in jeder beliebigen - Programmiersprache geschrieben werden, die Lambda unterstützt. Da es sich um eine Proxy-Integration handelt, können Sie die Implementierung der Lambda-Funktion jederzeit ändern, ohne Ihre API erneut bereitstellen zu müssen.

In diesem Tutorial führen Sie folgende Aufgaben aus:

  • Erstellen Sie eine "Hello, World!"-Lambda-Funktion als Backend für die API.

  • Erstellen und testen Sie eine "Hello, World!"- API mit Lambda-Proxy-Integration.

Erstellen Sie eine "Hello, World!"- Lambda Funktion

Diese Funktion gibt dem Aufrufer eine Antwort als JSON-Objekt im folgenden Format zurück:

{ "greeting": "Good {time}, {name} of {city}.[ Happy {day}!]" }

Erstellen einer "Hello, World!"-Lambda-Funktion in der Lambda-Konsole

  1. Melden Sie sich unter https://console.aws.amazon.com/lambda bei der Lambda-Konsole an.

  2. Wählen Sie in der AWS-Navigationsleiste eine Region (beispielsweise USA Ost (Nord-Virginia)) aus.

    Anmerkung

    Notieren Sie sich die Region, in der Sie die Lambda-Funktion erstellen. Sie benötigen sie zum Erstellen der API.

  3. Wählen Sie im Navigationsbereich Functions (Funktionen) aus.

  4. Wählen Sie Create function.

  5. Wählen Sie Author from scratch aus.

  6. Führen Sie unter Basic information (Grundlegende Informationen) die folgenden Schritte aus:

    1. Geben Sie in Function name (Funktionsname) GetStartedLambdaProxyIntegration ein.

    2. Wählen Sie aus der Dropdown-Liste Runtime (Laufzeit) die Option Node.js 8.10 aus.

    3. Erweitern Sie unter Permissions (Berechtigungen) den Bereich Choose or create an execution role (Ausführungsrolle wählen oder erstellen). Wählen Sie aus der Dropdown-Liste Execution role (Ausführungsrolle) Create new role from AWS policy templates (Neue Rolle aus Vorlage AWS-Richtlinienvorlagen erstellen) aus.

    4. Geben Sie in Role Name (Rollenname) den Namen GetStartedLambdaBasicExecutionRole ein.

    5. Lassen Sie das Feld Policy templates (Richtlinien-Vorlagen) leer.

    6. Wählen Sie Create function.

  7. Fügen Sie im Inline-Code-Editor unter Function code (Funktionscode) den folgenden Code ein:

    'use strict'; console.log('Loading hello world function'); exports.handler = async (event) => { let name = "you"; let city = 'World'; let time = 'day'; let day = ''; let responseCode = 200; console.log("request: " + JSON.stringify(event)); if (event.queryStringParameters && event.queryStringParameters.name) { console.log("Received name: " + event.queryStringParameters.name); name = event.queryStringParameters.name; } if (event.queryStringParameters && event.queryStringParameters.city) { console.log("Received city: " + event.queryStringParameters.city); city = event.queryStringParameters.city; } if (event.headers && event.headers['day']) { console.log("Received day: " + event.headers.day); day = event.headers.day; } if (event.body) { let body = JSON.parse(event.body) if (body.time) time = body.time; } let greeting = `Good ${time}, ${name} of ${city}.`; if (day) greeting += ` Happy ${day}!`; let responseBody = { message: greeting, input: event }; // The output from a Lambda proxy integration must be // in the following JSON object. The 'headers' property // is for custom response headers in addition to standard // ones. The 'body' property must be a JSON string. For // base64-encoded payload, you must also set the 'isBase64Encoded' // property to 'true'. let response = { statusCode: responseCode, headers: { "x-custom-header" : "my custom header value" }, body: JSON.stringify(responseBody) }; console.log("response: " + JSON.stringify(response)) return response; };
  8. Wählen Sie Save aus.

Erstellen Sie eine "Hello, World!"- API

Erstellen Sie nun mithilfe der API Gateway-Konsole eine API für Ihre "Hello, World!"-Lambda-Funktion.

Erstellen einer "Hello, World!"- API

  1. Melden Sie sich unter https://console.aws.amazon.com/apigateway bei der API Gateway-Konsole an.

  2. Wenn Sie API Gateway erstmals verwenden, wird eine Seite mit einer Einführung in die Funktionen des Service angezeigt. Wählen Sie Get Started. Wenn das Popup-Fenster Create Exampe API (Beispiel-API erstellen) angezeigt wird, klicken Sie auf OK.

    Wenn Sie API Gateway nicht erstmalig verwenden, wählen Sie Create API (API erstellen).

  3. Erstellen Sie eine leere API wie folgt:

    1. Wählen Sie unter Choose the protocol (Das Protokoll auswählen) die Option REST aus.

    2. Wählen Sie unter Create new API (Neue API erstellen) die Option New API (Neue API) aus.

    3. Unter Settings (Einstellungen):

      • Geben Sie unter API name (API-Name) LambdaSimpleProxy ein.

      • Geben Sie bei Bedarf eine Beschreibung in das Feld Description (Beschreibung) ein. Andernfalls lassen Sie es leer.

      • Lassen Sie die Einstellungen für Endpoint Type (Endpunkttyp) auf Regional.

    4. Wählen Sie Create API aus.

  4. Erstellen Sie die helloworld-Ressource folgendermaßen:

    1. Wählen Sie eine Root-Ressource (/) in der Struktur Resources (Ressourcen) aus.

    2. Wählen Sie im Dropdown-Menü Actions (Aktionen) die Option Create Resource (Ressource erstellen) aus.

    3. Lassen Sie die Option Configure as proxy resource (Als Proxy-Ressource konfigurieren) deaktiviert.

    4. Geben Sie für Resource Name (Ressourcenname) helloworld ein.

    5. Lassen Sie den Resource Path (Ressourcenpfad) auf /helloworld festgelegt.

    6. Lassen Sie die Option Enable API Gateway CORS (API Gateway CORS aktivieren) deaktiviert.

    7. Wählen Sie Create Resource (Ressource erstellen) aus.

  5. In einer Proxy-Integration wird die gesamte Anforderung unverändert an die Backend-Lambda-Funktion gesendet. Dazu wird eine Catch-All-ANY-Methode verwendet, die eine HTTP-Methode repräsentiert. Der tatsächliche HTTP-Methode wird vom Client zur Laufzeit angegeben. Mit der Methode ANY haben Sie die Möglichkeit, eine einzige API-Methodeneinrichtung für alle unterstützten HTTP-Methoden zu verwenden: DELETE, GET, HEAD, OPTIONS, PATCH, POST und PUT.

    Gehen Sie zum Einrichten der ANY-Methode wie folgt vor:

    1. Wählen Sie in der Liste Resources (Ressourcen) /helloworld aus.

    2. Wählen Sie im Menü Actions (Aktionen) die Option Create Method (Methode erstellen) aus.

    3. Wählen Sie aus dem Dropdown-Menü ANY aus und aktivieren Sie das Häkchen-Symbol

    4. Lassen Sie die Einstellung für Integration type (Integrationstyp) auf Lambda Function (Funktion).

    5. Wählen Sie die Option Use Lambda Proxy integration (Lambda-Proxy-Integration verwenden) aus.

    6. Wählen Sie im Dropdown-Menü Lambda Region (Lambda-Region) die Region aus, in der Sie die GetStartedLambdaProxyIntegration-Lambda-Funktion erstellt haben.

    7. Geben Sie im Feld Lambda Function (-Funktion) ein beliebiges Zeichen ein und wählen Sie GetStartedLambdaProxyIntegration aus dem Drop-Down-Menü aus.

    8. Lassen Sie die Option Use default Timeout aktiviert.

    9. Wählen Sie Save aus.

    10. Klicken Sie auf OK, wenn Sie dazu mit Add Permission to Lambda Function (Berechtigung für Lambda-Funktion hinzufügen) aufgefordert werden.

Bereitstellen und Testen der API

Bereitstellen der API in der API Gateway-Konsole

  1. Wählen Sie im Dropdown-Menü Actions (Aktionen) die Option Deploy API (API bereitstellen) aus.

  2. Wählen Sie für Deployment stage (Bereitstellungsstufe) [new stage] aus.

  3. Geben Sie für Stage name (Stufenname) test ein.

  4. Geben Sie bei Bedarf eine Beschreibung für Stage description (Beschreibung der Stufe) ein.

  5. Geben Sie bei Bedarf eine Beschreibung für Deployment description (Beschreibung der Bereitstellung) ein.

  6. Wählen Sie Deploy (Bereitstellen) aus.

  7. Notieren Sie den Wert Invoke URL (Aufruf-URL) der API.

Verwenden von Browser und cURL zum Testen einer API mit Lambda-Proxy-Integration

Sie können einen Browser oder eine cURL zum Testen Ihrer API verwenden.

Um GET-Anforderungen mit ausschließlich Abfragezeichenfolgeparametern zu testen, können Sie die URL für die helloworld-Ressource der API in eine Adressleiste des Browsers eingeben. Beispiel: https://r275xc9bmd.execute-api.us-east-1.amazonaws.com/test/helloworld?name=John&city=Seattle

Für andere Methoden müssen Sie erweiterte REST-API-Testtools wie POSTMAN oder cURL verwenden. In diesem Tutorial wird cURL verwendet. Bei den cURL-Befehl-Beispielen wird davon ausgegangen, dass cURL auf Ihrem Computer installiert ist.

So testen Sie die bereitgestellte API mithilfe von cURL:

  1. Öffnen Sie ein Terminal-Fenster.

  2. Kopieren Sie den folgenden cURL-Befehl und fügen Sie ihn in das Terminalfenster ein. Ersetzen Sie dabei r275xc9bmd mit der API-ID Ihrer API und us-east-1 mit der Region, in der Ihre API bereitgestellt ist.

    curl -v -X POST \ 'https://r275xc9bmd.execute-api.us-east-1.amazonaws.com/test/helloworld?name=John&city=Seattle' \ -H 'content-type: application/json' \ -H 'day: Thursday' \ -d '{ "time": "evening" }'

    Anmerkung

    Wenn Sie den Befehl unter Windows ausführen, verwenden Sie stattdessen die folgende Syntax:

    curl -v -X POST "https://r275xc9bmd.execute-api.us-east-1.amazonaws.com/test/helloworld?name=John&city=Seattle" -H "content-type: application/json" -H "day: Thursday" -d "{ \"time\": \"evening\" }"

Sie sollten eine positive Antwort mit einer Nutzlast erhalten, die in etwa so aussieht:

{ "message":"Good evening, John of Seattle. Happy Thursday!", "input":{ "resource":"/helloworld", "path":"/helloworld", "httpMethod":"POST", "headers":{"Accept":"*/*", "content-type":"application/json", "day":"Thursday", "Host":"r275xc9bmd.execute-api.us-east-1.amazonaws.com", "User-Agent":"curl/7.64.0", "X-Amzn-Trace-Id":"Root=1-1a2b3c4d-a1b2c3d4e5f6a1b2c3d4e5f6", "X-Forwarded-For":"72.21.198.64", "X-Forwarded-Port":"443", "X-Forwarded-Proto":"https"}, "multiValueHeaders":{"Accept":["*/*"], "content-type":["application/json"], "day":["Thursday"], "Host":["r275xc9bmd.execute-api.us-east-1.amazonaws.com"], "User-Agent":["curl/0.0.0"], "X-Amzn-Trace-Id":["Root=1-1a2b3c4d-a1b2c3d4e5f6a1b2c3d4e5f6"], "X-Forwarded-For":["11.22.333.44"], "X-Forwarded-Port":["443"], "X-Forwarded-Proto":["https"]}, "queryStringParameters":{"city":"Seattle", "name":"John" }, "multiValueQueryStringParameters":{ "city":["Seattle"], "name":["John"] }, "pathParameters":null, "stageVariables":null, "requestContext":{ "resourceId":"3htbry", "resourcePath":"/helloworld", "htt* Connection #0 to host r275xc9bmd.execute-api.us-east-1.amazonaws.com left intact pMethod":"POST", "extendedRequestId":"a1b2c3d4e5f6g7h=", "requestTime":"20/Mar/2019:20:38:30 +0000", "path":"/test/helloworld", "accountId":"123456789012", "protocol":"HTTP/1.1", "stage":"test", "domainPrefix":"r275xc9bmd", "requestTimeEpoch":1553114310423, "requestId":"test-invoke-request", "identity":{"cognitoIdentityPoolId":null, "accountId":null, "cognitoIdentityId":null, "caller":null, "sourceIp":"test-invoke-source-ip", "accessKey":null, "cognitoAuthenticationType":null, "cognitoAuthenticationProvider":null, "userArn":null, "userAgent":"curl/0.0.0","user":null }, "domainName":"r275xc9bmd.execute-api.us-east-1.amazonaws.com", "apiId":"r275xc9bmd" }, "body":"{ \"time\": \"evening\" }", "isBase64Encoded":false } }

Wenn Sie die vorherige Methode POST zu PUT ändern, sollten Sie dieselbe Antwort erhalten.

Um die Methode GET zu testen, kopieren Sie den folgenden cURL-Befehl und fügen Sie ihn in das Terminalfenster ein. Ersetzen Sie dabei r275xc9bmd durch die API-ID Ihrer API und us-east-1 durch die Region, in der Ihre API bereitgestellt wird.

curl -X GET \ 'https://r275xc9bmd.execute-api.us-east-1.amazonaws.com/test/helloworld?Seattle?name=John' \ -H 'content-type: application/json' \ -H 'day: Thursday'

Sie sollten eine ähnliche Antwort erhalten wie bei der vorherigen POST-Anforderung (mit der Ausnahme, dass die GET-Anforderung keine Nutzlast hat). Der body-Parameter ist daher null.