API Gateway：Gunakan parameter dan ekspresi kondisional

2. Definisi Parameter

2.1 Metode definisi

Sebelum menggunakan ekspresi kondisional, Anda harus secara eksplisit mendefinisikan semua parameter yang diperlukan dalam bidang parameters. Contohnya:

---
parameters:
  method: "Method"
  appId: "System:CaAppId"
  action: "Query:action"
  userId: "Token:UserId"

Bidang parameters berisi pasangan kunci-nilai bertipe string. kunci dan nilai didefinisikan sebagai berikut:

• kunci: Nama variabel yang digunakan dalam ekspresi kondisional. Nama tersebut harus unik dan mengikuti format [a-zA-Z_][a-zA-Z0-9]+.

• nilai: Lokasi suatu parameter. Definisikan lokasi dalam format {lokasi} atau {lokasi}:{nama}. Contohnya:

  • lokasi: Lokasi suatu parameter. Untuk informasi lebih lanjut, lihat bagian berikutnya.

  • nama: Nama suatu parameter. Gunakan nama ini untuk menemukan parameter pada lokasi tertentu. Misalnya, Query:q1 menunjukkan nilai pertama dari parameter bernama q1 dalam string kueri.

2.2 Lokasi parameter

Sebelum menggunakan ekspresi kondisional, Anda harus mendefinisikan parameter yang diperlukan dalam ekspresi tersebut. Tabel berikut menjelaskan parameter pada lokasi tertentu yang dapat digunakan oleh plug-in API Gateway.

Catatan Penggunaan Lokasi Parameter

• Plugin kontrol akses berbasis parameter, plugin pembentukan lalu lintas, dan plugin perutean backend berjalan selama fase permintaan. Plugin-plugin ini hanya mendukung parameter dari lokasi permintaan berikut: Method, Path, Header, Query, Form, Parameter, System, Token, dan XFF.

• Plugin pemetaan kode kesalahan berjalan selama fase respons. Plugin ini hanya mendukung parameter dari lokasi respons berikut: StatusCode, ErrorCode, Header, BodyJsonField, System, dan Token.

• Untuk lokasi Method, Path, StatusCode, ErrorCode, dan XFF, Anda hanya perlu menyediakan lokasi. Nama tidak diperlukan.

• Saat parameter pada lokasi Header digunakan dalam plug-in selama fase permintaan, plug-in membaca header dari permintaan klien. Saat digunakan dalam plug-in selama fase respons, plug-in membaca header dari respons backend.

• Parameter pada lokasi Parameter hanya digunakan dalam plug-in selama fase permintaan. Sistem mencari parameter dengan nama yang sama dalam definisi API menggunakan nama parameter, bukan nama parameter backend. Jika parameter tidak ada, null dikembalikan.

• Parameter pada lokasi Host hanya didukung untuk ekstraksi parameter nama domain wildcard. Untuk informasi selengkapnya, lihat Gunakan nama domain kustom untuk memanggil API. Untuk mengambil host lengkap, gunakan parameter sistem System:CaDomain.

• Parameter Path menentukan jalur permintaan lengkap. Jika Path berisi parameter, definisikan parameter tersebut dalam bagian Parameter.

• Parameter pada lokasi BodyJsonField saat ini hanya didukung dalam plugin pemetaan kode kesalahan. Gunakan ekspresi JSONPath untuk membaca nilai dari badan respons JSON. Untuk informasi selengkapnya, lihat Catatan penggunaan JSONPath.

• Token: Jika plugin autentikasi JWT dikonfigurasi, Anda dapat menggunakan Token:{ClaimName} untuk membaca nilai yang ditentukan dalam plug-in. Untuk informasi selengkapnya, lihat dokumentasi plug-in terkait.

2.3 Catatan penggunaan JSONPath

Anda dapat menggunakan ekspresi JSONPath pada lokasi BodyJsonField untuk mengekstraksi bidang JSON dari badan JSON respons backend. Fitur ini hanya didukung untuk plugin pemetaan kode kesalahan. Untuk informasi selengkapnya tentang JSONPath, lihat dokumentasi JSONPath.

• Contoh: Gunakan code:"BodyJsonField:$.result_code" untuk mengambil nilai result_code dari badan respons berikut. Hasil yang diurai adalah code: ok.

