Kebijakan SpikeArrest

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Kebijakan SpikeArrest melindungi dari lonjakan traffic dengan elemen <Rate>. Elemen ini membatasi jumlah permintaan yang diproses oleh proxy API dan dikirim ke backend, sehingga melindungi dari penurunan performa dan periode nonaktif.

Kebijakan ini adalah Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Untuk mengetahui informasi tentang jenis dan ketersediaan kebijakan dengan setiap jenis lingkungan, lihat Jenis kebijakan.

Perbedaan antara SpikeArrest dan Kuota

Kebijakan kuota mengonfigurasi jumlah pesan permintaan yang diizinkan untuk dikirimkan aplikasi klien ke API selama satu jam, hari, minggu, atau bulan. Kebijakan Kuota menerapkan batas konsumsi pada aplikasi klien dengan mempertahankan penghitung terdistribusi yang mencatat permintaan masuk.

Gunakan Kuota untuk menerapkan kontrak bisnis atau SLA dengan developer dan partner, bukan untuk pengelolaan traffic operasional. Gunakan SpikeArrest untuk melindungi dari lonjakan traffic API yang tiba-tiba. Lihat juga Membandingkan kebijakan Kuota dan SpikeArrest.

Video

Video ini membahas kasus penggunaan untuk kebijakan ini:

Mengapa Anda Membutuhkannya

Membandingkan Kebijakan Kuota

Elemen <SpikeArrest>

Menentukan kebijakan SpikeArrest.

Nilai Default Lihat tab Kebijakan Default di bawah
Wajib? Opsional
Jenis Objek kompleks
Elemen Induk t/a
Elemen Turunan <Identifier>
<MessageWeight>
<Rate> (Wajib)
<UseEffectiveCount>

Sintaksis

Elemen <SpikeArrest> menggunakan sintaksis berikut:

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <DisplayName>display_name</DisplayName>
  <Properties/>
  <Identifier ref="flow_variable"/>
  <MessageWeight ref="flow_variable"/>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

Kebijakan Default

Contoh berikut menunjukkan setelan default saat Anda menambahkan kebijakan SpikeArrest ke alur di UI:

<SpikeArrest async="false" continueOnError="false" enabled="true" name="Spike-Arrest-1">
  <DisplayName>Spike Arrest-1</DisplayName>
  <Properties/>
  <Identifier ref="request.header.some-header-name"/>
  <MessageWeight ref="request.header.weight"/>
  <Rate>30ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

Elemen ini memiliki atribut berikut yang umum untuk semua kebijakan:

Atribut Default Wajib? Deskripsi
name T/A Wajib

Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter.

Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

continueOnError false Opsional Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan. Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga:
enabled benar Opsional Tetapkan ke true untuk menerapkan kebijakan. Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.
async   false Tidak digunakan lagi Atribut ini tidak digunakan lagi.

Contoh

Contoh berikut menunjukkan beberapa cara penggunaan kebijakan SpikeArrest:

Contoh 1

Contoh berikut menetapkan kecepatan menjadi lima per detik:

<SpikeArrest name="SA-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

Contoh kebijakan ini mengizinkan maksimum 5 permintaan per detik. Melalui perataan, batas ini diterapkan sebagai maksimum satu permintaan untuk setiap interval 200 milidetik (1000/5).

Contoh 2

Contoh berikut menetapkan kecepatan ke 12 per menit:

<SpikeArrest name="SA-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Contoh kebijakan ini mengizinkan maksimum 12 permintaan per menit dengan kecepatan satu permintaan per interval 5 detik (60/12). Jika ada lebih dari satu permintaan dalam interval 5 detik, permintaan tersebut diizinkan (tanpa perataan) asalkan jumlah permintaan kurang dari batas frekuensi yang dikonfigurasi, yaitu 12 per menit.

Contoh 3

Contoh berikut membatasi permintaan hingga 12 per menit (satu permintaan diizinkan setiap lima detik, atau 60/12):

<SpikeArrest name="SA-With-Dynamic-Weight-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request_specific_weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Selain itu, elemen <MessageWeight> menerima nilai kustom (header weight) yang menyesuaikan bobot pesan untuk aplikasi atau klien tertentu. Hal ini memberikan kontrol tambahan atas pembatasan untuk entitas yang diidentifikasi dengan elemen <Identifier>.

Contoh 4

Contoh berikut menginstruksikan SpikeArrest untuk mencari nilai runtime yang ditetapkan melalui permintaan yang diteruskan sebagai variabel alur request.header.runtime_rate:

<SpikeArrest name="SA-From-Inbound-Header-1">
  <Rate ref="request.header.runtime_rate" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Nilai variabel alur harus dalam bentuk intpm atau intps.

Untuk mencoba contoh ini, jalankan permintaan seperti berikut:

