Kebijakan SpikeArrest

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca dokumentasi Apigee Edge.

Ikon SpikeArrest dari UI

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

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

Perbedaan antara SpikeArrest dan Quota

Kebijakan kuota mengonfigurasi jumlah pesan permintaan yang diizinkan untuk dikirim oleh aplikasi klien ke API selama satu jam, hari, minggu, atau bulan. Kebijakan Kuota menerapkan batas pemakaian pada aplikasi klien dengan mengelola penghitung terdistribusi yang menghitung 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 secara tiba-tiba. Lihat juga Membandingkan kebijakan Kuota dan SpikeArrest.

Video

Video berikut membahas kasus penggunaan kebijakan ini:

Mengapa Anda Membutuhkannya

Bandingkan Kebijakan Kuota

Elemen <SpikeArrest>

Menentukan kebijakan SpikeArrest.

Nilai Default Lihat tab Kebijakan Default di bawah
Wajib? Opsional
Type 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 flow 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 sama 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.

Atau, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.

continueOnError false Opsional Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan. Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal. Lihat juga:
enabled true Opsional Setel ke true untuk menerapkan kebijakan. Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.
async   false Tidak digunakan lagi Atribut ini sudah tidak digunakan lagi.

Contoh

Contoh berikut menunjukkan beberapa cara untuk menggunakan kebijakan SpikeArrest:

Contoh 1

Contoh berikut menetapkan kecepatan ke lima per detik:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

Kebijakan contoh ini mengizinkan maksimum 5 permintaan per detik. Melalui smoothing, ini diterapkan sebagai maksimum satu permintaan untuk setiap interval 200 milidetik (1.000/5).

Contoh 2

Contoh berikut menetapkan kecepatan ke 12 per menit:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Kebijakan sampel ini mengizinkan maksimum 12 permintaan per menit pada tingkat satu permintaan per interval 5 detik (60/12). Jika ada lebih dari satu permintaan dalam interval 5 detik, permintaan tersebut diizinkan (tidak akan lancar) asalkan jumlah permintaan kurang dari batas kapasitas yang dikonfigurasi 12 per menit.

Contoh 3

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.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 throttling 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="Spike-Arrest-1">
  <Rate ref="request.header.runtime_rate" />
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Nilai variabel flow 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 kebijakan di editor proxy UI pengelolaan dengan nama yang berbeda dan lebih alami.

Elemen <DisplayName> bersifat 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:

Sintaksis

<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. Dalam hal ini, permintaan setiap developer akan diperhitungkan dalam rasio SpikeArrest mereka sendiri dan tidak semua permintaan ke proxy.

Gunakan bersama elemen <MessageWeight> untuk kontrol yang lebih mendetail atas throttling permintaan.

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

Nilai Default t/a
Wajib? Opsional
Type 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 untuk menunjukkan klien unik, seperti yang tersedia dengan kebijakan VerifyAPIKey. Anda juga dapat menetapkan variabel kustom menggunakan kebijakan JavaScript atau kebijakanAssignMessage. t/a Diperlukan

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 kecepatan 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 kebijakanAssignMessage.

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

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

Nilai Default t/a
Wajib? Opsional
Type 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="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.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 throttling untuk entitas yang diidentifikasi dengan elemen <Identifier>.

Tabel berikut menjelaskan atribut <MessageWeight>:

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

<Rate>

Menentukan kecepatan untuk membatasi lonjakan (atau burst) traffic dengan menyetel 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 menyetel algoritma pembatasan kapasitas yang digunakan oleh kebijakan.

Nilai Default t/a
Wajib? Diperlukan
Type 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 didefinisikan sebagai nilai variabel atau dalam isi elemen) harus sesuai dengan format berikut:

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

Nilai int harus berupa bilangan bulat positif bukan nol.

Contoh 1

Contoh berikut menetapkan kecepatan ke lima permintaan per detik:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

Kebijakan ini memperhalus kecepatan menjadi satu permintaan yang diizinkan setiap 200 milidetik (1.000/5).

Contoh 2

Contoh berikut menetapkan kecepatan ke 12 permintaan per menit:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Kebijakan contoh ini memperhalus kecepatan menjadi satu permintaan yang diizinkan setiap lima detik (60/12).

Tabel berikut menjelaskan atribut <Rate>:

Atribut Deskripsi Kehadiran Default
ref Mengidentifikasi variabel flow yang menentukan laju. Ini dapat berupa variabel alur apa pun, seperti parameter kueri HTTP, header, atau isi pesan, atau nilai seperti KVM. Untuk informasi selengkapnya, lihat Referensi variabel flow.

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

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