{ "result_code": "ok", "message": ... }

2.4 Parameter sistem

3. Ekspresi kondisional

Anda dapat menggunakan ekspresi kondisional dalam plug-in dan skenario lain untuk melakukan evaluasi kondisional yang fleksibel.

3.1 Sintaksis

• Ekspresi kondisional mirip dengan ekspresi SQL. Contohnya: $A > 100 and $B = 'B'.

• Format dasar ekspresi adalah {parameter} {operator} {parameter}. Contohnya, dalam $A > 100, parameter dapat berupa variabel atau konstanta.

• Variabel diawali dengan $ dan mereferensikan parameter yang didefinisikan dalam konteks. Misalnya, jika parameter q1:"Query:q1" didefinisikan dalam parameters, Anda dapat menggunakan variabel $q1 dalam ekspresi. Nilai variabel ini adalah nilai parameter kueri bernama q1 dalam permintaan saat ini.

• Konstanta dapat berupa tipe string, angka, atau Boolean, seperti "Hello", 'foo', 100, -1, 0,1, atau true. Untuk informasi selengkapnya, lihat Tipe parameter dan aturan penilaian.

• operator berikut ini didukung:

• Operator = dan ==: sama dengan.

• <> dan !=: tidak sama dengan.

• >, >=, <, dan <=: perbandingan.

• like dan !like: pemeriksaan kemiripan. Karakter wildcard % di awal atau akhir string dapat digunakan untuk memeriksa kemiripan string. Contohnya: $Query like 'Prefix%'.

• in_cidr dan !in_cidr: memeriksa apakah alamat IP berada dalam blok CIDR tertentu. Contohnya: $ClientIp in_cidr '47.89.XX.XX/24'.

• Gunakan null untuk memeriksa apakah parameter kosong. Contohnya: $A == null atau $A != null.

• Gunakan and, or, dan xor untuk menggabungkan ekspresi yang berbeda. Urutan evaluasi default adalah dari kanan ke kiri.

• Gunakan tanda kurung ( dan ) untuk menentukan prioritas kondisi.

• Gunakan !( dan ) untuk melakukan operasi NOT pada ekspresi yang diapit. Contohnya, hasil dari !(1=1) adalah false.

• Sistem memiliki fungsi bawaan untuk evaluasi dalam skenario khusus.

  • Random(): Menghasilkan bilangan titik mengambang antara 0 dan 1. Fungsi ini digunakan dalam skenario yang memerlukan keacakan, seperti penyebaran biru-hijau.

  • Timestamp(): Mengembalikan timestamp Unix dalam milidetik.

  • TimeOfDay(): Mengembalikan jumlah milidetik yang telah berlalu sejak tengah malam hari ini dalam zona waktu GMT.

3.2 Jenis nilai dan aturan penilaian

• Jenis nilai berikut didukung dalam ekspresi:

  • STRING: Tipe string. Anda dapat menggunakan tanda kutip tunggal atau ganda. Contohnya: "Hello", 'Hello'.

  • NUMBER: Tipe bilangan bulat atau bilangan titik mengambang. Contohnya: 1001, -1, 0,1, -100,0.

  • BOOLEAN: Tipe Boolean. Contohnya: true, false.

• Untuk operator sama dengan, tidak sama dengan, dan perbandingan, aturan evaluasi untuk tipe yang berbeda adalah sebagai berikut:

  • STRING: Menggunakan urutan string untuk evaluasi. Contohnya:

    • Hasil dari '123' > '1000' adalah true.

    • Hasil dari 'A123' > 'A120' adalah true.

    • Hasil dari '' < 'a' adalah true.

  • NUMBER: Dievaluasi berdasarkan nilai numerik.

    • Hasil dari 123 > 1000 adalah false.

    • Hasil dari 100.0 == 100 adalah true.

  • BOOLEAN: Aturan evaluasi untuk nilai Boolean adalah bahwa true lebih besar dari false.

    • Hasil dari true == true adalah true.

    • Hasil dari false == false adalah true.

    • Hasil dari true > false adalah true.