curl http://myorg-myenv.apigee.net/price -H 'runtime_rate:30ps'

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <SpikeArrest>.

<DisplayName>

Gunakan selain atribut name untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama yang berbeda dan lebih terdengar alami.

Elemen <DisplayName> umum untuk semua kebijakan.

Nilai Default T/A
Wajib? Opsional. Jika Anda menghilangkan <DisplayName>, nilai atribut name kebijakan akan digunakan.
Jenis String
Elemen Induk <PolicyElement>
Elemen Turunan Tidak ada

Elemen <DisplayName> menggunakan sintaksis berikut:

Sintaks

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Contoh

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Elemen <DisplayName> tidak memiliki atribut atau elemen turunan.

<Identifier>

Memungkinkan Anda memilih cara mengelompokkan permintaan sehingga kebijakan SpikeArrest dapat diterapkan berdasarkan klien. Misalnya, Anda dapat mengelompokkan permintaan berdasarkan ID developer, yang dalam hal ini setiap permintaan developer akan dihitung berdasarkan kecepatan SpikeArrest-nya sendiri, bukan semua permintaan ke proxy.

Gunakan bersama dengan elemen <MessageWeight> untuk kontrol yang lebih mendetail terhadap pembatasan permintaan.

Jika Anda mengosongkan elemen <Identifier>, satu batas frekuensi akan diterapkan untuk semua permintaan ke proxy API tersebut.

Nilai Default t/a
Wajib? Opsional
Jenis String
Elemen Induk <SpikeArrest>
Elemen Turunan Tidak ada

Sintaksis

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Identifier ref="flow_variable"/>
</SpikeArrest>
        

Contoh 1

Contoh berikut menerapkan kebijakan SpikeArrest per ID developer:

<SpikeArrest name="Spike-Arrest-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Tabel berikut menjelaskan atribut <Identifier>:

Atribut Deskripsi Default Kehadiran
ref Mengidentifikasi variabel yang digunakan SpikeArrest untuk mengelompokkan permintaan masuk. Anda dapat menggunakan variabel alur apa pun untuk menunjukkan klien yang unik, seperti yang tersedia dengan kebijakan VerifyAPIKey. Anda juga dapat menetapkan variabel kustom menggunakan kebijakan JavaScript atau kebijakan AssignMessage. t/a Wajib

Elemen ini juga dibahas dalam postingan Komunitas Apigee ini.

<MessageWeight>

Menentukan pembobotan yang ditentukan untuk setiap pesan. Bobot pesan mengubah dampak satu permintaan pada penghitungan laju SpikeArrest. Bobot pesan dapat berupa variabel alur apa pun, seperti header HTTP, parameter kueri, parameter formulir, atau konten isi pesan. Anda juga dapat menggunakan variabel kustom menggunakan kebijakan JavaScript atau kebijakan AssignMessage.

Gunakan bersama dengan <Identifier> untuk membatasi lebih lanjut permintaan dari klien atau aplikasi tertentu.

Misalnya, jika SpikeArrest <Rate> adalah 10pm, dan aplikasi mengirimkan permintaan dengan bobot 2, maka hanya lima pesan per menit yang diizinkan dari klien tersebut karena setiap permintaan dihitung sebagai 2.

Nilai Default t/a
Wajib? Opsional
Jenis Bilangan bulat
Elemen Induk <SpikeArrest>
Elemen Turunan Tidak ada

Sintaksis

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <MessageWeight ref="flow_variable"/>
</SpikeArrest>

Contoh 1

Contoh berikut membatasi permintaan hingga 12 per menit (satu permintaan diizinkan setiap lima detik, atau 60/12):

<SpikeArrest name="SA-With-Dynamic-Weight-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request_specific_weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Dalam contoh ini, <MessageWeight> menerima nilai kustom (header weight dalam permintaan) yang menyesuaikan bobot pesan untuk klien tertentu. Hal ini memberikan kontrol tambahan atas pembatasan untuk entitas yang diidentifikasi dengan elemen <Identifier>.

Tabel berikut menjelaskan atribut <MessageWeight>:

Atribut Deskripsi Kehadiran Default
ref Mengidentifikasi variabel alur yang berisi bobot pesan untuk klien tertentu. Nilai ini dapat berupa variabel alur apa pun, seperti parameter kueri HTTP, header, atau konten isi pesan. Untuk mengetahui informasi selengkapnya, lihat Referensi variabel alur. Anda juga dapat menetapkan variabel kustom menggunakan kebijakan JavaScript atau kebijakan AssignMessage. Wajib T/A

<Rate>

