Menangani kesalahan Lambda di API Gateway

Untuk integrasi kustom Lambda, Anda harus memetakan kesalahan yang dikembalikan oleh Lambda dalam respons integrasi terhadap respons kesalahan HTTP standar untuk klien Anda. Jika tidak, kesalahan Lambda dikembalikan sebagai 200 OK respons secara default dan hasilnya tidak intuitif untuk pengguna API Anda.

Ada dua jenis kesalahan yang dapat dikembalikan Lambda: kesalahan standar dan kesalahan khusus. Di API Anda, Anda harus menangani ini secara berbeda.

Dengan integrasi proxy Lambda, Lambda diperlukan untuk mengembalikan output dari format berikut:

{
  "isBase64Encoded" : "boolean",
  "statusCode": "number",
  "headers": { ... },
  "body": "JSON string"
}

Dalam output ini, statusCode biasanya 4XX untuk kesalahan klien dan 5XX untuk kesalahan server. API Gateway menangani kesalahan ini dengan memetakan kesalahan Lambda ke respons kesalahan HTTP, sesuai dengan yang ditentukan. statusCode Agar API Gateway dapat meneruskan jenis kesalahan (misalnya,InvalidParameterException), sebagai bagian dari respons terhadap klien, fungsi Lambda harus menyertakan header (misalnya,"X-Amzn-ErrorType":"InvalidParameterException") di headers properti.

Menangani kesalahan Lambda standar di API Gateway

AWS LambdaKesalahan standar memiliki format berikut:

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

Di sini, errorMessage adalah ekspresi string dari kesalahan. errorTypeIni adalah kesalahan atau tipe pengecualian yang bergantung pada bahasa. stackTraceIni adalah daftar ekspresi string yang menunjukkan jejak tumpukan yang mengarah ke terjadinya kesalahan.

Misalnya, perhatikan fungsi Lambda berikut JavaScript (Node.js).

export const handler = function(event, context, callback) {
    callback(new Error("Malformed input ..."));
};

Fungsi ini mengembalikan kesalahan Lambda standar berikut, yang berisi Malformed input ... sebagai pesan kesalahan:

{
  "errorMessage": "Malformed input ...",
  "errorType": "Error",
  "stackTrace": [
    "export const handler (/var/task/index.js:3:14)"
  ]
}

Demikian pula, pertimbangkan fungsi Lambda Python berikut, yang memunculkan pesan kesalahan Exception yang sama. Malformed input ...

def lambda_handler(event, context):
    raise Exception('Malformed input ...')

Fungsi ini mengembalikan kesalahan Lambda standar berikut:

{
  "stackTrace": [
    [
      "/var/task/lambda_function.py",
      3,
      "lambda_handler",
      "raise Exception('Malformed input ...')"
    ]
  ],
  "errorType": "Exception",
  "errorMessage": "Malformed input ..."
}

Perhatikan bahwa nilai errorType dan stackTrace properti bergantung pada bahasa. Kesalahan standar juga berlaku untuk objek kesalahan apa pun yang merupakan perpanjangan dari Error objek atau subkelas Exception kelas.

Untuk memetakan kesalahan Lambda standar ke respons metode, Anda harus terlebih dahulu memutuskan kode status HTTP untuk kesalahan Lambda yang diberikan. Anda kemudian menetapkan pola ekspresi reguler pada selectionPattern properti yang IntegrationResponseterkait dengan kode status HTTP yang diberikan. Di konsol API Gateway, ini selectionPattern dilambangkan sebagai regex kesalahan Lambda di bagian Respons Integrasi, di bawah setiap respons integrasi.

catatan

API Gateway menggunakan regex gaya pola Java untuk pemetaan respons. Untuk informasi selengkapnya, lihat Pola dalam Oracle dokumentasi.

Misalnya, untuk mengatur selectionPattern ekspresi baru, menggunakanAWS CLI, panggil put-integration-responseperintah berikut:

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

Pastikan bahwa Anda juga mengatur kode kesalahan yang sesuai (400) pada respon metode. Jika tidak, API Gateway akan menampilkan respons kesalahan konfigurasi yang tidak valid saat runtime.

catatan

