Common Expression Language (CEL) adalah
bahasa non-Turing lengkap open source yang menerapkan semantik umum untuk
evaluasi ekspresi. Ekstensi Layanan menggunakan subset kondisi CEL untuk membuat keputusan evaluasi rantai berdasarkan data atribut. Secara
umum, ekspresi kondisi terdiri dari satu atau beberapa pernyataan yang digabungkan
oleh operator logis (&&, ||, atau !).
Atribut
Untuk setiap permintaan koneksi tertentu, proxy mengekstrak atribut,
yang merupakan sekumpulan informasi kontekstual. Atribut memiliki jenis tetap (seperti
string atau int), dan mungkin tidak ada atau ada, bergantung pada konteksnya.
Atribut diekspos ke runtime CEL selama pemrosesan kondisi kecocokan.
Atribut tidak tersedia untuk dikirim ke layanan ekstensi.
Atribut permintaan
Atribut berikut dapat diekstrak dari permintaan:
| Atribut | Jenis atribut | Deskripsi |
|---|---|---|
request.headers |
map{string,string} | Peta string-ke-string dari header permintaan HTTP. Jika header berisi beberapa nilai, nilai dalam peta ini adalah string yang dipisahkan koma dari semua nilai header. Kunci dalam peta ini menggunakan huruf kecil. |
request.method |
string | Metode permintaan HTTP, seperti GET atau POST. |
request.host |
string | Kemudahan yang setara dengan request.headers['host'].
|
request.path |
string | Jalur URL HTTP yang diminta. |
request.query |
string | Kueri URL HTTP dalam format
Tidak ada decoding yang dijalankan. |
request.scheme |
string | Skema URL HTTP, seperti HTTP atau HTTPS. Nilai untuk atribut ini berupa huruf kecil. |
request.backend_service_name |
string | Layanan backend yang menjadi tujuan penerusan permintaan. Tidak berlaku untuk ekstensi edge. |
request.backend_service_project_number |
int | Saat menggunakan VPC Bersama, nomor project layanan backend yang meneruskan permintaan. Tidak berlaku untuk ekstensi edge. |
Atribut koneksi
Atribut berikut dapat diekstrak dari koneksi:
| Atribut | Jenis atribut | Deskripsi |
|---|---|---|
source.ip |
string | Alamat IP sumber permintaan. |
source.port |
int | Port koneksi klien hilir. |
connection.sni |
string | Nama server yang diminta dari koneksi TLS hilir. |
connection.tls_version |
string | Versi TLS dari koneksi TLS hilir. Nilai yang valid:
TLSv1, TLSv1.1, TLSv1.2, dan
TLSv1.3.
|
connection.sha256_peer_certificate_digest |
string | Hash SHA256 berenkode heksadesimal dari sertifikat peer dalam koneksi TLS hilir, jika ada. |
Operator
Ekstensi Layanan mendukung beberapa operator yang dapat Anda gunakan
untuk membuat kondisi kecocokan yang kompleks dari pernyataan ekspresi sederhana.
Ekstensi Layanan mendukung
operator logis, seperti &&, ||, dan !, serta operator manipulasi string, seperti x.contains('y').
Operator manipulasi string mencocokkan string atau substring yang Anda tentukan. Misalnya, request.host.endsWith('.example.com') dievaluasi ke true jika permintaan HTTP dibuat ke domain yang berakhiran example.com.
Operator logika memungkinkan Anda memverifikasi beberapa variabel dalam ekspresi
bersyarat. Misalnya,
request.method == 'GET' && request.host.matches('.example.com') menggabungkan dua
pernyataan dan mengharuskan kedua pernyataan tersebut true untuk menghasilkan
hasil keseluruhan true.
Operator logika
Tabel berikut menjelaskan operator logika yang didukung Ekstensi Layanan.
| Contoh ekspresi | Deskripsi |
|---|---|
x == "foo" |
Menampilkan true jika x sama dengan argumen
literal string konstan. |
x == R"fo'o" |
Menampilkan true jika x sama dengan literal string raw yang diberikan
yang tidak menafsirkan urutan escape. Literal string
raw berguna untuk mengekspresikan string yang harus
menggunakan karakter urutan escape dalam kode. |
x == y |
Menampilkan true jika x sama dengan
y. |
x != y |
Menampilkan true jika x tidak sama dengan
y. |
x && y |
Menampilkan true jika x dan y
adalah true. |
x || y |
Menampilkan true jika x, y, atau keduanya
adalah true. |
!x |
Menampilkan true jika nilai boolean x adalah
false, atau menampilkan false jika nilai boolean
x adalah true. |
m['k'] |
Jika kunci k ada, menampilkan nilai pada kunci
k dalam peta string-ke-string m. Jika kunci
k tidak ada, menampilkan error yang
menyebabkan aturan yang sedang dievaluasi tidak cocok. |
Operator manipulasi string
Tabel berikut menjelaskan operator manipulasi string yang didukung oleh Ekstensi Layanan.
| Ekspresi | Deskripsi |
|---|---|
x.contains(y) |
Menampilkan true jika string x berisi
substring y. |
x.startsWith(y) |
Menampilkan true jika string x dimulai dengan
substring y. |
x.endsWith(y) |
Menampilkan true jika string x diakhiri dengan
substring y. |
x.matches(y) |
Menampilkan Ekstensi Layanan menggunakan opsi RE2::Latin1 saat mengompilasi pola RE2, yang menonaktifkan fitur Unicode. Ekstensi Edge memungkinkan Anda menggunakan hanya satu ekspresi reguler per ekspresi CEL. |
x.lower() |
Menampilkan nilai huruf kecil dari string x. |
x.upper() |
Menampilkan nilai huruf besar dari string x. |
int(x) |
Mengonversi hasil string x menjadi jenis int. Anda dapat menggunakan string yang dikonversi untuk perbandingan bilangan bulat menggunakan
operator aritmatika standar, seperti lebih besar dari (>)
dan kurang dari atau sama dengan (≤).
Cara ini hanya berfungsi untuk nilai yang dapat berupa bilangan bulat. |
Contoh ekspresi
Cocokkan semua permintaan ke host example.com dengan layanan backend bs1 di 123
sebagai tujuan akhir:
request.host == "example.com" && request.backend_service_name == "bs1" && request.backend_service_project_number == 123
Mencocokkan semua permintaan untuk jalur */inventory dengan header HTTP Hello:
request.path.endsWith("/inventory") && request.headers["Hello"] != ""
Batasan
Batasan berikut berlaku untuk ekspresi CEL saat ditentukan untuk Ekstensi Layanan:
- Ekspresi maksimum per ekstensi: 1 untuk ekstensi edge dan 5 untuk ekstensi lainnya
- Jumlah maksimum karakter per ekspresi reguler: 100
- Jumlah karakter maksimum per ekspresi CEL: 500