Auswählen eines API-Typs Hinzufügen eines Endpunkts zur Lambda-Funktion Proxy-Integration Ereignisformat Reaktionsformat Berechtigungen Beispielanwendung Der Event-Handler von Powertools für AWS Lambda

Aufrufen einer Lambda-Funktion über einen Amazon API Gateway-Endpunkt

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.

Tipp

Lambda bietet zwei Möglichkeiten, Ihre Funktion über einen HTTP-Endpunkt aufzurufen: API Gateway und Lambda-Funktions-URLs. Wenn Sie sich nicht sicher sind, welche Methode für Ihren Anwendungsfall am besten geeignet ist, siehe Wählen Sie eine Methode, um Ihre Lambda-Funktion über eine HTTP-Anfrage aufzurufen.

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.

Sections

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, featurereiche RESTful-API.
WebSocket API: Eine Web-API, die persistente Verbindungen zu Kunden 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 Features sind neu bei HTTP-APIs:

HTTP-API-Features

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 Tracing 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 Gateway Version 2 der API und unterstützen einen ähnlichen Funktionsumfang. Verwenden Sie eine WebSocket API für Anwendungen, die von einer dauerhaften Verbindung zwischen dem Client und der API profitieren. WebSocket APIs bieten Vollduplex-Kommunikation, was bedeutet, dass sowohl der Client als auch die API kontinuierlich Nachrichten senden können, ohne auf eine Antwort zu warten.

HTTP-APIs unterstützen ein vereinfachtes Ereignisformat (Version 2.0). Ein Beispiel für ein Ereignis aus einer HTTP-API finden Sie unter Erstellen von AWS Lambda Proxy-Integrationen für HTTP-APIs in API Gateway.

Weitere Informationen finden Sie unter Erstellen von AWS Lambda Proxy-Integrationen für HTTP-APIs in API Gateway.

Hinzufügen eines Endpunkts zur Lambda-Funktion

So fügen Sie Ihrer Lambda-Funktion einen öffentlichen Endpunkt hinzu

Öffnen Sie die Seite Funktionen der Lambda-Konsole.
Wählen Sie eine Funktion aus.
Wählen Sie unter Function overview (Funktionsübersicht) die Option Add trigger (Trigger hinzufügen).
Wählen Sie API Gateway aus.
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 Auswählen eines API-Typs.
2. Vorhandene API: Wählen Sie die API aus der Dropdown-Liste aus oder geben Sie die API-ID ein (z. B. r3pmxmplak).
Wählen Sie unter Security (Sicherheit) die Option Open (Öffnen) aus.
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.

Weitere Informationen finden Sie unter Lambda-Proxy-Integrationen in API Gateway.

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. Ein Beispiel für ein Proxy-Ereignis von einer API Gateway REST API finden Sie unter Eingabeformat einer Lambda-Funktion für die Proxy-Integration im API Gateway Developer Guide.

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 einer Node.js Funktion. Das Antwortobjekt stellt eine erfolgreiche HTTP-Antwort dar, die ein JSON-Dokument enthält.

Beispiel index.mjs — Antwortobjekt für die Proxyintegration () 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

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

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


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 Ihre Funktion und Ihre API unterschiedlich sind AWS-Regionen, muss der Region-Identifier im Quell-ARN mit der Region der Funktion übereinstimmen, nicht mit der Region der API. 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 Anzeigen von ressourcenbasierten IAM-Richtlinien in Lambda.

Beispielanwendung

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

Der Event-Handler von Powertools für AWS Lambda

Der Event-Handler aus dem Powertools for AWS Lambda-Toolkit bietet Routing, Middleware, CORS-Konfiguration, OpenAPI-Spezifikationsgenerierung, Anforderungsvalidierung, Fehlerbehandlung und andere nützliche Funktionen beim Schreiben von Lambda-Funktionen, die von einem API-Gateway-Endpunkt (HTTP oder REST) aufgerufen werden. Das Event-Handler-Hilfsprogramm ist für Python und verfügbar. TypeScript/JavaScript Weitere Informationen finden Sie unter Event Handler REST API in der Powertools for AWS Lambda (Python) -Dokumentation und Event Handler HTTP API in der Powertools for AWS Lambda () -Dokumentation. TypeScript

Python


from aws_lambda_powertools import Logger
from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools.utilities.typing.lambda_context import LambdaContext

app = APIGatewayRestResolver()
logger = Logger()

@app.get("/healthz")
def ping():
    return {"message": "health status ok"}

@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)  
def lambda_handler(event: dict, context: LambdaContext) -> dict:
    return app.resolve(event, context)

TypeScript


import { Router } from '@aws-lambda-powertools/event-handler/experimental-rest';
import { Logger } from '@aws-lambda-powertools/logger';
import {
  correlationPaths,
  search,
} from '@aws-lambda-powertools/logger/correlationId';
import type { Context } from 'aws-lambda/handler';

const logger = new Logger({
  correlationIdSearchFn: search,
});

const app = new Router({ logger });

app.get("/healthz", async () => {
  return { message: "health status ok" };
});

export const handler = async (event: unknown, context: Context) => {
  // You can continue using other utilities just as before
  logger.addContext(context);
  logger.setCorrelationId(event, correlationPaths.API_GATEWAY_REST);
  return app.resolve(event, context);
};

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Fehlerbehebung

Tutorial