API Gateway:Error code mapping plug-in

1. Ikhtisar

Gunakan plug-in ini untuk mengubah respons kesalahan backend menjadi format yang diharapkan oleh klien Anda.

2. Memulai

Pada contoh berikut, backend mengembalikan respons HTTP 200, tetapi badan respons berisi pesan kesalahan dalam bidang JSON.

HTTP 200 OK
Content-Type:application/json

{"req_msg_id":"d02afa56394f4588832bed46614e1772","result_code":"ROLE_NOT_EXISTS"}

• Dalam skenario ini, klien mengharapkan respons non-200, yang ingin Anda berikan tanpa mengubah backend.

HTTP 404 
X-Ca-Error-Message: Role Not Exists, ResultId=d02afa56394f4588832bed46614e1772

Untuk menanganinya, konfigurasikan plug-in pemetaan kode kesalahan sebagai berikut.

---
# Bidang yang terlibat dalam pemetaan
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# Kondisi pemetaan
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# Bidang kode kesalahan
errorCode: "resultCode"
# Item pemetaan
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# Pemetaan default (opsional)
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

Pada contoh ini, kondisi pemetaan didasarkan pada kode respons backend dan bidang result_code dalam badan respons JSON. Pemetaan kode kesalahan dipicu jika kode respons backend adalah 200 tetapi bidang result_code bukan 'OK'. Nilai bidang result_code digunakan sebagai kode kesalahan untuk pemetaan. Dua kode kesalahan dikonfigurasi: ROLE_NOT_EXISTS mengembalikan respons 404 ke klien, dan INVALID_PARAMETER mengembalikan respons 400. Semua kode kesalahan lainnya mengembalikan respons 500.

3. Konfigurasi plug-in dan aturan pemetaan

3.1. Konfigurasi plug-in

Konfigurasikan plug-in pemetaan kesalahan dalam format json atau yaml. Bidang konfigurasinya adalah:

• parameters (Wajib): Parameter yang digunakan untuk pemetaan. Parameter ini dikonfigurasi sebagai peta. Untuk informasi lebih lanjut, lihat Menggunakan Parameter dan Ekspresi Kondisional.

• errorCondition (Wajib): Ekspresi kondisional yang menentukan apakah suatu respons merupakan kesalahan. Jika ekspresi bernilai true, pemetaan akan dieksekusi.

• errorCode (Opsional): Menentukan parameter yang menyediakan kode kesalahan. Nilai parameter ini digunakan untuk mencocokkan bidang code dalam daftar mappings.

• mappings (Wajib): Daftar catatan pemetaan. Gerbang merekonstruksi respons berdasarkan catatan yang cocok dengan kode kesalahan atau kondisi kesalahan. Bidang-bidangnya adalah:

  • code (Opsional): Pengenal unik. Jika Anda mengatur parameter ini, parameter errorCode wajib diisi. Ketika nilai parameter errorCode cocok dengan nilai parameter code ini, catatan pemetaan saat ini dieksekusi.

  • condition (Opsional): Ekspresi kondisional kesalahan. Ketika ekspresi bernilai true, catatan pemetaan saat ini dieksekusi.

  • statusCode (Wajib): Kode status HTTP untuk catatan pemetaan saat ini.

  • errorMessage (Opsional): Pesan kesalahan untuk catatan pemetaan saat ini. Pesan ini muncul di header respons X-Ca-Error-Message dan bidang errorMessage dalam log.

  • responseHeaders (Opsional): Header respons untuk catatan pemetaan saat ini, dikonfigurasi sebagai peta.

  • responseBody (Opsional): Badan respons yang menggantikan badan respons asli untuk catatan pemetaan saat ini.

• defaultMapping (Opsional): Catatan pemetaan default. Jika tidak ada catatan dalam mappings yang cocok, catatan ini digunakan untuk respons.

  • statusCode (Wajib): Kode status HTTP untuk catatan pemetaan saat ini.

  • errorMessage (Opsional): Pesan kesalahan untuk catatan pemetaan saat ini. Pesan ini muncul di header respons X-Ca-Error-Message dan bidang errorMessage dalam log.

  • responseHeaders (Opsional): Header respons untuk catatan pemetaan saat ini, dikonfigurasi sebagai peta.

  • responseBody (Opsional): Badan respons yang menggantikan badan respons asli untuk catatan pemetaan saat ini.

Aturan konfigurasi:

• Parameter yang digunakan dalam ekspresi kondisional untuk mappingCondition dan mappings[].condition harus didefinisikan dalam bidang parameters. Jika tidak, terjadi kesalahan. Untuk informasi lebih lanjut tentang definisi parameter dan ekspresi kondisional, lihat Menggunakan Parameter dan Ekspresi Kondisional.

• Parameter yang digunakan dalam bidang errorCode harus didefinisikan dalam parameters.

• Untuk setiap catatan dalam daftar mappings, Anda harus mengonfigurasi salah satu dari code atau condition. Jika Anda mengonfigurasi code, nilainya harus unik dalam daftar tersebut. Jika Anda mengonfigurasi condition, catatan dievaluasi sesuai urutan yang tercantum. Catatan pertama yang cocok akan dieksekusi.

• Untuk errorMessage dan responseBody, Anda dapat menggunakan format templat seperti "${Code}: ${Message}" untuk mengganti variabel. Nilai parameter diambil dari nilai yang diekstraksi oleh konfigurasi parameters.

• Nilai dalam responseHeaders juga dapat menggunakan format ${Message} untuk penggantian templat.

• Jika responseBody tidak dikonfigurasi, badan respons backend diteruskan.

