All Products
Search

This Product

    API Gateway:Konfigurasikan kebijakan dan plug-in

    Document Center

    API Gateway:Konfigurasikan kebijakan dan plug-in

    Last Updated:Jun 03, 2026

    Cloud-native API Gateway mendukung kebijakan dan plug-in pada tingkat API maupun tingkat operasi guna meningkatkan keamanan, kinerja, dan kemudahan pemeliharaan.

    Penting

    • Perubahan konfigurasi kebijakan berlaku langsung tanpa perlu menerbitkan ulang API.

    • Secara default, konfigurasi plug-in tingkat API berlaku pada tingkat operasi.

    • Anda tidak dapat menghapus kebijakan tingkat API pada tingkat operasi. Namun, kebijakan tingkat operasi dapat menggantikan kebijakan tingkat API.

    Prosedur

    1. Tambahkan kebijakan API dengan salah satu dari dua cara berikut:

      API di luar instans

      1. Masuk ke Konsol Cloud-native API Gateway. Di panel navigasi sebelah kiri, pilih APIs dan pilih wilayah di bilah menu atas.

      2. Klik API yang dituju dan pilih instans tujuan dari daftar drop-down.image

      API dalam instans

      1. Masuk ke Konsol Cloud-native API Gateway. Di panel navigasi sebelah kiri, pilih Instances dan pilih wilayah di bilah menu atas.

      2. Pada halaman Instances, klik ID instans gerbang yang dituju. Di panel navigasi sebelah kiri, pilih APIs, lalu klik API yang dituju.

    2. Anda dapat mengonfigurasi kebijakan dan plug-in pada tingkat API atau tingkat operasi:

      • Tingkat API: Klik tab API Policy Configuration untuk mengonfigurasi kebijakan dan plug-in tingkat API untuk semua operasi. Lalu, klik Enable Policy/Plug-in.

      • Tingkat operasi: Pada tab Operations, klik operasi yang dituju, klik tab Policy Configuration, lalu klik Enable Policy/Plug-in.

    3. Pada panel Enable Policy/Plug-in, pilih dan konfigurasi kebijakan atau plug-in dari bagian Policies atau Plug-ins.

    Policies

    Throttling policy

    Throttling mengontrol volume permintaan per API dan operasi dalam ambang batas yang dikonfigurasi selama periode tertentu. Fitur ini mencegah permintaan eksternal membebani layanan backend dan menghindari kegagalan berantai dengan menolak permintaan berlebih saat konkurensi tinggi.

    Kebijakan throttling mencakup concurrency control, traffic shaping, dan circuit breaking.

    • Concurrency control policy: Membatasi jumlah total permintaan konkuren yang diproses oleh gateway. Saat ambang batas tercapai, permintaan baru akan ditolak. Atur ambang batas sesuai kapasitas backend Anda.

      Prosedur

      Pada halaman Add Policy, klik kartu Concurrency Control. Pada panel Add Policy: Concurrency control, konfigurasikan parameter berikut.

      Parameter

      Deskripsi

      Enable or Not

      Mengaktifkan kebijakan concurrency control.

      Overall Concurrency Threshold

      Atur Overall Concurrency Threshold.

      Web Fallback Behavior

      Return Specific Content

      HTTP Status Code

      Atur HTTP Status Code untuk respons. Nilai default adalah 429.

      Type of Returned Content

      Pilih Type of Returned Content, yaitu Regular Text atau application/json.

      HTTP Text

      Masukkan konten badan respons.

      Return Specific Content

      Redirect URL

      Masukkan Redirect URL.

    • Traffic shaping policy: Memantau queries per second (QPS) untuk API dan operasi. Saat QPS melebihi ambang batas, permintaan baru akan ditolak untuk melindungi layanan backend dari lonjakan traffic.

      Prosedur

      Pada halaman Add Policy, klik kartu Traffic Shaping. Pada panel Add Policy: Traffic shaping, konfigurasikan parameter berikut.

      Parameter

      Deskripsi

      Enable or Not

      Mengaktifkan kebijakan traffic shaping.

      Overall QPS Threshold

      Atur Overall QPS Threshold.

      Web Fallback Behavior

      Return Specific Content

      HTTP Status Code

      Atur HTTP Status Code untuk respons. Nilai default adalah 429.

      Type of Returned Content

      Pilih Type of Returned Content, yaitu Regular Text atau application/json.

      HTTP Text

      Masukkan konten badan respons.

      Redirect to Specified Page

      Redirect URL

      Masukkan Redirect URL.

    • Circuit breaking policy: Memantau waktu respons atau tingkat kesalahan API dan operasi. Saat ambang batas tercapai, pemutus sirkuit aktif dan gagalkan permintaan berikutnya selama periode tertentu untuk mencegah kegagalan berantai. Setelah timeout, gateway memperbolehkan sejumlah kecil permintaan uji untuk memeriksa apakah backend telah pulih.

      Prosedur

      Pada halaman Add Policy, klik kartu Circuit Breaking. Pada panel Add Policy: Circuit breaking, konfigurasikan parameter berikut.

      Parameter

      Deskripsi

      Enable or Not

      Mengaktifkan kebijakan circuit breaking.

      Statistical Window Duration

      Jendela waktu untuk analisis statistik. Nilai valid: 1 detik hingga 120 menit.

      Minimum Number of Requests

      Jumlah minimum permintaan dalam jendela waktu yang diperlukan untuk memicu circuit breaking. Jika jumlah di bawah nilai ini, circuit breaking tidak dipicu meskipun ambang batas tercapai.

      Threshold Type

      Pilih antara Slow Call Ratio (%) atau Exception Ratio (%) sebagai ambang batas.

      1. Jika Anda memilih Slow Call Ratio (%), Anda harus mengatur Slow Call RT (waktu respons maksimum). Permintaan yang melebihi nilai ini dihitung sebagai slow call. Jika rasio slow call melebihi ambang batas dalam jendela waktu (dengan jumlah permintaan yang cukup), circuit breaking dipicu selama durasi yang dikonfigurasi. Sirkuit kemudian masuk ke kondisi half-open: jika permintaan berikutnya memenuhi batas RT, operasi normal dilanjutkan; jika tidak, sirkuit kembali trip.

      2. Jika Anda memilih Exception Ratio (%), atur ambang batas rasio kesalahan. Jika rasio kesalahan melebihi ambang batas dalam jendela waktu (dengan jumlah permintaan yang cukup), circuit breaking dipicu selama durasi yang dikonfigurasi.

      Slow Call RT

      Menentukan Slow Call RT (waktu respons maksimum) yang diizinkan dalam milidetik.

      Circuit Breaking Ratio Threshold

      Ambang batas rasio slow call atau kesalahan. Nilai valid: 0 hingga 100 (0% hingga 100%).

      Circuit breaking duration (s)

      Durasi sirkuit tetap terbuka setelah trip. Permintaan gagal secara cepat selama periode ini.

      Web Fallback Behavior

      Return Specific Content

      HTTP Status Code

      Atur HTTP Status Code untuk respons. Nilai default adalah 429.

      Type of Returned Content

      Pilih Type of Returned Content, yaitu Regular Text atau application/json.

      HTTP Text

      Masukkan konten badan respons.

      Redirect to Specified Page

      Redirect URL

      Masukkan Redirect URL.

    Rewrite policy

    Kebijakan rewrite memodifikasi path permintaan dan header host sebelum diteruskan ke layanan backend, memastikan permintaan mencapai titik akhir yang benar.

    Prosedur

    Pada halaman Add Policy, klik HTTP Rewrite. Pada panel Add Policy: HTTP Rewrite, konfigurasikan parameter.

    • Path rewrite

      Untuk path rewrite, Cloud-native API Gateway mendukung dua mode rewrite berikut.

      • Constant rewrite: Didukung hanya pada tingkat operasi.

      • Regex Rewrite: Didukung pada tingkat operasi maupun tingkat API.

      Constant rewrite

      Constant rewrite memungkinkan Anda mengganti awalan path dari permintaan masuk.

      Contoh 1

      Path permintaan asli adalah /app/test, tetapi path yang diteruskan ke layanan backend harus /test. Konfigurasi yang direkomendasikan adalah:

      • Kondisi pencocokan operasi API: Atur tipe pencocokan ke Prefix Match dan path ke /app/.

      • Aturan rewrite: Atur tipe rewrite ke Constant Rewrite dan path ke /.

      Catatan

      Path pencocokan operasi harus diatur ke /app/ karena constant rewrite hanya mengganti awalan yang cocok. Jika path pencocokan diatur ke /app, path hasil rewrite akan menjadi //test, yang salah.

      Contoh 2

      Path permintaan asli adalah /v1/test, tetapi path yang diteruskan ke layanan backend harus /v2/test. Konfigurasi yang direkomendasikan adalah:

      • Kondisi pencocokan operasi API: Atur tipe pencocokan ke Prefix Match dan path ke /v1.

      • Aturan rewrite: Atur tipe rewrite ke Constant Rewrite dan path ke /v2.

      Penting

      Constant rewrite mengharuskan tipe pencocokan operasi API diatur ke Prefix Match. Tipe Exact Match dan Regex Match tidak mendukung constant rewrite. Karena Prefix Match berlaku untuk semua permintaan yang dimulai dengan awalan tersebut, perhatikan bahwa semuanya akan di-rewrite. Jika Anda memerlukan penargetan yang lebih spesifik, gunakan Regex Rewrite sebagai gantinya.

      Regex rewrite

      Regex rewrite memodifikasi bagian dari path permintaan asli menggunakan pola ekspresi reguler dan string pengganti. Pola mengikuti Regular Expression Syntax.

      Contoh 1

      Path permintaan asli adalah /aaa/one/bbb/one/ccc, tetapi path yang diteruskan ke layanan backend harus /aaa/two/bbb/two/ccc. Konfigurasi yang direkomendasikan adalah:

      • Kondisi pencocokan operasi API: Atur tipe pencocokan ke Exact Match dan path ke /aaa/one/bbb/one/ccc.

      • Aturan rewrite: Atur tipe rewrite ke Regex Rewrite, pola ke one, dan string pengganti ke two.

      Contoh 2

      Path permintaan asli cocok dengan /httpbin/(.*)/(.*). Anda ingin menghapus awalan /httpbin dan menukar posisi dua grup yang ditangkap. Konfigurasi yang direkomendasikan adalah:

      • Kondisi pencocokan operasi API: Atur tipe pencocokan ke Regex Match dan path ke /httpbin/(.*)/(.*).

      • Aturan rewrite: Atur tipe rewrite ke Regex Rewrite, pola ke /httpbin/(.*)/(.*), dan string pengganti ke /\2/\1. Di sini, \1 merepresentasikan grup pertama yang ditangkap dan \2 merepresentasikan grup kedua, mirip dengan sintaksis $1 dan $2 di Nginx.

      Contoh 3

      Untuk API REST versi yang menyertakan versi dalam path, Anda ingin menghapus segmen versi sebelum meneruskan permintaan ke backend. Misalnya, path asli /basePath/version/order/get harus di-rewrite menjadi /basePath/order/get. Konfigurasi yang direkomendasikan adalah:

      • Terapkan kebijakan pada tingkat API menggunakan API Policy Configuration.

      • Aturan rewrite: Atur tipe rewrite ke Regex Rewrite, pola ke (/.*)/version(/.*), dan string pengganti ke \1\2. Di sini, \1 merepresentasikan grup pertama yang ditangkap dan \2 merepresentasikan grup kedua.

      Catatan

      Regex rewrite adalah fitur lanjutan. Gunakan Constant Rewrite bila memungkinkan.

    • Host header rewrite

      Untuk rewrite header host, Cloud-native API Gateway mendukung constant rewrite.

      Sebagai contoh, jika header Host permintaan asli adalah test.com, tetapi layanan backend mengharapkan dev.com, Anda dapat mengatur host rewrite ke dev.com dalam kebijakan rewrite.

    Header modification policy

    Modifikasi header memungkinkan Anda mengubah header permintaan sebelum diteruskan ke backend, atau header respons sebelum dikembalikan ke klien.

    Prosedur

    Pada halaman Add Policy, klik kartu Edit Header. Pada panel Add Policy: Header Modification, konfigurasikan parameter berikut.

    Parameter

    Deskripsi

    Enable

    Mengaktifkan atau menonaktifkan kebijakan modifikasi header.

    • Diaktifkan: Gateway akan memodifikasi header permintaan dan respons sesuai konfigurasi.

    • Dimatikan: Gateway tidak akan memodifikasi header permintaan atau respons.

    Header Type

    Pilih jenis header yang akan dimodifikasi.

    • Request: Memodifikasi header permintaan masuk.

    • Response: Memodifikasi header respons keluar.

    Operation Type

    Pilih aksi yang akan dilakukan.

    • Add: Menambahkan header baru ke permintaan atau respons.

      Catatan

      Jika header dengan nama yang sama sudah ada, nilai baru akan ditambahkan ke nilai yang ada, dipisahkan dengan koma (,).

    • Modify: Mengatur nilai header tertentu dalam permintaan atau respons.

      Catatan

      • Jika header yang ditentukan tidak ada, header tersebut akan ditambahkan.

      • Jika header yang ditentukan sudah ada, nilainya akan ditimpa.

    • Delete: Menghapus header tertentu dari permintaan atau respons.

    Header key

    Masukkan nama header.

    Header value

    Masukkan nilai header.

    CORS policy

    Cross-Origin Resource Sharing (CORS) mengontrol akses ke resource dari origin berbeda (domain, skema, atau port). Konfigurasikan kebijakan CORS pada tingkat API dan operasi untuk menentukan origin dan metode permintaan yang diizinkan.

    Penting

    Kebijakan CORS tidak berlaku untuk layanan mock. Anda harus mengonfigurasi layanan backend aktual untuk pengujian.

    Prosedur

    Pada halaman Add Policy, klik kartu CORS. Pada panel Add Policy: CORS, konfigurasikan parameter berikut.

    Parameter

    Deskripsi

    Enable

    Nyalakan sakelar Enable di sebelah kanan.

    • Diaktifkan: Mengizinkan permintaan lintas asal dari origin pihak ketiga yang dikonfigurasi.

    • Dimatikan: Menolak semua permintaan lintas asal dari origin pihak ketiga mana pun.

    Allowed Origins

    Origin yang diizinkan mengakses resource melalui browser.

    • Izinkan semua sumber akses: *.

    • Izinkan akses dari origin domain root tertentu: *.example.com.

    • Untuk mengizinkan beberapa sumber akses spesifik: Mulai setiap sumber dengan http:// atau https:// dan pisahkan dengan baris baru.

    Catatan

    Parameter ini mengatur header respons Access-Control-Allow-Origin. Jika header Origin dari permintaan masuk cocok dengan nilai dalam daftar ini, header Access-Control-Allow-Origin pada respons diatur ke nilai header Origin permintaan.

    Allowed Methods

    Pilih metode HTTP yang diizinkan untuk permintaan lintas asal. Metode umum termasuk GET, POST, PUT, DELETE, HEAD, OPTIONS, dan PATCH.

    Catatan

    Parameter ini berlaku untuk header Access-Control-Allow-Methods.

    Trusted Request Headers

    Header permintaan yang diizinkan selama permintaan lintas asal, di luar header standar yang didukung browser.

    • Izinkan semua header permintaan: *.

    • Untuk mengizinkan beberapa header spesifik, masukkan setiap nama header pada baris baru.

    Catatan

    Parameter ini berlaku untuk header Access-Control-Allow-Headers.

    Trusted Response Headers

    Header respons yang dapat diakses oleh klien browser.

    • Izinkan semua header respons: *.

    • Untuk mengekspos beberapa header spesifik, masukkan setiap nama header pada baris baru.

    Catatan

    Parameter ini memengaruhi header Access-Control-Expose-Headers.

    Allow to Carry Credentials

    Apakah browser mengirim kredensial (cookie, header otorisasi) bersama permintaan lintas asal.

    Catatan

    Parameter ini berlaku untuk header Access-Control-Allow-Credentials.

    Precheck Expiration Time

    Berapa lama browser menyimpan cache respons preflight (OPTIONS) untuk permintaan tidak sederhana.

    Catatan

    Parameter ini berlaku untuk header Access-Control-Max-Age.

    Traffic replication policy

    Replikasi traffic mencerminkan persentase traffic langsung ke layanan tertentu untuk pengujian simulasi dan diagnosis kesalahan.

    Prosedur

    Pada halaman Add Policy, klik kartu Mirror Traffic. Pada panel Add Policy: Traffic Replication, konfigurasikan parameter berikut.

    Parameter

    Deskripsi

    Enable

    Mengaktifkan atau menonaktifkan kebijakan replikasi traffic untuk API atau operasi.

    Destination Service

    Layanan tempat traffic yang direplikasi diteruskan.

    Catatan

    Layanan tujuan harus menggunakan protokol HTTP atau HTTPS.

    Port

    Port layanan tujuan. Anda juga dapat memilih port dinamis.

    Catatan

    Port dinamis cocok untuk layanan yang port-nya berubah secara dinamis. Opsi ini tidak didukung untuk layanan multi-port.

    Traffic Mirror Percentage

    Persentase traffic yang direplikasi. Nilai valid: 0 hingga 100.

    Catatan

    Jika Anda mengatur parameter ini ke 50, 50% traffic untuk API atau operasi saat ini direplikasi ke layanan tujuan.

    Timeout policy

    Konfigurasikan waktu maksimum yang ditunggu gateway untuk respons backend. Jika tidak ada respons yang diterima dalam waktu tersebut, gateway mengembalikan kesalahan HTTP 504 (Gateway Timeout).

    Prosedur

    Pada halaman Add Policy, klik kartu Timeout. Pada panel Add Policy: Timeout, konfigurasikan parameter berikut.

    Catatan

    Setelah Anda mengonfigurasi dan mengaktifkan kebijakan timeout, verifikasi bahwa perilaku timeout layanan sesuai dengan kebutuhan bisnis Anda.

    Parameter

    Deskripsi

    Enable

    Menentukan apakah kebijakan timeout diaktifkan.

    • Diaktifkan: Kebijakan timeout untuk API atau operasi berlaku.

    • Dimatikan: Kebijakan timeout untuk API atau operasi dinonaktifkan.

    Timeout Period

    Atur durasi timeout untuk API atau operasi, dalam detik.

    Catatan

    Jika diatur ke 0 atau jika kebijakan dinonaktifkan, gateway menunggu respons tanpa batas waktu.

    Retry policy

    Konfigurasikan retry otomatis untuk permintaan yang gagal. Kondisi retry mencakup kegagalan koneksi, ketidaktersediaan backend, dan kode status HTTP tertentu.

    Kondisi retry

    Saat layanan backend mengembalikan kesalahan 5xx, Cloud-native API Gateway secara otomatis melakukan retry permintaan yang gagal sesuai jumlah retry yang dikonfigurasi.

    • Kondisi retry untuk protokol HTTP adalah sebagai berikut:

      • 5xx: Gateway melakukan retry permintaan jika layanan backend mengembalikan respons 5xx apa pun, atau jika koneksi terputus, di-reset, atau timeout.

        Catatan

        5xx mencakup kondisi connect-failure dan refused-stream.

      • reset: Gateway melakukan retry permintaan jika koneksi terputus, di-reset, atau timeout.

      • connect-failure: Gateway melakukan retry permintaan jika gagal karena kegagalan koneksi.

      • refused-stream: Gateway melakukan retry permintaan jika layanan backend mereset stream dengan kode kesalahan REFUSED_STREAM.

      • retriable-status-codes: Gateway melakukan retry permintaan jika kode status HTTP pada respons cocok dengan salah satu kode status yang ditentukan pengguna.

        Catatan

        Kode status retry hanya dapat digunakan jika retriable-status-codes ditentukan dalam kondisi retry.

    • Kondisi retry untuk protokol gRPC adalah sebagai berikut:

      • cancelled: Melakukan retry saat layanan gRPC backend mengembalikan cancelled.

      • deadline-exceeded: Melakukan retry saat layanan gRPC backend mengembalikan deadline-exceeded.

      • internal: Melakukan retry saat layanan gRPC backend mengembalikan internal.

      • resource-exhausted: Melakukan retry saat layanan gRPC backend mengembalikan resource-exhausted.

      • unavailable: Melakukan retry saat layanan gRPC backend mengembalikan unavailable.

    Prosedur

    Pada halaman Add Policy, klik kartu Retry. Pada panel Add Policy: Retry, konfigurasikan parameter berikut.

    Catatan

    Setelah Anda mengonfigurasi dan mengaktifkan kebijakan retry, verifikasi bahwa perilaku retry layanan sesuai dengan kebutuhan bisnis Anda.

    Parameter

    Deskripsi

    Enable

    Menentukan apakah kebijakan retry diaktifkan.

    • Diaktifkan: Kebijakan retry untuk API atau operasi berlaku.

    • Dimatikan: Kebijakan retry untuk API atau operasi dinonaktifkan.

      Meskipun Anda menonaktifkan retry, gateway memiliki konfigurasi retry internal default. Jumlah retry default adalah 2, dan kondisi retry default adalah connect-failure, refused-stream, unavailable, cancelled, dan retriable-status-codes.

    Retry Times

    Jumlah maksimum upaya retry. Nilai valid: 0 hingga 10. Direkomendasikan: 2 atau kurang.

    Nilai 0 menonaktifkan retry.

    Retry Condition

    Kondisi yang memicu retry.

    Retry Status Code

    Kode status HTTP yang memicu retry. Beberapa kode dapat dikonfigurasi.

    Penting

    Anda harus mengatur Retry Condition ke retriable-status-codes untuk mengonfigurasi Retry Status Code.

    Plug-ins

    1. Klik tab Add Plug-in.

    2. Pada bagian Quick Navigation, temukan plug-in target berdasarkan tipe atau nama, lalu klik kartunya.

      • Jika plug-in belum diinstal, klik Install and Configure di kotak dialog. Konfigurasikan aturan dan aktifkan.

      • Jika plug-in sudah diinstal, konfigurasikan aturannya dan aktifkan di kotak dialog.

    3. Klik OK. Anda kembali ke daftar plug-in API, tempat Anda dapat melihat status plug-in baru.

      image