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.

Standard-Lambda-Fehler in API Gateway behandeln

Ein AWS Lambda-Standardfehler hat folgendes Format:

{
  "errorMessage": "<replaceable>string</replaceable>",
  "errorType": "<replaceable>string</replaceable>",
  "stackTrace": [
    "<replaceable>string</replaceable>",
    ...
  ]
}

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.

Nehmen wir beispielsweise die folgende JavaScript (Node.js) Lambda-Funktion.

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 definieren Sie ein reguläres Ausdrucksmuster für die selectionPattern-Eigenschaft von IntegrationResponse, die dem angegebenen HTTP-Statuscode 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 in der OracleDokumentation.

Wenn Sie beispielsweise einen neuen selectionPattern-Ausdruck mit der AWS CLI erstellen möchten, rufen Sie folgenden put-integration-response-Befehl auf:

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. 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 einen vorhandenen selectionPattern-Wert mithilfe der AWS CLI aktualisieren möchten, rufen Sie die Operation update-integration-response auf und ersetzen Sie den /selectionPattern-Pfadwert durch den angegebenen regulären Ausdruck des Malformed*-Musters.

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

Anstatt einen Standardfehler wie oben beschriebenen auszugeben, können Sie in AWS Lambda ein benutzerdefiniertes Fehlerobjekt als JSON-Zeichenfolge zurückgeben. Der Fehler kann ein beliebiges gültiges JSON-Objekt sein. Beispielsweise gibt die folgende JavaScript (Node.js)-Lambda-Funktion 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 nur für Text-zu-Header-Mappings bei benutzerdefinierten Lambda-Fehlermeldungen – sie gilt jedoch nicht für Text-zu-Text-Zuweisungen mit $input.body. Mit diesen Text-zu-Header-Mappings bei benutzerdefinierten Fehlermeldungen erhält der Client die folgenden Header als Teil der Methodenantwort (vorausgesetzt, die Header error_status, error_trace, error_trace_function und error_type wurden in der Methodenanforderung deklariert):

"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.