API Gateway:Plugin Tipe Pemetaan Kesalahan

1. Ikhtisar

Plugin tipe Pemetaan Kesalahan digunakan untuk memetakan respons kesalahan backend ke respons kesalahan baru berdasarkan aturan pemetaan yang ditentukan sesuai kebutuhan klien.

2. Panduan Cepat

Contoh berikut menunjukkan respons kesalahan yang dikembalikan oleh backend dari suatu Operasi API. Kode status HTTP adalah 200, tetapi badan respons berisi pesan kesalahan dalam string JSON.

HTTP 200 OK
Content-Type:application/json

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

• Misalkan klien ingin menerima kode status HTTP selain 200 tanpa mengubah konfigurasi backend. Sebagai contoh, klien mengharapkan respons kesalahan berikut:

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

Dalam kasus ini, Anda dapat mengonfigurasi plugin tipe Pemetaan Kesalahan menggunakan sampel berikut dan mengikat plugin tersebut ke Operasi API yang relevan:

---
# Parameter yang terlibat dalam pemetaan.
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# Kondisi pemetaan di mana respons kesalahan perlu dipetakan.
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# Parameter dalam respons kesalahan yang digunakan untuk menentukan kode kesalahan dan memenuhi aturan pemetaan.
errorCode: "resultCode"
# Aturan pemetaan.
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# Opsional. Aturan pemetaan default.
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

Dalam contoh ini, kode status HTTP dan parameter result_code dalam respons kesalahan digunakan untuk mendefinisikan kondisi pemetaan. Jika kode status HTTP dari respons kesalahan adalah 200 dan nilai parameter result_code bukan OK, pemetaan dimulai. Parameter result_code digunakan untuk mendefinisikan aturan pemetaan. Salah satu aturannya adalah jika nilai parameter result_code adalah ROLE_NOT_EXISTS, kode status HTTP asli dipetakan ke 404. Aturan lainnya adalah jika nilai parameter result_code adalah INVALID_PARAMETER, kode status HTTP asli dipetakan ke 400. Aturan pemetaan default juga didefinisikan. Jika nilai parameter result_code bukan salah satu dari nilai sebelumnya, kode status HTTP asli dipetakan ke 500.

3. Konfigurasi Plugin dan Aturan Pemetaan

3.1. Konfigurasi Plugin

Anda dapat mengonfigurasi plugin tipe Pemetaan Kesalahan dalam format JSON atau YAML. Parameter berikut dapat ditentukan:

• parameters: wajib. Parameter yang terlibat dalam pemetaan. Parameter ini ditentukan sebagai pasangan kunci-nilai dalam format map. Untuk informasi tentang cara mendefinisikan parameter dan menulis ekspresi kondisional, lihat Gunakan parameter dan ekspresi kondisional.

• errorCondition: wajib. Kondisi pemetaan di bawah mana respons kesalahan perlu dipetakan. Jika hasil dari ekspresi kondisional adalah true, pemetaan dimulai.

• errorCode: opsional. Parameter dalam respons kesalahan yang digunakan untuk menentukan kode kesalahan dan memenuhi aturan pemetaan. Kode kesalahan yang ditentukan oleh nilai parameter errorCode dibandingkan dengan nilai parameter code dalam aturan pemetaan.

• mappings: wajib. Aturan pemetaan. API Gateway merekonstruksi respons kesalahan berdasarkan aturan pemetaan ini. Aturan pemetaan dapat berisi parameter berikut:

  • code: opsional. Nilai tertentu yang digunakan untuk mengidentifikasi respons kesalahan yang kode kesalahannya ditentukan oleh nilai parameter errorCode sama. Nilai parameter ini harus unik di antara semua aturan pemetaan. Jika kode kesalahan dari respons kesalahan sama dengan nilai parameter code dalam aturan pemetaan saat ini, respons kesalahan dipetakan berdasarkan aturan saat ini.

  • condition: opsional. Kondisi di bawah mana respons kesalahan perlu dipetakan berdasarkan aturan pemetaan saat ini. Jika hasil dari ekspresi kondisional adalah true, respons kesalahan dipetakan berdasarkan aturan saat ini.

  • statusCode: wajib. Kode status HTTP yang menggantikan kode status HTTP asli dari respons kesalahan jika respons kesalahan perlu dipetakan berdasarkan aturan pemetaan saat ini.

  • errorMessage: opsional. Pesan kesalahan yang dikembalikan ke klien setelah pemetaan. Nilai parameter ini diperoleh dari parameter dalam respons kesalahan backend asli dan juga disimpan dalam parameter errorMessage dalam log kesalahan. Dalam respons kesalahan setelah pemetaan, parameter ini ditampilkan sebagai nilai dari field header X-Ca-Error-Message.

  • responseHeaders: opsional. Field header respons yang termasuk dalam respons kesalahan setelah pemetaan jika aturan pemetaan saat ini tercapai. Parameter ini ditentukan sebagai pasangan kunci-nilai dalam format map.

  • responseBody: opsional. Badan respons yang menimpa badan respons asli dari respons kesalahan jika respons kesalahan perlu dipetakan berdasarkan aturan pemetaan saat ini.