Contoh:

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

Dalam contoh ini, jika klien tidak meneruskan header custom_rate, tarif proxy API adalah 1 permintaan per menit untuk semua klien. Jika klien meneruskan header custom_rate, batas kapasitas 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 khusus untuk berbagai jenis klien.

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

Opsional t/a

<UseEffectiveCount>

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

true

Jika ditetapkan ke true, SpikeArrest akan didistribusikan di suatu region. Artinya, jumlah permintaan disinkronkan ke seluruh pemroses pesan (MP) di suatu region. Selain itu, algoritma pembatasan kapasitas "jendela geser" digunakan. Algoritma ini memberikan perilaku batas kapasitas yang konsisten dan tidak "menghaluskan" jumlah permintaan masuk yang dapat dikirim ke backend. Jika burst permintaan dikirim dalam interval waktu yang singkat, permintaan tersebut diizinkan selama tidak melebihi batas kapasitas yang dikonfigurasi, seperti yang 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>

salah (default)

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

Misalnya, Anda memasukkan frekuensi pukul 30.00 (30 permintaan per menit). Saat pengujian, Anda mungkin berpikir dapat mengirim 30 permintaan dalam 1 detik, asalkan permintaan tersebut masuk dalam satu menit. Namun, kebijakan tersebut tidak akan menerapkan setelan. Jika Anda memikirkannya, 30 permintaan dalam periode 1 detik dapat dianggap sebagai lonjakan kecil di beberapa lingkungan.

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

    Misalnya, pukul 15.00 dihaluskan seperti ini:
    60 detik (1 menit) / 30.00 = 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 akan dihaluskan menjadi permintaan penuh yang diizinkan dalam interval milidetik.

    Misalnya, 10 ps dihaluskan seperti ini:
    1.000 milidetik (1 detik) / 10 ps = 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
Type 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>. Ini dapat berupa variabel alur apa pun, seperti parameter kueri HTTP, header, atau konten isi pesan. Untuk informasi selengkapnya, lihat Referensi variabel flow. Anda juga dapat menetapkan variabel kustom menggunakan kebijakan JavaScript atau kebijakanAssignMessage. t/a Opsional

Variabel alur

Saat kebijakan SpikeArrest dijalankan, variabel flow berikut akan diisi:

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

Untuk informasi selengkapnya, lihat Referensi variabel flow.

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kesalahan Status HTTP Penyebab Perbaikan
policies.ratelimit.FailedToResolveSpikeArrestRate 500 Error ini terjadi jika referensi ke variabel yang berisi setelan tarif dalam elemen <Rate> tidak dapat di-resolve menjadi nilai dalam kebijakan SpikeArrest. Elemen ini bersifat wajib dan digunakan untuk menentukan rasio penangkapan lonjakan dalam bentuk intpm atau intps.
policies.ratelimit.InvalidMessageWeight 500 Error ini terjadi jika nilai yang ditentukan untuk elemen <MessageWeight> melalui variabel flow tidak valid (nilai non-bilangan bulat).
policies.ratelimit.SpikeArrestViolation 429 Batas kapasitas terlampaui.

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Nama error Penyebab Perbaikan
InvalidAllowedRate Jika rasio penangkapan lonjakan yang ditentukan dalam elemen <Rate> kebijakan SpikeArrest tidak berupa bilangan bulat atau jika tarif tidak memiliki ps atau pm sebagai akhiran, deployment proxy API akan gagal.

Variabel kesalahan

Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.

Variabel Dari mana Contoh
fault.name="fault_name" fault_name adalah nama kesalahannya, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir dari kode kesalahan. fault.name Matches "SpikeArrestViolation"
ratelimit.policy_name.failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. ratelimit.SA-SpikeArrestPolicy.failed = true

Contoh respons error

Berikut adalah contoh respons error:

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

Contoh aturan kesalahan

Berikut adalah contoh aturan kesalahan untuk menangani kesalahan SpikeArrestViolation:

<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 karena melebihi batas kapasitas yang ditetapkan oleh kebijakan Kuota atau SpikeArrest adalah 429 (Terlalu Banyak Permintaan). Untuk mengubah kode status HTTP menjadi 500 (Error Server Internal), tetapkan properti features.isHTTPStatusTooManyRequestEnabled ke false menggunakan API Update organization properties.

Contoh:

curl -u email:password -X POST -H "Content-type:application/xml" http://apigee.googleapis.com/v1/organizations/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property>
        . . .
    </Properties>
</Organization>"

Skema

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

Topik terkait