• Jika responseHeaders tidak dikonfigurasi, header respons backend diteruskan. Jika tidak, pasangan kunci-nilai yang dikonfigurasi akan menggantikan header respons backend. Jika nilai diatur ke '', header yang bersangkutan dihapus.

• Jika defaultMapping tidak dikonfigurasi, respons backend diteruskan tanpa pemetaan kode kesalahan.

3.2. Parameter pemetaan

Parameter pemetaan dikonfigurasi sebagai pasangan kunci-nilai dalam bidang parameters. Kuncinya adalah nama variabel, dan nilainya menggunakan format Location:Name untuk mengambil nilai dari lokasi tertentu dalam respons atau konteks sistem.

---
# Bidang yang terlibat dalam pemetaan
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"

Lokasi berikut tersedia untuk pemetaan kode kesalahan. Untuk informasi lebih lanjut, lihat Menggunakan Parameter dan Ekspresi Kondisional.

• ErrorCode dan ErrorMessage mengambil kode dan pesan kesalahan sistem dari API Gateway. Untuk informasi lebih lanjut, lihat dokumen Tabel Kode Kesalahan.

• Menggunakan BodyJsonField memungkinkan Anda menggunakan JSONPath untuk mengekstrak nilai dari respons JSON backend. Namun, jika badan respons backend melebihi 15.360 byte, parameter ini tidak dapat diekstrak dan mengembalikan nilai null.

3.3. Aturan eksekusi

Plug-in pemetaan kode kesalahan dieksekusi dalam urutan berikut.

1. Plug-in mengambil nilai parameter saat ini dari respons dan konteks sistem berdasarkan daftar parameter yang dikonfigurasi dalam parameters.

2. Plug-in mengeksekusi ekspresi kondisional yang dikonfigurasi dalam errorCondition menggunakan nilai parameter dari langkah 1. Jika ekspresi bernilai true, proses dilanjutkan. Jika bernilai false, plug-in berhenti dan tidak melakukan pemetaan.

3. Jika parameter errorCode dikonfigurasi, plug-in mengambil nilainya dan mencari catatan pemetaan dalam mappings yang nilainya code cocok.

4. Jika tidak ditemukan catatan yang cocok pada langkah 3, plug-in secara berurutan mengevaluasi condition dari setiap catatan pemetaan dalam mappings hingga ditemukan kecocokan.

5. Jika catatan pemetaan cocok pada langkah 3 atau 4, gerbang membuat respons baru berdasarkan konfigurasi catatan tersebut. Jika tidak, gerbang membuat respons berdasarkan konfigurasi defaultMapping.

3.4. Pemetaan kesalahan sistem dan log

• Kesalahan sistem API Gateway dapat terjadi selama pemeriksaan gerbang, validasi, pembatasan kecepatan, dan pemrosesan plug-in. Anda dapat menggunakan parameter ErrorCode untuk memetakan kode kesalahan sistem ini. Misalnya, Anda dapat memetakan respons 429 akibat pembatasan kecepatan menjadi respons 200 untuk klien yang hanya mendukung respons 200. Untuk daftar kode kesalahan sistem, lihat dokumen Tabel Kode Kesalahan.

• Saat terjadi kesalahan sistem, nilai parameter yang diambil dari respons, seperti StatusCode, Header, dan BodyJsonField, bernilai null. Perhatikan hal ini saat menulis ekspresi kondisional. Saat tidak terjadi kesalahan sistem, nilai yang diambil dari lokasi ErrorCode adalah OK.

• Kode kesalahan sistem API Gateway muncul di header respons X-Ca-Error-Code dan bidang errorCode dalam log. Plug-in pemetaan kode kesalahan tidak mengganti nilai ini.

• Bidang statusCode dalam log mencatat kode respons yang dikirimkan gerbang ke klien. Plug-in pemetaan kode kesalahan dapat mengganti nilai ini.

4. Contoh konfigurasi

4.1. Memetakan kode kesalahan dalam badan respons

Pemetaan

---
# Bidang yang terlibat dalam pemetaan
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# Kondisi pemetaan
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# Bidang kode kesalahan
errorCode: "resultCode"
# Item pemetaan
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# Pemetaan default (opsional)
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

4.2. Memetakan badan respons

#
# Contoh ini mengembalikan badan kesalahan JSON kustom ke antarmuka depan.
---
# Tentukan parameter pemetaan
parameters:
  statusCode: "StatusCode"
  resultCode: "Header:X-Ca-Error-Code"
  requestId: "Header:X-Ca-Request-Id"
  errorMessage: "Header:X-Ca-Error-Message"

# Kondisi pemetaan
errorCondition: "$statusCode != 200"
# Bidang kode kesalahan
errorCode: "resultCode"
# Item pemetaan
mappings:
  - code: "I400MH"
    statusCode: 200
    responseHeaders:
        Content-Type: "application/xml"
        X-Ca-Error-Message: ""
        X-Ca-Error-Code: ""
    responseBody: |
        {
            "code":"89",
            "message":"${errorMessage}",
            "resultCode":"${resultCode}"
            
        }

5. Batasan

• Anda dapat mendefinisikan maksimal 16 parameter.

• Setiap ekspresi dapat berisi maksimal 512 karakter.

• Untuk lokasi BodyJsonField, badan respons dibatasi hingga 16.380 byte. Jika badan melebihi ukuran ini, nilai null dikembalikan.

• Ukuran konfigurasi plug-in dibatasi hingga 50 KB.

• Anda dapat mengonfigurasi maksimal 20 catatan pemetaan menggunakan metode condition dalam mappings.