• defaultMapping: opsional. Aturan pemetaan default. Jika respons kesalahan tidak mencapai aturan yang didefinisikan dalam parameter mappings, respons kesalahan dipetakan berdasarkan aturan pemetaan default.

  • statusCode: wajib. Kode status HTTP yang menggantikan kode status HTTP asli dari respons kesalahan jika respons kesalahan perlu dipetakan berdasarkan aturan pemetaan default.

  • errorMessage: opsional. Pesan kesalahan yang dikembalikan ke klien setelah pemetaan. Nilai parameter ini diperoleh dari parameter dalam respons kesalahan backend asli dan juga disimpan dalam parameter errorMessage dalam log kesalahan. Dalam respons kesalahan setelah pemetaan, parameter ini ditampilkan sebagai nilai dari field header X-Ca-Error-Message.

  • responseHeaders: opsional. Field header respons yang termasuk dalam respons kesalahan setelah pemetaan jika aturan pemetaan default tercapai. Parameter ini ditentukan sebagai pasangan kunci-nilai dalam format map.

  • responseBody: opsional. Badan respons yang menimpa badan respons asli dari respons kesalahan jika respons kesalahan perlu dipetakan berdasarkan aturan pemetaan default.

Perhatikan hal-hal berikut saat mengonfigurasi plugin tipe Pemetaan Kesalahan:

• Parameter yang digunakan untuk menulis ekspresi kondisional dalam mappingCondition dan mappings[].condition harus didefinisikan dalam parameter parameters. Jika tidak, plugin tidak akan bekerja dan melaporkan kesalahan. Untuk informasi tentang cara mendefinisikan parameter dan menulis ekspresi kondisional, lihat Gunakan parameter dan ekspresi kondisional.

• Nilai parameter errorCode harus merupakan nama parameter yang didefinisikan dalam parameter parameters.

• Saat mengonfigurasi aturan pemetaan, Anda harus menentukan setidaknya salah satu parameter code dan condition. Saat menentukan parameter code, nilai parameter ini harus unik di antara semua aturan pemetaan. Saat menentukan parameter condition, Anda harus menulis ekspresi kondisional dalam urutan yang memenuhi kebutuhan Anda. Ini karena urutan kondisi menentukan prioritas mereka.

• Anda dapat mengganti parameter errorMessage dan responseBody dengan format "${Code}: ${Message}". Nilai parameter Code dan Message dalam format ini harus diperoleh dari parameter yang didefinisikan dalam parameter parameters.

• Anda juga dapat mengganti parameter responseHeaders dengan format ${Message}.

• Jika Anda tidak menentukan parameter responseBody, badan respons dari respons kesalahan yang dikembalikan ke klien setelah pemetaan sama dengan badan respons dari respons kesalahan asli.

• Anda dapat menggunakan parameter responseHeaders untuk menentukan field header dan nilainya untuk mengganti field header yang sesuai dalam respons kesalahan backend. Jika Anda menentukan nilai field header sebagai '', field header ini akan dihapus setelah pemetaan. Jika Anda tidak menentukan parameter ini, field header dari respons kesalahan yang dikembalikan ke klien setelah pemetaan sama dengan field header dari respons kesalahan asli.

• Jika Anda tidak menentukan parameter defaultMapping dan respons kesalahan tidak mencapai aturan pemetaan, respons kesalahan backend asli dikembalikan ke klien.

3.2. Parameter yang terlibat dalam pemetaan

Sebagaimana ditunjukkan dalam potongan kode berikut, Anda harus menentukan parameter yang terlibat dalam pemetaan sebagai pasangan kunci-nilai dalam parameter parameters. Setiap kunci adalah nama parameter. Setiap nilai ditentukan dalam format Location:Name. Format ini menunjukkan bahwa nilai parameter diperoleh dari respons atau konteks sistem.

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

Anda dapat menentukan lokasi berikut saat menggunakan format `Location:Name` untuk mendapatkan nilai parameter. Untuk informasi lebih lanjut tentang lokasi, lihat Gunakan parameter dan ekspresi kondisional.