Saat runtime, API Gateway mencocokkan kesalahan errorMessage Lambda dengan pola ekspresi reguler pada selectionPattern properti. Jika ada kecocokan, API Gateway mengembalikan kesalahan Lambda sebagai respons HTTP dari kode status HTTP yang sesuai. Jika tidak ada kecocokan, API Gateway mengembalikan kesalahan sebagai respons default atau melempar pengecualian konfigurasi yang tidak valid jika tidak ada respons default yang dikonfigurasi.

Menyetel selectionPattern nilai .* untuk respons yang diberikan berarti mengatur ulang respons ini sebagai respons default. Ini karena pola pemilihan seperti itu akan cocok dengan semua pesan kesalahan, termasuk null, yaitu, pesan kesalahan yang tidak ditentukan. Pemetaan yang dihasilkan mengesampingkan pemetaan default.

Untuk memperbarui selectionPattern nilai yang ada menggunakanAWS CLI, panggil update-integration-responseoperasi untuk mengganti nilai /selectionPattern jalur dengan ekspresi regex yang ditentukan dari pola. Malformed*

Untuk mengatur selectionPattern ekspresi menggunakan konsol API Gateway, masukkan ekspresi di kotak teks regex kesalahan Lambda saat menyiapkan atau memperbarui respons integrasi kode status HTTP yang ditentukan.

Menangani kesalahan Lambda khusus di API Gateway

Alih-alih kesalahan standar yang dijelaskan di bagian sebelumnya, AWS Lambda memungkinkan Anda mengembalikan objek kesalahan kustom sebagai string JSON. Kesalahan dapat berupa objek JSON yang valid. Misalnya, fungsi Lambda berikut JavaScript (Node.js) mengembalikan kesalahan kustom:

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));
};

Anda harus mengubah myErrorObj objek menjadi string JSON sebelum memanggil callback untuk keluar dari fungsi. Jika tidak, myErrorObj dikembalikan sebagai string dari"[object Object]". Saat metode API Anda terintegrasi dengan fungsi Lambda sebelumnya, API Gateway menerima respons integrasi dengan muatan berikut:

{
    "errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}"
}

Seperti halnya respons integrasi apa pun, Anda dapat melewati respons kesalahan ini apa adanya terhadap respons metode. Atau Anda dapat memiliki template pemetaan untuk mengubah payload menjadi format yang berbeda. Misalnya, pertimbangkan template pemetaan tubuh berikut untuk respons metode kode status500:

{
    errorMessage: $input.path('$.errorMessage');
}

Template ini menerjemahkan badan respons integrasi yang berisi string JSON kesalahan kustom ke badan respons metode berikut. Badan respons metode ini berisi objek JSON kesalahan kustom:

{
    "errorMessage" : {
        errorType : "InternalServerError",
        httpStatus : 500,
        requestId : context.awsRequestId,
        trace : {
            "function": "abc()",
            "line": 123,
            "file": "abc.js"
        }
    }
};

Bergantung pada persyaratan API Anda, Anda mungkin perlu meneruskan beberapa atau semua properti kesalahan kustom sebagai parameter header respons metode. Anda dapat mencapai ini dengan menerapkan pemetaan kesalahan kustom dari badan respons integrasi ke header respons metode.

Misalnya, ekstensi OpenAPI berikut mendefinisikan pemetaan darierrorMessage.errorType,,, dan errorMessage.trace properti ke errorMessage.httpStatuserrorMessage.trace.function,,, dan error_type header error_statuserror_trace_function, masing-masing. 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"
          },
          ...
        }
    }
}

Saat runtime, API Gateway melakukan deserialisasi integration.response.body parameter saat melakukan pemetaan header. Namun, deserialisasi ini hanya berlaku untuk body-to-header pemetaan untuk respons kesalahan khusus Lambda dan tidak berlaku untuk pemetaan yang menggunakan. body-to-body $input.body Dengan pemetaan custom-error-body-to -header ini, klien menerima header berikut sebagai bagian dari respons metode, asalkan,, error_status error_traceerror_trace_function, dan error_type header dideklarasikan dalam permintaan metode.

"error_status":"500",
"error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}",
"error_trace_function":"abc()",
"error_type":"InternalServerError"

errorMessage.traceProperti badan respons integrasi adalah properti yang kompleks. Hal ini dipetakan ke error_trace header sebagai string JSON.