Kebijakan dan plugin - API Gateway - Alibaba Cloud Documentation Center

AI Gateway memungkinkan Anda menambahkan kebijakan dan mengonfigurasi plugin di tingkat API untuk meningkatkan keamanan, kinerja, dan kemudahan pemeliharaan API Anda.

Penting

Perubahan konfigurasi kebijakan berlaku segera. Anda tidak perlu menerbitkan ulang API.

Prosedur

Buka halaman Instance di konsol AI Gateway. Di bilah navigasi atas, pilih wilayah tempat instans target Anda berada, lalu klik ID instance tersebut.
Di panel navigasi sebelah kiri, klik Model API, lalu klik nama API target untuk membuka halaman API Details.
Klik tab Policies and Plug-ins. Di bagian More policies and plugins, pilih lokasi tempat Anda ingin mengonfigurasi kebijakan atau plugin (Inbound Processing/Outbound Processing), lalu klik Enable Policy/Plug-in.
Di panel Enable Policy/Plug-in, pilih dan konfigurasi kebijakan atau plugin. Untuk informasi lebih lanjut, lihat Konfigurasi kebijakan dan Konfigurasi plugin.

Konfigurasi kebijakan

Kontrol konkurensi

Kontrol konkurensi melindungi layanan backend Anda dengan membatasi jumlah permintaan simultan. Gerbang menghitung permintaan yang sedang diproses, dan ketika jumlah ini mencapai ambang batas tertentu, gerbang segera memblokir lalu lintas berikutnya untuk mencegah layanan backend kelebihan beban dan memastikan ketersediaannya.

Prosedur

Di tab Add Policy, klik kartu Concurrency Control. Di panel Add Policy, konfigurasi parameter berikut.

Parameter			Deskripsi
Enable or Not			Jika diaktifkan, aturan kontrol konkurensi akan berlaku.
Overall Concurrency Threshold			Tetapkan Overall Concurrency Threshold.
Web Fallback Behavior	Return Specific Content	HTTP Status Code	Tetapkan HTTP Status Code. Nilai default-nya adalah 429.
		Type of Returned Content	Menentukan apakah Type of Returned Content berupa Regular Text atau JSON.
		HTTP Text	Konten badan respons yang dikembalikan saat ambang batas terlampaui.
	Return Specific Content	Redirect URL	Masukkan Redirect URL.

Traffic shaping

Traffic shaping memantau jumlah permintaan per detik (QPS) suatu API. Ketika QPS mencapai ambang batas tertentu, gerbang segera memblokir lalu lintas. Hal ini mencegah lonjakan lalu lintas mendadak yang dapat membebani layanan backend dan memastikan ketersediaan tinggi.

Prosedur

Di tab Add Policy, klik kartu Traffic Shaping. Di panel Add Policy, konfigurasi parameter berikut.

Parameter			Deskripsi
Enable or Not			Jika diaktifkan, aturan traffic shaping akan berlaku.
Overall QPS Threshold			Tetapkan Overall QPS Threshold.
Web Fallback Behavior	Return Specific Content	HTTP Status Code	Tetapkan HTTP Status Code. Nilai default-nya adalah 429.
		Type of Returned Content	Menentukan apakah Type of Returned Content berupa Regular Text atau JSON.
		HTTP Text	Konten badan respons yang dikembalikan saat ambang batas terlampaui.
	Redirect to Specified Page	Redirect URL	Masukkan Redirect URL.

Kebijakan pemutusan sirkuit

Kebijakan pemutusan sirkuit melindungi layanan backend Anda dengan memantau waktu respons atau rasio kesalahan layanan tersebut. Ketika ambang batas tertentu terlampaui, gerbang "memutus sirkuit" dan berhenti mengirim permintaan ke layanan selama durasi yang ditentukan. Tindakan ini mencegah kegagalan berantai dan memastikan ketersediaan tinggi. Setelah durasi berakhir, gerbang secara hati-hati melanjutkan pengiriman permintaan ke resource tersebut.