• Untuk operator sama dengan, tidak sama dengan, dan perbandingan, jika tipe parameter operan kiri dan kanan berbeda, aturan evaluasi berikut berlaku:

  • STRING NUMBER: Jika operan kiri dapat dikonversi ke tipe NUMBER, nilai dibandingkan secara numerik. Jika tidak, dibandingkan sebagai string. Contohnya:

    • Hasil dari '100' = 100.0 adalah benar.

    • Hasil dari '-100' > 0 adalah false.

  • STRING BOOLEAN: Jika operan kiri dapat dikonversi ke tipe BOOLEAN (sama dengan true atau false tanpa memperhatikan huruf besar/kecil), perbandingan didasarkan pada tipe BOOLEAN. Jika tidak, kecuali untuk perbandingan !=, hasil semua perbandingan lainnya adalah false. Contohnya:

    • Hasil dari 'True' = true adalah true.

    • Hasil dari 'False' = false adalah true.

    • Hasil dari 'bad' = false adalah false.

    • Hasil dari 'bad' != false adalah true. Untuk operan kiri yang bukan true atau false, hanya operator != yang mengembalikan true. Semua operator perbandingan lainnya mengembalikan false.

    • Hasil dari 'bad' != true adalah true.

    • Hasil dari '0' > false adalah false.

    • Hasil dari '0' <= false adalah false.

  • NUMBER BOOLEAN: Selalu mengembalikan false.

• Nilai null dapat digunakan untuk memeriksa apakah suatu bidang kosong. Untuk operator sama dengan, tidak sama dengan, dan perbandingan, aturan evaluasi adalah sebagai berikut:

  • Saat parameter $A kosong, hasil dari $A == null adalah true, dan hasil dari $A != null adalah false.

  • String kosong '' tidak sama dengan null. Hasil dari '' == null adalah false, dan hasil dari '' == '' adalah true.

  • Untuk operator perbandingan, jika salah satu operan adalah null, hasilnya adalah false.

• Operator like dan !like dapat digunakan untuk memeriksa awalan, akhiran, dan inklusi string. Aturan evaluasi adalah sebagai berikut:

  • Ekspresi hanya mendukung konstanta STRING sebagai operan kanan. Contohnya: $Path like '/users/%'.

  • Karakter '%' dapat digunakan di awal atau akhir operan kanan untuk mendukung pemeriksaan awalan, akhiran, dan inklusi. Contohnya:

    • Pemeriksaan awalan: $Path like '/users/%', $Path !like '/admin/%'.

    • Pemeriksaan akhiran: $q1 like '%search', $q1 !like '%.do'.

    • Pemeriksaan inklusi: $ErrorCode like '%400%', $ErrorCode !like '%200%'.

  • Jika operan kiri bukan tipe NUMBER atau BOOLEAN, akan dikonversi ke format STRING sebelum evaluasi.

  • Jika operan kiri adalah null, hasilnya adalah false.

• Ekspresi in_cidr dan !in_cidr dapat digunakan untuk memeriksa apakah alamat IP berada dalam blok CIDR. Aturan evaluasi adalah sebagai berikut:

  • Ekspresi hanya mendukung konstanta STRING dalam format CIDR IPv4 atau IPv6 sebagai operan kanan. Contohnya:

    • $ClientIP in_cidr '10.0.0.0/8'

    • $ClientIP !in_cidr '0:0:0:0:0:FFFF::/96'

  • Jika operan kiri bertipe STRING, dievaluasi sebagai alamat IP.

  • Jika operan kiri bertipe NUMBER atau BOOLEAN, atau kosong, hasilnya adalah false.

  • Parameter System:CaClientIp mengembalikan alamat IP klien dan biasanya digunakan untuk jenis evaluasi ini.

Random() < 0.05

parameters:
  stage: "System:CaStage"

$CaStage = 'TEST'

parameters:
  UserName: "Token:UserName"
  ClientIp: "System:CaClientIp"

$UserName = 'Admin' and $CaClientIp in_cidr '47.47.XX.XX/24'

parameters:
  CaAppId: "System:CaAppId"
  HttpSchema: "System:CaHttpSchema"

$CaHttpScheme = 'HTTPS' and ($CaAppId = 1001 or $CaAppId = 1098 or $CaAppId = 2011)`

parameters:
  StatusCode: "StatusCode"
  ResultCode: "BodyJsonField:$.result_code"

$StatusCode = 200 and ($ResultCode <> null and $ResultCode <> 'ok')