Menentukan kecepatan untuk membatasi lonjakan (atau burst) traffic dengan menetapkan jumlah permintaan yang diizinkan dalam interval per menit atau per detik. Anda juga dapat menggunakan elemen ini bersama dengan <Identifier> dan <MessageWeight> untuk membatasi traffic dengan lancar saat runtime dengan menerima nilai dari klien. Gunakan elemen <UseEffectiveCount> untuk menetapkan algoritma pembatasan frekuensi yang digunakan oleh kebijakan.

Lihat bagian SpikeArrest di halaman Batas untuk mengetahui batas frekuensi maksimum yang dapat Anda tentukan.

Nilai Default t/a
Wajib? Wajib
Jenis Bilangan bulat
Elemen Induk <SpikeArrest>
Elemen Turunan Tidak ada

Sintaksis

Anda dapat menentukan tarif dengan salah satu cara berikut:

  • Tarif statis yang Anda tentukan sebagai isi elemen <Rate>
  • Nilai variabel, yang dapat diteruskan oleh klien; identifikasi nama variabel alur menggunakan atribut ref
<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
</SpikeArrest>

Nilai tarif yang valid (baik ditentukan sebagai nilai variabel atau di isi elemen) harus sesuai dengan format berikut:

  • intps (jumlah permintaan per detik, dihaluskan ke dalam interval milidetik)
  • intpm (jumlah permintaan per menit, dihaluskan ke dalam interval detik)

Nilai int harus berupa bilangan bulat positif bukan nol.

Contoh 1

Contoh berikut menetapkan kecepatan ke lima permintaan per detik:

<SpikeArrest name="SA-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

Kebijakan ini memperlancar laju menjadi satu permintaan yang diizinkan setiap 200 milidetik (1000/5).

Contoh 2

Contoh berikut menetapkan kecepatan ke 12 permintaan per menit:

<SpikeArrest name="SA-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Contoh kebijakan ini memperlancar laju ke satu permintaan yang diizinkan setiap lima detik (60/12).

Tabel berikut menjelaskan atribut <Rate>:

Atribut Deskripsi Kehadiran Default
ref Mengidentifikasi variabel alur yang menentukan tarif. Hal ini dapat berupa variabel alur apa pun, seperti parameter kueri HTTP, header, atau konten isi pesan, atau nilai seperti KVM. Untuk mengetahui informasi selengkapnya, lihat Referensi variabel alur.

Anda juga dapat menggunakan variabel kustom menggunakan kebijakan JavaScript atau kebijakan AssignMessage.

Jika Anda menentukan ref dan isi elemen ini, nilai ref akan diterapkan dan diprioritaskan saat variabel alur ditetapkan dalam permintaan. (Kebalikannya berlaku jika variabel yang diidentifikasi dalam ref tidak ditetapkan dalam permintaan.)

Contoh:

<Rate ref="request.header.custom_rate">1pm</Rate>

Dalam contoh ini, jika klien tidak meneruskan header custom_rate, maka batas laju untuk proxy API adalah 1 permintaan per menit untuk semua klien. Jika klien meneruskan header custom_rate, batas frekuensi akan menjadi 10 permintaan per detik untuk semua klien di proxy — hingga permintaan tanpa header custom_rate dikirim.

Anda dapat menggunakan <Identifier> untuk mengelompokkan permintaan guna menerapkan tarif kustom untuk berbagai jenis klien.

Jika Anda menentukan nilai untuk ref, tetapi tidak menetapkan kecepatan di isi elemen <Rate> dan klien tidak meneruskan nilai, kebijakan SpikeArrest akan menampilkan error.

Opsional t/a
Tabel berikut menjelaskan atribut Rate yang menentukan perilaku pembatasan traffic:
Atribut Deskripsi
messagesPerPeriod Menentukan jumlah pesan yang diizinkan dalam jangka waktu yang ditentukan. Misalnya, jika kebijakan dikonfigurasi untuk '10ps' (10 per detik), nilai messagesPerPeriod adalah 10.
periodInMicroseconds Menentukan jangka waktu, dalam mikrodetik, yang digunakan untuk menghitung messagesPerPeriod. Untuk konfigurasi '10ps', nilai ini adalah 1.000.000, yang setara dengan satu detik.
maxBurstMessageCount Mewakili jumlah maksimum permintaan yang dapat diizinkan secara instan atau dalam burst singkat di awal interval baru.

<UseEffectiveCount>

Elemen ini memungkinkan Anda memilih di antara algoritma peredaman lonjakan yang berbeda dengan menyetel nilai ke true atau false, seperti yang dijelaskan di bawah:

true

Jika disetel ke true, SpikeArrest didistribusikan di suatu region. Artinya, jumlah permintaan disinkronkan di seluruh pemroses pesan (MP) dalam suatu region. Selain itu, algoritma pembatasan kapasitas "sliding window" diterapkan. Algoritma ini memberikan perilaku pembatasan kapasitas yang konsisten dan tidak "memperlancar" jumlah permintaan masuk yang dapat dikirim ke backend. Jika serangkaian permintaan dikirim dalam interval waktu yang singkat, permintaan tersebut diizinkan selama tidak melebihi batas frekuensi yang dikonfigurasi, sebagaimana ditetapkan dalam elemen <Rate>. Contoh:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

