Lambda-Fehler in API Gateway behandeln

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.

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.

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 das folgende 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.

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 Eigenschaft fest, die dem angegebenen HTTP-Statuscode IntegrationResponsezugeordnet ist. In der API-Gateway-Konsole wird dieses selectionPattern im Abschnitt Integrationsantwort unter jeder Integrationsantwort als Lambda-Fehler-Regex ausgewiesen.

Verwenden Sie beispielsweise Folgendes, put-integration-responseum 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. Andernfalls gibt API Gateway zur Laufzeit eine ungültige Konfigurationsfehler-Antwort aus.

Um einen vorhandenen selectionPattern Wert mithilfe von zu aktualisieren AWS CLI, rufen Sie die update-integration-responseOperation 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.