Prosedur

Di tab Add Policy, klik kartu Circuit Breaking. Di panel Add Policy, konfigurasi parameter berikut.

Parameter			Deskripsi
Enable or Not			Jika diaktifkan, aturan pemutusan sirkuit akan berlaku.
Statistical Window Duration			Durasi jendela waktu untuk mengumpulkan statistik permintaan. Nilai yang valid berkisar dari 1 detik hingga 120 menit.
Minimum Number of Requests			Jumlah minimum permintaan dalam jendela statistik yang diperlukan untuk mengevaluasi aturan pemutusan sirkuit. Jika jumlah permintaan di bawah nilai ini, sirkuit tidak akan terputus meskipun ambang batas terlampaui.
Threshold Type			Pilih apakah akan menggunakan Slow Call Ratio (%) atau Exception Ratio (%) sebagai ambang batas. Jika Anda memilih Slow Call Ratio (%), Anda juga harus menentukan Slow Call RT (waktu respons). Permintaan dihitung sebagai slow call jika waktu responsnya melebihi nilai ini. Saat aturan diaktifkan, sirkuit terputus jika jumlah permintaan dalam jendela statistik melebihi Minimum Number Of Requests dan rasio slow call melebihi ambang batas. Saat terputus, semua permintaan berikutnya langsung gagal selama durasi yang dikonfigurasi. Setelah periode ini, sirkuit masuk ke status half-open dan mengizinkan satu permintaan probing. Jika permintaan ini berhasil (waktu respons kurang dari Slow Call RT), sirkuit menutup dan operasi normal dilanjutkan. Jika gagal, sirkuit terputus lagi. Jika Anda memilih Exception Ratio (%), Anda harus menentukan rasio kesalahan yang memicu pemutusan sirkuit. Sirkuit terputus jika dua kondisi terpenuhi dalam jendela statistik: jumlah permintaan melebihi minimum, dan rasio kesalahan melebihi ambang batas yang ditentukan. Saat terputus, permintaan berikutnya langsung gagal selama durasi yang dikonfigurasi.
Slow Call RT			Tetapkan Slow Call RT yang diizinkan (waktu respons maksimum).
Circuit Breaking Ratio Threshold			Rasio slow call yang memicu pemutusan sirkuit. Nilai yang valid: 0 hingga 100 (mewakili 0% hingga 100%).
Circuit Breaking Duration (s)			Durasi, dalam detik, sirkuit tetap terbuka setelah terputus. Selama periode ini, semua permintaan ke resource tersebut langsung gagal.
Web Fallback Behavior	Return Specific Content	HTTP Status Code	Tetapkan HTTP Status Code. Nilai default-nya adalah 429.
		Type of Returned Content	Menentukan apakah Type of Returned Content berupa Regular Text atau JSON.
		HTTP Text	Konten badan respons yang dikembalikan saat ambang batas terlampaui.
	Redirect to Specified Page	Redirect URL	Masukkan Redirect URL.

Kebijakan daftar hitam dan putih IP

Kebijakan daftar hitam dan putih IP mengontrol akses klien ke layanan Anda berdasarkan daftar alamat IP yang telah dikonfigurasi sebelumnya—alamat yang diizinkan (daftar putih) atau ditolak (daftar hitam).

Prosedur

Di tab Add Policy, klik kartu IP Blacklist/Whitelist. Di panel Add Policy, konfigurasi parameter berikut.

Parameter	Deskripsi
Enable	Jika diaktifkan, kebijakan daftar hitam dan putih IP akan berlaku.
Name	Nama unik untuk kebijakan ini. Ini membantu identifikasi, terutama saat mengelola beberapa kebijakan.
Remarks	Deskripsi kebijakan untuk membantu identifikasi dan pengelolaan.
Type	Menentukan jenis kontrol akses. Whitelist: Mengizinkan akses hanya dari alamat IP yang ditentukan. Akses dari semua alamat IP lainnya ditolak secara default. Blacklist: Memblokir akses dari alamat IP yang ditentukan. Akses dari semua alamat IP lainnya diizinkan secara default.
IP Address/CIDR Block	Daftar alamat IP atau Blok CIDR yang diterapkan oleh kebijakan ini. Beberapa entri didukung. Contohnya, `192.168.1.1/24`.