false (default)

Jika disetel ke false (default), kebijakan SpikeArrest menggunakan algoritma "token bucket" yang memperlancar lonjakan traffic dengan membagi batas frekuensi yang Anda tentukan ke dalam interval yang lebih kecil. Kelemahan dari pendekatan ini adalah beberapa permintaan yang sah yang masuk dalam interval waktu singkat berpotensi ditolak.

Misalnya, Anda memasukkan kecepatan 30pm (30 permintaan per menit). Saat pengujian, Anda mungkin berpikir Anda dapat mengirim 30 permintaan dalam 1 detik, selama permintaan tersebut masuk dalam satu menit. Namun, bukan begitu cara kebijakan menerapkan setelan. Jika dipikir-pikir, 30 permintaan dalam periode 1 detik dapat dianggap sebagai lonjakan kecil di beberapa lingkungan.

  • Rasio per menit akan disesuaikan menjadi permintaan penuh yang diizinkan dalam interval detik.

    Misalnya, 30 pm akan di-smoothing seperti ini:
    60 detik (1 menit) / 30 pm = interval 2 detik, atau 1 permintaan diizinkan setiap 2 detik. Permintaan kedua dalam waktu 2 detik akan gagal. Selain itu, permintaan ke-31 dalam satu menit akan gagal.

  • Kecepatan per detik dihaluskan menjadi permintaan penuh yang diizinkan dalam interval milidetik.

    Misalnya, 10ps di-smoothing seperti ini:
    1.000 milidetik (1 detik) / 10ps = interval 100 milidetik, atau 1 permintaan diizinkan setiap 100 milidetik. Permintaan kedua dalam waktu 100 md akan gagal. Selain itu, permintaan ke-11 dalam satu detik akan gagal.

Nilai Default Salah
Wajib? Opsional
Jenis Boolean
Elemen Induk <SpikeArrest>
Elemen Turunan Tidak ada

Tabel berikut menjelaskan atribut elemen <UseEffectiveCount>:

Atribut Deskripsi Default Kehadiran
ref Mengidentifikasi variabel yang berisi nilai <UseEffectiveCount>. Nilai ini dapat berupa variabel alur apa pun, seperti parameter kueri HTTP, header, atau konten isi pesan. Untuk mengetahui informasi selengkapnya, lihat Referensi variabel alur. Anda juga dapat menetapkan variabel kustom menggunakan kebijakan JavaScript atau kebijakan AssignMessage. t/a Opsional

Variabel alur

Saat kebijakan SpikeArrest dijalankan, variabel alur berikut akan diisi:

Variabel Jenis Izin Deskripsi
ratelimit.policy_name.failed Boolean Hanya Baca Menunjukkan apakah kebijakan gagal atau tidak (true atau false).

Untuk mengetahui informasi selengkapnya, lihat Referensi variabel alur.

Referensi error

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
policies.ratelimit.FailedToResolveSpikeArrestRate 500 This error occurs if the reference to the variable containing the rate setting within the <Rate> element cannot be resolved to a value within the SpikeArrest policy. This element is mandatory and used to specify the spike arrest rate in the form of intpm or intps.
policies.ratelimit.InvalidMessageWeight 500 This error occurs if the value specified for the <MessageWeight> element through a flow variable is invalid (a non-integer value).
policies.ratelimit.SpikeArrestViolation 429 The rate limit is exceeded.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidAllowedRate If the spike arrest rate specified in the <Rate> element of the SpikeArrest policy is not an integer or if the rate does not have ps or pm as a suffix, then the deployment of the API proxy fails.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "SpikeArrestViolation"
ratelimit.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. ratelimit.SA-SpikeArrestPolicy.failed = true

Example error response

Shown below is an example error response:

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.SpikeArrestViolation"
      },
      "faultstring":"Spike arrest violation. Allowed rate : 10ps"
   }
}

Example fault rule

Shown below is an example fault rule to handle a SpikeArrestViolation fault:

<FaultRules>
    <FaultRule name="Spike Arrest Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "SpikeArrestViolation") </Condition>
        </Step>
        <Condition>ratelimit.Spike-Arrest-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

Kode status HTTP saat ini untuk melampaui batas frekuensi yang ditetapkan oleh kebijakan Quota atau SpikeArrest adalah 429 (Terlalu Banyak Permintaan).

Skema

Setiap jenis kebijakan ditentukan oleh skema XML (.xsd). Sebagai referensi, skema kebijakan tersedia di GitHub.

Topik terkait