Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Lambda-Integrationen für REST APIs in API Gateway
Sie können eine API-Methode mit einer Lambda-Funktion integrieren, indem Sie eine Lambda-Proxy-Integration oder eine nicht-proxy (benutzerdefinierte) Lambda-Integration verwenden.
Bei der Lambda-Proxy-Integration ist die erforderliche Einrichtung einfach. Legen Sie die HTTP-Methode der Integration auf POST und den Integrationsendpunkt-URI auf den ARN der Lambda-Funktion-Aufrufsaktion einer bestimmten Lambda-Funktion fest. Gewähren Sie dann API Gateway die Berechtigung zum Aufrufen der Lambda-Funktion in Ihrem Namen.
In der Lambda-Nicht-Proxy-Integration müssen Sie zusätzlich zu den Einrichtungsschritten der Proxy-Integration angeben, wie die eingehenden Anfragedaten der Integrationsanforderung und die resultierenden Integrationsantwortdaten der Methodenantwort zugeordnet werden.
**Topics**
+ [Lambda-Proxy-Integrationen in API Gateway](set-up-lambda-proxy-integrations.md)
+ [Benutzerdefinierte Lambda-Integrationen in API Gateway einrichten](set-up-lambda-custom-integrations.md)
+ [Asynchronen Aufruf der Backend-Lambda-Funktion einrichten](set-up-lambda-integration-async.md)
+ [Lambda-Fehler in API Gateway behandeln](handle-errors-in-lambda-integration.md)
# Lambda-Proxy-Integrationen in API Gateway
Im folgenden Abschnitt wird gezeigt, wie Sie eine Lambda-Proxy-Integration verwenden.
**Topics**
+ [API Gateway Lambda-Proxy-Integration kennenlernen](#api-gateway-create-api-as-simple-proxy)
+ [Support für mehrwertige Header- und Abfragezeichenfolgenparameter](#apigateway-multivalue-headers-and-parameters)
+ [Eingabeformat einer Lambda-Funktion für die Proxy-Integration](#api-gateway-simple-proxy-for-lambda-input-format)
+ [Ausgabeformat einer Lambda-Funktion für die Proxy-Integration](#api-gateway-simple-proxy-for-lambda-output-format)
+ [Richten Sie die Lambda-Proxyintegration für API Gateway mit dem ein AWS CLI](set-up-lambda-proxy-integration-using-cli.md)
+ [Proxy-Ressource mit einer Lambda-Proxy-Integration mithilfe einer OpenAPI-Definition einrichten](api-gateway-set-up-lambda-proxy-integration-on-proxy-resource.md)
## API Gateway Lambda-Proxy-Integration kennenlernen
Die Amazon API Gateway-Lambda-Proxy-Integration ist ein einfacher, leistungsstarker und schneller Mechanismus zur Erstellung einer API mit der Einrichtung einer einzigen API-Methode. Die Lambda-Proxy-Integration ermöglicht es dem Client, eine einzelne Lambda-Funktion im Backend aufzurufen. Die Funktion greift auf viele Ressourcen oder Funktionen anderer AWS Dienste zu, einschließlich des Aufrufs anderer Lambda-Funktionen.
Bei der Lambda-Proxy-Integration übergibt API Gateway beim Senden einer API-Anfrage ein [Ereignisobjekt](#api-gateway-simple-proxy-for-lambda-input-format) an die integrierte Lambda-Funktion. Allerdings wird die Reihenfolge der Anfrageparameter nicht beibehalten. Diese [Anforderungsdaten](#api-gateway-simple-proxy-for-lambda-input-format) 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 Anfragedaten, um die eigene Antwort zu bestimmen. Damit API Gateway die Lambda-Ausgabe als API-Antwort an den Client weiterleiten kann, muss die Lambda-Funktion das Ergebnis in [diesem Format](#api-gateway-simple-proxy-for-lambda-output-format) zurückgeben.
Da API Gateway für die Lambda-Proxy-Integration zwischen dem Client und der Backend-Lambda-Funktion nur unwesentlich eingreift, können sich der Client und die integrierte Lambda-Funktion an Änderungen in der jeweils anderen Funktion anpassen, ohne die bestehende Integrationseinrichtung der API zu stören. Hierzu muss der Client den Anwendungsprotokollen der Backend-Lambda-Funktion folgen.
Sie können eine Lambda-Proxy-Integration für jede API-Methode 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 Anfrage als Anfrageparameter 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 den Payload 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 Anfrage-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 Anfrage-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 es einem Supervisor zu ermöglichen, das Inventar der `produce` Abteilung zu aktualisieren, können Sie auf ähnliche Weise eine einzige Methode einrichten: `PUT /produce/{proxy+}` mit read/write Berechtigungen. Um es einem Kassierer zu ermöglichen, die Gesamtsumme eines Gemüses zu aktualisieren, können Sie eine `POST /produce/vegetables/{proxy+}` Methode mit read/write Berechtigungen einrichten. Damit ein Filialleiter alle möglichen Aktionen für jedes verfügbare Produkt ausführen kann, kann der Onlineshop-Entwickler die `ANY /{proxy+}` Methode mit read/write entsprechenden Berechtigungen verfügbar machen. 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 zum Einrichten der API Gateway-Proxy-Integrationen finden Sie unter [Einrichten der Proxy-Integration mit einer Proxy-Ressource](api-gateway-set-up-simple-proxy.md).
Die Proxy-Integration erfordert, dass der Client über detaillierte Kenntnisse der Backend-Anforderungen verfügt. Um eine optimale App-Leistung und Benutzererfahrung sicherzustellen, 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.
## Support für mehrwertige Header- und Abfragezeichenfolgenparameter
API Gateway unterstützt mehrere gleichnamige Header und Abfragezeichenfolgenparameter. Mehrwertige Header sowie einwertige Header und Parameter können in denselben Anforderungen und Antworten kombiniert werden. Weitere Informationen erhalten Sie unter [Eingabeformat einer Lambda-Funktion für die Proxy-Integration](#api-gateway-simple-proxy-for-lambda-input-format) und [Ausgabeformat einer Lambda-Funktion für die Proxy-Integration](#api-gateway-simple-proxy-for-lambda-output-format).
## Eingabeformat einer Lambda-Funktion für die Proxy-Integration
Bei der Lambda-Proxy-Integration ordnet API Gateway die gesamte Client-Anforderung dem `event`-Eingabeparameter der Backend-Lambda-Funktion zu. Das folgende Beispiel zeigt die Struktur eines Ereignisses, das API Gateway an eine Lambda-Proxy-Integration sendet.
In diesem Beispiel gehen wir davon aus, dass der Aufruf an API Gateway folgendermaßen erfolgte:
```
curl 'https://a1b2c3.execute-api.us-east-1.amazonaws.com/my/path?parameter1=value1¶meter2=value1¶meter2=value2¶meter3=value1,value2' -H 'header1: value1' -H 'header2: value1' -H 'header2: value2' -H 'header3: value1,value2'
```
Die Ausgabe sollte wie folgt aussehen:
```
{
"resource": "/my/path",
"path": "/my/path",
"httpMethod": "GET",
"headers": {
"header1": "value1",
"header2": "value2",
"header3": "value1,value2"
},
"multiValueHeaders": {
"header1": ["value1"],
"header2": ["value1","value2"],
"header3": ["value1,value2"]
},
"queryStringParameters": {
"parameter1": "value1",
"parameter2": "value2",
"parameter3": "value1,value2"
},
"multiValueQueryStringParameters": {
"parameter1": ["value1"],
"parameter2": ["value1","value2"],
"parameter3": ["value1,value2"]
},
"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": "IP",
"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
}
```
**Anmerkung**
Wählen Sie im Bereich
Der `headers`Schlüssel kann nur einwertige Header enthalten
Der `multiValueHeaders`Schlüssel kann mehrwertige Header sowie einwertige Header enthalten.
Wenn Sie Werte sowohl für `headers` als auch für `multiValueHeaders` angeben, führt API Gateway diese in einer einzigen Liste zusammen. Wenn in beiden das gleiche Schlüssel / Wert-Paar angegeben ist, werden nur die Werte von in der `multiValueHeaders`zusammengeführten Liste angezeigt.
In der Eingabe an die Backend-Lambda-Funktion ist das `requestContext`-Objekt eine Zuordnung von Schlüssel-Werte-Paaren. In jedem Paar ist der Schlüssel der Name einer [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference)-Variableneigenschaft, und der Wert ist der Wert dieser Eigenschaft. API Gateway kann der Zuordnung u. U. 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 wird, bewirkt dies, dass API Gateway autorisierte Benutzerinformationen wie folgt in einem `requestContext.identity`-Objekt an den Integrationsendpunkt weiterleitet:
+ Wenn der Autorisierungstyp `AWS_IAM` ist, enthalten die autorisierten Benutzerinformationen `$context.identity.*`-Eigenschaften.
+ Wenn der Autorisierungstyp `COGNITO_USER_POOLS` ist (Amazon Cognito-Genehmiger), enthalten die autorisierten Benutzerinformationen die Eigenschaften `$context.identity.cognito*` und `$context.authorizer.claims.*`.
+ Wenn der Autorisierungstyp `CUSTOM` (Lambda-Genehmiger) ist, enthalten die autorisierten Benutzerinformationen `$context.authorizer.principalId`- und andere relevante `$context.authorizer.*`-Eigenschaften.
## Ausgabeformat einer Lambda-Funktion für die Proxy-Integration
Bei der Lambda-Proxy-Integration erfordert API Gateway, dass die Backend-Lambda-Funktion die Ausgabe gemäß dem folgenden JSON-Format zurückgibt:
```
{
"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 `headers`Schlüssel kann nur einwertige Header enthalten
+ Der `multiValueHeaders`Schlüssel kann mehrwertige Header sowie einwertige Header enthalten. Sie können den `multiValueHeaders`Schlüssel verwenden, um alle zusätzlichen Header anzugeben, einschließlich einzelner Werte.
+ Wenn Sie Werte sowohl für `headers` als auch für `multiValueHeaders` angeben, führt API Gateway diese in einer einzigen Liste zusammen. Wenn in beiden das gleiche Schlüssel / Wert-Paar angegeben ist, werden nur die Werte von in der `multiValueHeaders`zusammengeführten Liste angezeigt.
Um CORS für die Lambda-Proxy-Integration zu aktivieren, müssen Sie der Ausgabe `headers` `Access-Control-Allow-Origin:domain-name` hinzufügen. `domain-name` kann `*` für einen beliebigen Domänennamen 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 [Binärunterstützung über die API Gateway-Konsole aktivieren](api-gateway-payload-encodings-configure-with-console.md). Eine Beispielfunktion für Lambda finden Sie unter [Rückgabe binärer Medien aus einer Lambda-Proxy-Integration in API Gateway](lambda-proxy-binary-media.md).
Wenn die Funktionsausgabe ein anderes Format hat, gibt API Gateway eine `502 Bad Gateway`-Fehlerantwort zurück.
Um eine Antwort in einer Lambda-Funktion in Node.js zurückzugeben, können Sie Befehle wie den folgenden verwenden:
+ Um ein erfolgreiches Ergebnis zurückzugeben, rufen Sie au `callback(null, {"statusCode": 200, "body": "results"})`.
+ Rufen Sie zum Auslösen einer Ausnahme au `callback(new Error('internal server error'))`.
+ 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 einer Lambda-`async`-Funktion in Node.js würde die entsprechende Syntax so lauten:
+ Um ein erfolgreiches Ergebnis zurückzugeben, rufen Sie au `return {"statusCode": 200, "body": "results"}`.
+ Rufen Sie zum Auslösen einer Ausnahme au `throw new Error("internal server error")`.
+ 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.
# Richten Sie die Lambda-Proxyintegration für API Gateway mit dem ein AWS CLI
In diesem Abschnitt zeigen wir Ihnen, wie Sie mithilfe von AWS CLI eine API mit der Lambda-Proxy-Integration einrichten. Detaillierte Anweisungen zur Verwendung der API Gateway-Konsole zur Konfiguration einer Proxy-Ressource mit der Lambda-Proxy-Integration finden Sie unter [Tutorial: Erstellen einer REST-API mit einer Lambda-Proxy-Integration](api-gateway-create-api-as-simple-proxy-for-lambda.md).
Als Beispiel verwenden wir die folgende Lambda-Beispielfunktion als Backend der API:
```
export const handler = async(event, context) => {
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 + "!";
return res
};
```
Vergleicht man dies mit der benutzerdefinierten Lambda-Integrationseinrichtung unter [Benutzerdefinierte Lambda-Integrationen in API Gateway einrichten](set-up-lambda-custom-integrations.md), kann die Eingabe für diese Lambda-Funktion in den Anfrageparametern und im Text definiert 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 kann außerdem die benutzerdefinierte Lambda-Integration unterstützen. Die API-Einrichtung ist einfacher. Sie müssen keine Methoden- oder Integrationsantwort konfigurieren.
**So richten Sie eine Lambda-Proxyintegration mit dem AWS CLI**
1. Verwenden Sie den folgenden [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)Befehl, um eine API zu erstellen:
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
Die Ausgabe sieht wie folgt aus:
```
{
"name": "HelloWorldProxy (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
In diesem Beispiel verwenden Sie durchgängig die API `id` (`te6si5ach7`) und die `rootResourceId` (`krznpq9xpg`).
1. Verwenden Sie den folgenden [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html)-Befehl, um eine API-Gateway-[Ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) mit dem Namen `/greeting` zu erstellen:
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part {proxy+}
```
Die Ausgabe sieht wie folgt aus:
```
{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
Sie verwenden den `id`-Wert der Ressource `{proxy+}` (`2jf6xt`), um im nächsten Schritt eine Methode für die Ressource `/{proxy+}` zu erstellen.
1. Verwenden Sie die folgende [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html), um eine `ANY`-Methodenanforderung von `ANY /{proxy+}` zu erstellen:
```
aws apigateway put-method --rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method ANY \
--authorization-type "NONE"
```
Die Ausgabe sieht wie folgt aus:
```
{
"apiKeyRequired": false,
"httpMethod": "ANY",
"authorizationType": "NONE"
}
```
Diese API-Methode gestattet dem Client, einen Gruß über die Lambda-Funktion am Backend zu empfangen oder zu senden.
1. Verwenden Sie den folgenden [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html)-Befehl, um die Integration der `ANY /{proxy+}`-Methode mit einer Lambda-Funktion mit dem Namen `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 \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method ANY \
--type AWS_PROXY \
--integration-http-method POST \
--uri arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:HelloWorld/invocations \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole
```
**Wichtig**
Für Lambda-Integrationen müssen Sie entsprechend der [Spezifikation der Lambda-Service-Aktion für Funktionsaufrufe](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) die HTTP-Methode `POST` für die Integrationsanfrage verwenden. Die IAM-Rolle `apigAwsProxyRole` muss über Richtlinien verfügen, die es dem `apigateway`-Service erlauben, Lambda-Funktionen aufzurufen. Weitere Informationen zu IAM-Berechtigungen finden Sie unter [API Gateway-Berechtigungsmodell für den Aufruf einer API](permissions.md#api-gateway-control-access-iam-permissions-model-for-calling-api).
Die Ausgabe sieht wie folgt aus:
```
{
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2: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](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) verwenden, um ressourcenbasierte Berechtigungen hinzuzufügen. Dies erledigt die API Gateway-Konsole.
1. Verwenden Sie den folgenden [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html)-Befehl, um die API für eine `test`-Stufe bereitzustellen:
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. 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'
```
API-Aufruf mit einem Header-Parameter `greeter:jane`:
```
curl -X GET https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \
-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/hi \
-H 'content-type: application/json' \
-d '{ "greeter": "jane" }'
```
In allen Fällen ist die Ausgabe eine Antwort mit dem folgenden Antworttext: 200
```
Hello, jane!
```
# Proxy-Ressource mit einer Lambda-Proxy-Integration mithilfe einer OpenAPI-Definition einrichten
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. Wie bei einer Nicht-Proxy-Ressource können Sie 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.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"
}
}
}
}
}
```
------
Bei der Lambda-Proxy-Integration ordnet API Gateway zur Laufzeit eine eingehende Anfrage dem Eingabe-`event`-Parameter der Lambda-Funktion 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 die Proxy-Integration](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). Damit API Gateway die Lambda-Ausgabe erfolgreich den HTTP-API-Antworten zuordnen kann, muss die Lambda-Funktion das Ergebnis in dem unter [Ausgabeformat einer Lambda-Funktion für die Proxy-Integration](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format) beschriebenen Format ausgeben.
Bei der Lambda-Proxy-Integration einer Proxy-Ressource durch die `ANY`-Methode dient die einzelne Backend-Lambda-Funktion als Ereignis-Handler für alle Anfragen über die Proxy-Ressource. 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 Location-tuples in eine DynamoDB-Tabelle einfügen.
# Benutzerdefinierte Lambda-Integrationen in API Gateway einrichten
Um zu zeigen, wie die benutzerdefinierte (nicht-Proxy-)Lambda-Integration eingerichtet wird, erstellen wir ein API in API Gateway, um die `GET /greeting?greeter={name}`-Methode zum Aufrufen einer Lambda-Funktion bereitzustellen. Verwenden Sie eine der folgenden Lambda-Beispielfunktionen für Ihre API.
Verwenden Sie eine der folgenden Lambda-Beispielfunktionen:
------
#### [ Node.js ]
```
'use strict';
var days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
var times = ['morning', 'afternoon', 'evening', 'night', 'day'];
export const handler = async(event) => {
console.log(event);
// Parse the input for the name, city, time and day property values
let name = event.name === null || event.name === undefined || event.name === "" ? 'you' : event.name;
let city = event.city === undefined ? 'World' : event.city;
let time = times.indexOf(event.time)<0 ? 'day' : event.time;
let day = days.indexOf(event.day)<0 ? null : event.day;
// Generate a greeting
let greeting = 'Good ' + time + ', ' + name + ' of ' + city + '. ';
if (day) greeting += 'Happy ' + day + '!';
// Log the greeting to CloudWatch
console.log('Hello: ', greeting);
// Return a greeting to the caller
return greeting;
};
```
------
#### [ Python ]
```
import json
def lambda_handler(event, context):
print(event)
res = {
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
}
}
if event['greeter'] == "":
res['body'] = "Hello, World"
elif (event['greeter']):
res['body'] = "Hello, " + event['greeter'] + "!"
else:
raise Exception('Missing the required greeter parameter.')
return res
```
------
Die Funktion gibt die Nachricht `"Hello, {name}!"` zurück, sofern der `greeter`-Parameterwert keine leere Zeichenfolge ist. Wenn der `"Hello, World!"`-Wert eine leere Zeichenfolge ist, wird als Antwort `greeter` zurückgegeben. Die Funktion gibt eine Fehlermeldung zurück, `"Missing the required greeter parameter."` wenn der "greeter"-Parameter in der eingehenden Anforderung nicht festgelegt ist. Wir geben der Funktion den Namen `HelloWorld`.
Sie können sie in der Lambda-Konsole oder mithilfe der AWS CLI erstellen. In diesem Abschnitt definieren wir diese Funktion mithilfe des folgenden ARN:
```
arn:aws:lambda:us-east-1:123456789012:function:HelloWorld
```
Wenn die Lambda-Funktion im Backend eingerichtet ist, fahren Sie mit dem Einrichten der API fort.
**So richten Sie die benutzerdefinierte Lambda-Integration mit dem AWS CLI**
1. Verwenden Sie den folgenden [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)Befehl, um eine API zu erstellen:
```
aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)'
```
Die Ausgabe sieht wie folgt aus:
```
{
"name": "HelloWorld (AWS CLI)",
"id": "te6si5ach7",
"rootResourceId" : "krznpq9xpg",
"createdDate": 1508461860
}
```
In diesem Beispiel verwenden Sie durchgängig die API `id` (`te6si5ach7`) und die `rootResourceId` (`krznpq9xpg`).
1. Verwenden Sie den folgenden [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html)-Befehl, um eine API-Gateway-[Ressource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) mit dem Namen `/greeting` zu erstellen:
```
aws apigateway create-resource \
--rest-api-id te6si5ach7 \
--parent-id krznpq9xpg \
--path-part greeting
```
Die Ausgabe sieht wie folgt aus:
```
{
"path": "/greeting",
"pathPart": "greeting",
"id": "2jf6xt",
"parentId": "krznpq9xpg"
}
```
Sie verwenden den `id`-Wert der Ressource `greeting` (`2jf6xt`), um im nächsten Schritt eine Methode für die Ressource `/greeting` zu erstellen.
1. Verwenden Sie den folgenden [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html)-Befehl, um eine API-Methodenanforderung von `GET /greeting?greeter={name}` zu erstellen:
```
aws apigateway put-method --rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.querystring.greeter=false
```
Die Ausgabe sieht wie folgt aus:
```
{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE",
"requestParameters": {
"method.request.querystring.greeter": false
}
}
```
Diese API-Methode gestattet dem Client, einen Gruß über die Lambda-Funktion am Backend zu empfangen. Der `greeter`-Parameter ist optional, da das Backend entweder einen anonymen Aufrufer oder einen selbst identifizierten Aufrufer verarbeiten sollte.
1. Verwenden Sie den folgenden [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)Befehl, um die `200 OK` Antwort auf die Methodenanforderung von einzurichten`GET /greeting?greeter={name}`:
```
aws apigateway put-method-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200
```
1. Verwenden Sie den folgenden [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html)-Befehl, um die Integration der `GET /greeting?greeter={name}`-Methode mit einer Lambda-Funktion mit dem Namen `HelloWorld` einzurichten. Die 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 \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--type AWS \
--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 \
--request-templates '{"application/json":"{\"greeter\":\"$input.params('greeter')\"}"}' \
--credentials arn:aws:iam::123456789012:role/apigAwsProxyRole
```
Die hier bereitgestellte Mapping-Vorlage übersetzt den `greeter`-Abfragezeichenfolgeparameter in den `greeter`-Parameter der JSON-Nutzlast. Dies ist notwendig, da die Eingabe einer Lambda-Funktion im Textkörper ausgedrückt werden muss.
**Wichtig**
Für Lambda-Integrationen müssen Sie entsprechend der [Spezifikation der Lambda-Service-Aktion für Funktionsaufrufe](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) die HTTP-Methode `POST` für die Integrationsanfrage verwenden. Der `uri`-Parameter ist der ARN der Aktion, die die Funktion aufruft.
Die Ausgabe sieht wie folgt 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:123456789012:function:HelloWorld/invocations",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\"greeter\":\"$input.params('greeter')\"}"
},
"cacheNamespace": "krznpq9xpg",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"type": "AWS"
}
```
Die IAM-Rolle `apigAwsProxyRole` muss über Richtlinien verfügen, die es dem `apigateway`-Service erlauben, Lambda-Funktionen aufzurufen. Anstatt eine IAM-Rolle für `credentials` bereitzustellen, können Sie den Befehl [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) aufrufen, um ressourcenbasierte Berechtigungen hinzuzufügen. Auf diese Weise fügt die API Gateway-Konsole diese Berechtigungen hinzu.
1. Verwenden Sie den folgenden [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)Befehl, um die Integrationsantwort so einzurichten, dass die Ausgabe der Lambda-Funktion als `200 OK` Methodenantwort an den Client übergeben wird:
```
aws apigateway put-integration-response \
--rest-api-id te6si5ach7 \
--resource-id 2jf6xt \
--http-method GET \
--status-code 200 \
--selection-pattern ""
```
Beim Festlegen des Auswahlmusters auf eine leere Zeichenfolge lautet die voreingestellte Antwort `200 OK`.
Die Ausgabe sieht wie folgt aus:
```
{
"selectionPattern": "",
"statusCode": "200"
}
```
1. Verwenden Sie den folgenden [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html)-Befehl, um die API für eine `test`-Stufe bereitzustellen:
```
aws apigateway create-deployment \
--rest-api-id te6si5ach7 \
--stage-name test
```
1. Testen Sie die API mithilfe des folgenden cURL-Befehls in einem Terminal:
```
curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=me' \
-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'
```
# Asynchronen Aufruf der Backend-Lambda-Funktion einrichten
Bei der nicht-proxy (benutzerdefinierten) Lambda-Integration wird die Backend-Lambda-Funktion standardmäßig synchron aufgerufen. Dies ist das gewünschte Verhalten für die meisten REST-API-Operationen. Einige Anwendungen erfordern jedoch eine asynchrone Durchführung (als Batchvorgang oder Operation mit langer Latenzzeit), in der Regel durch eine separate Backend-Komponente. In diesem Fall wird die Lambda-Backend-Funktion asynchron aufgerufen, und die Frontend-REST-API-Methode gibt das Ergebnis nicht zurück.
Sie können die Lambda-Funktion für eine nicht-proxy Lambda-Integration so konfigurieren, dass sie asynchron aufgerufen wird, indem Sie `'Event'` als [Lambda invocation type (Lambda-Aufruftyp)](https://docs.aws.amazon.com/lambda/latest/dg/lambda-invocation.html) festlegen. Gehen Sie hierzu folgendermaßen vor:
## Asynchronen Lambda-Aufruf in der API Gateway-Konsole konfigurieren
Damit alle Aufrufe asynchron sind:
+ Fügen Sie in **Integrationsanforderung** einen `X-Amz-Invocation-Type`-Header mit dem statischen Wert `'Event'` hinzu.
Damit Clients entscheiden können, ob Aufrufe asynchron oder synchron sind:
1. Fügen Sie in **Methodenanforderung** einen `InvocationType`-Header hinzu.
1. Fügen Sie in **Integrationsanforderung** einen `X-Amz-Invocation-Type`-Header mit dem Mapping-Ausdruck `method.request.header.InvocationType` hinzu.
1. Clients können den `InvocationType: Event`-Header in API-Anforderungen für asynchrone Aufrufe oder `InvocationType: RequestResponse` für synchrone Aufrufe einschließen.
## Asynchronen Lambda-Aufruf mit OpenAPI konfigurieren
Damit alle Aufrufe asynchron sind:
+ Fügen Sie die `X-Amz-Invocation-Type` Kopfzeile zum **x-amazon-apigateway-integration**Abschnitt hinzu.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.X-Amz-Invocation-Type" : "'Event'"
},
"passthroughBehavior" : "when_no_match",
"contentHandling" : "CONVERT_TO_TEXT"
}
```
Damit Clients entscheiden können, ob Aufrufe asynchron oder synchron sind:
1. Fügen Sie ein beliebiges [OpenAPI Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) dem folgenden Header hinzu.
```
"parameters" : [ {
"name" : "InvocationType",
"in" : "header",
"schema" : {
"type" : "string"
}
} ]
```
1. Fügen Sie die `X-Amz-Invocation-Type` Kopfzeile zum **x-amazon-apigateway-integration**Abschnitt hinzu.
```
"x-amazon-apigateway-integration" : {
"type" : "aws",
"httpMethod" : "POST",
"uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.X-Amz-Invocation-Type" : "method.request.header.InvocationType"
},
"passthroughBehavior" : "when_no_match",
"contentHandling" : "CONVERT_TO_TEXT"
}
```
1. Clients können den `InvocationType: Event`-Header in API-Anforderungen für asynchrone Aufrufe oder `InvocationType: RequestResponse` für synchrone Aufrufe einschließen.
## Konfigurieren Sie den asynchronen Lambda-Aufruf mit CloudFormation
Die folgenden CloudFormation Vorlagen zeigen, wie Sie den `AWS::ApiGateway::Method` für asynchrone Aufrufe konfigurieren.
Damit alle Aufrufe asynchron sind:
```
AsyncMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref AsyncResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
RequestParameters:
integration.request.header.X-Amz-Invocation-Type: "'Event'"
IntegrationResponses:
- StatusCode: '200'
IntegrationHttpMethod: POST
Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations
MethodResponses:
- StatusCode: '200'
```
Damit Clients entscheiden können, ob Aufrufe asynchron oder synchron sind:
```
AsyncMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref AsyncResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
RequestParameters:
method.request.header.InvocationType: false
Integration:
Type: AWS
RequestParameters:
integration.request.header.X-Amz-Invocation-Type: method.request.header.InvocationType
IntegrationResponses:
- StatusCode: '200'
IntegrationHttpMethod: POST
Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations
MethodResponses:
- StatusCode: '200'
```
Clients können den `InvocationType: Event`-Header in API-Anforderungen für asynchrone Aufrufe oder `InvocationType: RequestResponse` für synchrone Aufrufe einschließen.
# Lambda-Fehler in API Gateway behandeln
Bei benutzerdefinierten Lambda-Integrationen müssen Sie Fehler, die von Lambda in der Integrationsantwort zurückgegeben werden, für Ihre Kunden zu Standard-HTTP-Fehlerantworten zuordnen. Andernfalls werden Lambda-Fehler standardmäßig als `200 OK`-Meldungen zurückgegeben und ein solches Verhalten ist für die API-Benutzer nicht intuitiv.
Lambda kann zwei Fehlertypen zurückgeben, nämlich Standardfehler und benutzerdefinierte Fehler. In Ihrer API müssen Sie diese unterschiedlich handhaben.
Bei der Lambda-Proxy-Integration muss Lambda eine Ausgabe im folgenden Format zurückgeben:
```
{
"isBase64Encoded" : "boolean",
"statusCode": "number",
"headers": { ... },
"body": "JSON string"
}
```
Bei dieser Ausgabe entspricht `statusCode` einem `4XX`-Client-Fehler bzw. einem `5XX`-Server-Fehler. API Gateway behandelt diese Fehler über das Mapping des Lambda-Fehlers zu einer HTTP-Fehlerantwort gemäß den angegebenen `statusCode`. Damit API Gateway den Fehlertyp (z. B. `InvalidParameterException`) als Teil der Antwort an den Client weitergibt, muss die Lambda-Funktion einen Header (z. B. `"X-Amzn-ErrorType":"InvalidParameterException"`) in der `headers`-Eigenschaft enthalten.
**Topics**
+ [Standard-Lambda-Fehler in API Gateway behandeln](#handle-standard-errors-in-lambda-integration)
+ [Benutzerdefinierte Lambda-Fehlern in API Gateway behandeln](#handle-custom-errors-in-lambda-integration)
## Standard-Lambda-Fehler in API Gateway behandeln
Ein AWS Lambda Standardfehler hat das folgende Format:
```
{
"errorMessage": "string",
"errorType": "string",
"stackTrace": [
"string",
...
]
}
```
Hier ist `errorMessage` ein Zeichenfolgeausdruck des Fehlers. Der Wert `errorType` gibt eine sprachabhängige Fehler- oder Ausnahmeart an. `stackTrace` zeigt in einer Liste von Zeichenfolgeausdrücken das Stacktrace an, das zum Fehlerereignis geführt hat.
Betrachten Sie beispielsweise die folgende Lambda-Funktion JavaScript (Node.js).
```
export const handler = function(event, context, callback) {
callback(new Error("Malformed input ..."));
};
```
Diese Funktion gibt den folgenden Lambda-Standardfehler mit der Fehlermeldung `Malformed input ...` zurück:
```
{
"errorMessage": "Malformed input ...",
"errorType": "Error",
"stackTrace": [
"export const handler (/var/task/index.js:3:14)"
]
}
```
Bei der folgenden Python-Lambda-Funktion wird beispielsweise eine `Exception` mit derselben Fehlermeldung `Malformed input ...` ausgegeben:
```
def lambda_handler(event, context):
raise Exception('Malformed input ...')
```
Diese Funktion gibt den folgenden Standard-Lambda-Fehler zurück:
```
{
"stackTrace": [
[
"/var/task/lambda_function.py",
3,
"lambda_handler",
"raise Exception('Malformed input ...')"
]
],
"errorType": "Exception",
"errorMessage": "Malformed input ..."
}
```
Beachten Sie, dass die Eigenschaftswerte `errorType` und `stackTrace` sprachabhängig sind. Der Standardfehler gilt auch für jedes Fehlerobjekt, das eine Erweiterung des `Error`-Objekts oder eine Subklasse der `Exception`-Klasse ist.
Um den Standard-Lambda-Fehler einer Methodenantwort zuzuordnen, müssen Sie zunächst einen HTTP-Statuscode für einen bestimmten Lambda-Fehler festlegen. Anschließend legen Sie ein reguläres Ausdrucksmuster für die `[selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern)` Eigenschaft fest, die dem angegebenen HTTP-Statuscode [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)zugeordnet ist. In der API-Gateway-Konsole wird dieses `selectionPattern` im Abschnitt **Integrationsantwort** unter jeder Integrationsantwort als **Lambda-Fehler-Regex** ausgewiesen.
**Anmerkung**
API Gateway verwendet für das Antwort-Mapping Regexe-Anweisungen im Java-Pattern-Stil. Weitere Informationen finden Sie unter [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) in der OracleDokumentation.
Verwenden Sie beispielsweise Folgendes, [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)um einen neuen `selectionPattern` Ausdruck einzurichten:
```
aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --http-method GET --status-code 400 --selection-pattern "Malformed.*" --region us-west-2
```
Stellen Sie sicher, dass Sie auch den entsprechenden Fehlercode (`400`) für die [Methodenantwort definieren](api-gateway-method-settings-method-response.md#setup-method-response-status-code). Andernfalls gibt API Gateway zur Laufzeit eine ungültige Konfigurationsfehler-Antwort aus.
**Anmerkung**
Zur Laufzeit ordnet API Gateway die `errorMessage` des Lambda-Fehlers dem Muster des regulären Ausdrucks für die `selectionPattern`-Eigenschaft zu. Wenn es eine Zuordnung gibt, gibt API Gateway den Lambda-Fehler als HTTP-Antwort des entsprechenden HTTP-Statuscodes zurück. Liegt keine Übereinstimmung vor, gibt API Gateway den Fehler als Standardmeldung zurück. Falls keine Standardmeldung konfiguriert ist, wird eine Fehlermeldung bezüglich einer ungültigen Konfiguration ausgegeben.
Wenn als `selectionPattern`-Wert für eine bestimmte Antwort `.*` festgelegt wird, wird diese Antwort wieder als Standardantwort festgelegt. Der Grund hierfür ist, dass ein solches Auswahlmuster allen Fehlermeldungen entspricht, einschließlich Null, d. h. nicht spezifizierten Fehlermeldungen. Das daraus resultierende Mapping überschreibt das des Standard-Mapping. Wenn Sie `.+` als Auswahlmuster zur Filterung von Antworten verwenden, beachten Sie, dass es eine Antwort mit einem Zeilenumbruch ('`\n`) möglicherweise nicht erkennt.
Um einen vorhandenen `selectionPattern` Wert mithilfe von zu aktualisieren AWS CLI, rufen Sie die [update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html)Operation auf, um den `/selectionPattern` Pfadwert durch den angegebenen Regex-Ausdruck des `Malformed*` Musters zu ersetzen.
Wenn Sie eine Integrationsantwort für einen bestimmten HTTP-Statuscode einrichten oder aktualisieren wollen, geben Sie den Ausdruck im Textfeld **Lambda-Fehler-Regex** ein, um den `selectionPattern`-Ausdruck über die Amazon API Gateway-Konsole zu definieren.
## Benutzerdefinierte Lambda-Fehlern in API Gateway behandeln
AWS Lambda Ermöglicht es Ihnen, anstelle des im vorherigen Abschnitt beschriebenen Standardfehlers ein benutzerdefiniertes Fehlerobjekt als JSON-Zeichenfolge zurückzugeben. Der Fehler kann ein beliebiges gültiges JSON-Objekt sein. Beispielsweise gibt die folgende Lambda-Funktion JavaScript (Node.js) einen benutzerdefinierten Fehler zurück:
```
export const handler = (event, context, callback) => {
...
// Error caught here:
var myErrorObj = {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
callback(JSON.stringify(myErrorObj));
};
```
Das `myErrorObj`-Objekt muss in eine JSON-Zeichenfolge umgewandelt werden, bevor Sie `callback` zum Beenden der Funktion aufrufen. Andernfalls wird `myErrorObj` als `"[object Object]"`-Zeichenfolge zurückgegeben. Wenn eine Methode Ihrer API mit der vorhergehenden Lambda-Funktion integriert wird, erhält API Gateway eine Integrationsantwort mit dem folgenden Payload:
```
{
"errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}"
}
```
Wie bei jeder Integrationsantwort können Sie diese Fehlermeldung unverändert an die Methodenantwort übergeben. Alternativ können Sie die Nutzlast mithilfe einer Zuordnungsvorlage in ein anderes Format umwandeln. Nehmen Sie zum Beispiel die folgende Text-Mapping-Vorlage für eine Methodenantwort mit dem Statuscode `500`:
```
{
errorMessage: $input.path('$.errorMessage');
}
```
Diese Vorlage wandelt den Integrationsantworttext mit der benutzerdefinierten JSON-Fehlerzeichenfolge in den folgenden Methodenantworttext um. Dieser Methodenantworttext enthält das benutzerdefinierte JSON-Fehlerobjekt:
```
{
"errorMessage" : {
errorType : "InternalServerError",
httpStatus : 500,
requestId : context.awsRequestId,
trace : {
"function": "abc()",
"line": 123,
"file": "abc.js"
}
}
};
```
Abhängig von Ihren API-Anforderungen müssen Sie möglicherweise einige oder alle benutzerdefinierte Fehlereigenschaften als Header-Parameter für die Methodenantwort übergeben. Dazu wenden Sie die benutzerdefinierten Fehler-Mappings aus dem Integrationsantworttext auf die Header der Methodenantwort an.
Beispielsweise definiert die folgende OpenAPI-Erweiterung das Mapping der Eigenschaften `errorMessage.errorType`, `errorMessage.httpStatus`, `errorMessage.trace.function` und `errorMessage.trace` zu den Headern `error_type`, `error_status`, `error_trace_function` und `error_trace`:
```
"x-amazon-apigateway-integration": {
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.error_trace_function": "integration.response.body.errorMessage.trace.function",
"method.response.header.error_status": "integration.response.body.errorMessage.httpStatus",
"method.response.header.error_type": "integration.response.body.errorMessage.errorType",
"method.response.header.error_trace": "integration.response.body.errorMessage.trace"
},
...
}
}
}
```
Zur Laufzeit deserialisiert API Gateway den Parameter `integration.response.body` bei der Ausführung von Header-Mappings. Diese Deserialisierung gilt jedoch nur für body-to-header Zuordnungen für benutzerdefinierte Lambda-Fehlerantworten und nicht für Zuordnungen mit. body-to-body `$input.body` Bei diesen custom-error-body-to -Header-Zuordnungen erhält der Client die folgenden Header als Teil der Methodenantwort, vorausgesetzt, dass die Header,, und in der Methodenanforderung deklariert `error_status` sind. `error_trace` `error_trace_function` `error_type`
```
"error_status":"500",
"error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}",
"error_trace_function":"abc()",
"error_type":"InternalServerError"
```
Die Eigenschaft `errorMessage.trace` des Integrationsantworttexts ist eine komplexe Eigenschaft. Sie wird dem Header `error_trace` als JSON-Zeichenfolge zugewiesen.