Kebijakan timeout

AI Gateway memungkinkan Anda menetapkan timeout di tingkat API, yang menentukan waktu maksimum gerbang menunggu respons dari layanan backend. Jika tidak ada respons yang diterima dalam periode tersebut, gerbang mengembalikan kode status HTTP 504 Gateway Timeout kepada klien.

Prosedur

Di tab Add Policy, klik kartu Timeout. Di panel Add Policy, konfigurasi parameter berikut.

Catatan

Setelah Anda mengonfigurasi dan mengaktifkan kebijakan timeout, verifikasi bahwa aturan timeout berfungsi sesuai harapan untuk layanan Anda.

Parameter

Deskripsi

Enable

Menentukan apakah kebijakan timeout diaktifkan.

Aktifkan: Kebijakan timeout API berlaku.
Nonaktifkan: Kebijakan timeout API dinonaktifkan.

Timeout Period

Menentukan periode timeout untuk API, dalam satuan detik.

Catatan

Jika Anda menetapkan parameter ini ke 0 atau menonaktifkan kebijakan timeout, gerbang akan menunggu respons tanpa batas waktu.

Kebijakan retry

AI Gateway dapat secara otomatis melakukan retry permintaan yang gagal di tingkat API. Anda dapat mengonfigurasi retry agar dipicu oleh kondisi tertentu, seperti kegagalan koneksi, layanan backend tidak tersedia, atau kode status HTTP tertentu.

Kondisi retry API

Ketika layanan backend mengembalikan error 5xx, AI Gateway secara otomatis melakukan retry permintaan yang gagal berdasarkan jumlah retry yang dikonfigurasi.

Kondisi retry untuk HTTP:
- 5xx: Jika layanan backend mengembalikan respons 5xx apa pun, atau jika koneksi terputus, di-reset, atau terjadi read timeout, AI Gateway mencoba melakukan retry permintaan.
  
  Catatan
  Kondisi 5xx mencakup kondisi connect-failure dan refused-stream.
- reset: Jika koneksi terputus, di-reset, atau terjadi read timeout, AI Gateway mencoba melakukan retry permintaan.
- connect-failure: Jika koneksi ke layanan backend tidak dapat dibuat, AI Gateway mencoba melakukan retry permintaan yang gagal.
- refused-stream: Jika layanan backend mereset aliran dengan kode error REFUSED_STREAM, AI Gateway mencoba melakukan retry permintaan.
- retriable-status-codes: Jika kode status HTTP dari respons layanan backend cocok dengan salah satu kode status retry yang ditentukan, AI Gateway mencoba melakukan retry permintaan.
  
  Catatan
  Anda hanya dapat menggunakan kode status retry jika Anda menentukan retriable-status-codes dalam kondisi retry.
Kondisi retry untuk gRPC:
- cancelled: Jika kode status gRPC dalam header respons dari layanan gRPC backend adalah cancelled, AI Gateway mencoba melakukan retry permintaan.
- deadline-exceeded: Jika kode status gRPC dalam header respons dari layanan gRPC backend adalah deadline-exceeded, AI Gateway mencoba melakukan retry permintaan.
- internal: Jika kode status gRPC dalam header respons dari layanan gRPC backend adalah internal, AI Gateway mencoba melakukan retry permintaan.
- resource-exhausted: Jika kode status gRPC dalam header respons dari layanan gRPC backend adalah resource-exhausted, AI Gateway mencoba melakukan retry permintaan.
- unavailable: Jika kode status gRPC dalam header respons dari layanan gRPC backend adalah unavailable, AI Gateway mencoba melakukan retry permintaan.

Prosedur