• Lokasi ErrorCode dan ErrorMessage digunakan untuk mendapatkan kode kesalahan dan pesan kesalahan dalam respons kesalahan sistem di API Gateway. Untuk informasi lebih lanjut, lihat Tabel Kode Kesalahan.

• Lokasi BodyJsonField dapat digunakan untuk mendapatkan string JSON dalam badan respons backend. Namun, jika ukuran badan respons melebihi 16.380 byte, string yang diperoleh adalah

  null.

3.3. Mekanisme Kerja

Berikut adalah langkah-langkah kerja plugin tipe Pemetaan Kesalahan:

• 1. Langkah 1: Berdasarkan daftar parameter yang didefinisikan dalam parameter parameters, peroleh nilai parameter dari respons kesalahan backend dan konteks sistem.

• 1. Langkah 2: Gunakan parameter dan nilai yang diperoleh untuk mengeksekusi ekspresi kondisional yang ditulis dalam parameter errorCondition. Jika hasilnya true, lanjutkan ke langkah berikutnya. Jika hasilnya false, proses berakhir.

• 1. Langkah 3: Jika parameter errorCode ditentukan, peroleh kode kesalahan yang ditentukan oleh nilai parameter errorCode. Kemudian, periksa apakah kode kesalahan sama dengan nilai parameter code dalam aturan pemetaan.

• 1. Langkah 4: Jika tidak ada aturan pemetaan yang tercapai pada langkah 3, eksekusi secara berurutan ekspresi kondisional yang ditulis dalam parameter condition dalam aturan pemetaan.

• 1. Langkah 5: Jika aturan pemetaan tercapai pada langkah 3 atau langkah 4, respons kesalahan asli dipetakan berdasarkan aturan pemetaan. Jika tidak, respons kesalahan asli dipetakan berdasarkan aturan pemetaan default.

3.4. Pemetaan Respons Kesalahan Sistem dan Log Kesalahan

• Di API Gateway, kesalahan sistem dapat terjadi dalam proses seperti pemeriksaan, verifikasi, pembatasan laju, dan operasi plugin. Untuk informasi lebih lanjut, lihat Tabel kode kesalahan. Anda dapat menggunakan ErrorCode sebagai lokasi untuk mendapatkan informasi dalam respons kesalahan sistem. Misalnya, klien hanya mendukung kode status HTTP 200 dan ingin memetakan kode status HTTP 429 yang dikembalikan oleh API Gateway ke kode status HTTP 200.

• Untuk respons kesalahan sistem, nilai yang diperoleh dari lokasi seperti StatusCode, Header, dan BodyJsonField semuanya adalah null. Saat mendefinisikan kondisi pemetaan untuk plugin tipe Pemetaan Kesalahan, perhatikan bahwa untuk respons kesalahan backend, nilai yang diperoleh dari lokasi ErrorCode adalah O.

• Kode kesalahan dari respons kesalahan sistem dikembalikan sebagai nilai dari field header X-Ca-Error-Code dan juga disimpan dalam parameter errorCode dalam log kesalahan. Nilai ini tidak dapat ditimpa menggunakan plugin tipe Pemetaan Kesalahan.

• Parameter statusCode dalam log kesalahan mencatat nilai kode status HTTP yang dikirim dari API Gateway ke klien. Nilai ini dapat ditimpa menggunakan plugin tipe Pemetaan Kesalahan.

4. Contoh Konfigurasi

4.1. Gunakan kode kesalahan dalam respons kesalahan untuk pemetaan kesalahan

Pemetaan

---
# Parameter yang terlibat dalam pemetaan.
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# Kondisi pemetaan di bawah mana respons kesalahan perlu dipetakan.
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# Parameter dalam respons kesalahan yang digunakan untuk menentukan kode kesalahan dan memenuhi aturan pemetaan.
errorCode: "resultCode"
# Aturan pemetaan.
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# Opsional. Aturan pemetaan default.
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

5. Batasan

• Maksimal 16 parameter dapat didefinisikan dalam setiap plugin tipe Pemetaan Kesalahan.

• Setiap ekspresi kondisional dapat berisi maksimal 512 karakter.

• Jika Anda menggunakan lokasi BodyJsonField untuk mendapatkan string JSON dalam badan respons kesalahan, badan respons dapat berukuran maksimal 16.380 byte. Jika ukuran badan respons melebihi batas ini, string yang diperoleh adalah null.

• Untuk setiap plugin tipe Pemetaan Kesalahan, Anda dapat mengonfigurasi maksimal 16.380 byte metadata.

• Untuk setiap plugin tipe Pemetaan Kesalahan, Anda dapat mengonfigurasi maksimal 20 aturan pemetaan menggunakan parameter condition.