Di tab Add Policy, klik kartu Retry. Di panel Add Policy, konfigurasi parameter berikut.

Catatan

Setelah Anda mengonfigurasi dan mengaktifkan kebijakan retry, verifikasi bahwa aturan retry berfungsi sesuai harapan untuk layanan Anda.

Parameter	Deskripsi
Enable	Menentukan apakah kebijakan retry diaktifkan. Aktifkan: Kebijakan retry API berlaku. Nonaktifkan: Kebijakan retry API dinonaktifkan. Jika kebijakan ini dinonaktifkan, gerbang menggunakan konfigurasi retry internal default. Jumlah retry adalah 2, dan kondisi retry-nya adalah `connect-failure`, `refused-stream`, `unavailable`, `cancelled`, `non_idempotent`, dan `retriable-status-codes`.
Retry Times	Jumlah maksimum retry untuk permintaan yang gagal. Nilai yang valid: 0 hingga 10. Disarankan menggunakan nilai 2 atau kurang. Jika Anda menetapkan parameter ini ke 0, permintaan yang gagal tidak akan diulang.
Retry Condition	Pilih satu atau beberapa kondisi yang memicu retry.
Retry Status Code	Kode status HTTP spesifik yang memicu retry. Anda dapat menentukan beberapa kode. Penting Anda hanya dapat mengonfigurasi Retry Status Code jika Anda memilih `retriable-status-codes` untuk Retry Condition.

Kebijakan modifikasi header

Fitur modifikasi header memungkinkan Anda mengubah header permintaan sebelum dikirim ke layanan backend, dan header respons sebelum dikembalikan ke klien.

Prosedur

Di tab Add Policy, klik kartu Edit Header. Di panel Add Policy, konfigurasi parameter berikut.

Parameter	Deskripsi
Enable	Menentukan apakah kebijakan modifikasi header diaktifkan. Aktifkan: Jika diaktifkan, gerbang memodifikasi header permintaan dan respons sesuai konfigurasi. Nonaktifkan: Jika dinonaktifkan, gerbang tidak memodifikasi header permintaan atau respons.
Header Type	Pilih jenis header yang akan dimodifikasi. Request: Memodifikasi header permintaan. Response: Memodifikasi header respons.
Operation Type	Pilih operasi yang akan dilakukan. Add: Menambahkan header ke permintaan atau respons. Catatan Jika header sudah ada, nilai baru akan ditambahkan ke nilai yang sudah ada, dipisahkan dengan koma (,). Modify: Memodifikasi header tertentu dalam permintaan atau respons. Catatan Jika header yang ditentukan tidak ada, header tersebut akan ditambahkan dengan kunci dan nilai yang ditentukan. Jika header yang ditentukan sudah ada, nilainya akan ditimpa. Delete: Menghapus header tertentu dari permintaan atau respons.
Header Key	Masukkan nama header permintaan atau respons.
Header Value	Masukkan nilai header permintaan atau respons.

Konfigurasi plugin

Klik tab Add Plug-in.
Di bagian Quick Navigation, temukan plugin yang diinginkan berdasarkan jenis atau dengan mencari namanya, lalu klik kartu plugin tersebut:
- Jika plugin belum diinstal, klik Install and Configure di kotak dialog yang muncul. Kemudian, konfigurasi aturan plugin dan aktifkan.
- Jika plugin sudah diinstal, konfigurasi aturan plugin dan aktifkan di kotak dialog yang muncul.
Klik OK. Anda akan diarahkan ke daftar lampiran API, tempat Anda dapat melihat status lampirannya.

Di daftar lampiran, bagian Inbound Processing menampilkan jwt-auth (dinonaktifkan) dan key-auth (diaktifkan). Bagian Outbound Processing menampilkan key-auth (diaktifkan) dan jwt-auth (dinonaktifkan). Alamat layanan backend adalah test.static. Alur permintaan berjalan dari API front-end, melalui Inbound Processing, ke layanan backend, lalu melalui Outbound Processing.