Kebijakan SpikeArrest

Anda sedang melihat dokumentasi Apigee Edge.
Buka Dokumentasi Apigee X.
info

Ikon Spike Arrest dari UI Edge

Kebijakan Penangkapan Lonjakan melindungi jaringan dari lonjakan traffic dengan elemen <Rate>. Ini men-throttle jumlah permintaan yang diproses oleh proxy API dan dikirim ke backend, untuk melindungi dari jeda performa dan periode nonaktif.

Elemen <SpikeArrest>

Menentukan kebijakan Lonjakan.

Nilai Default Lihat tab Kebijakan Default, di bawah
Wajib? Opsional
Jenis Rumit objek
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 Lonjakan ke di UI Edge:

<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>true</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.

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

continueOnError false Opsional Tetapkan ke "false" untuk menampilkan error saat kebijakan gagal. Hal ini wajar untuk sebagian besar kebijakan. Tetapkan ke "true" agar eksekusi flow berlanjut meskipun kebijakan gagal.
enabled benar Opsional Tetapkan ke "true" untuk menerapkan kebijakan. Tetapkan ke "false" untuk "menonaktifkan" kebijakan. Kebijakan ini tidak akan diterapkan meskipun tetap dilampirkan ke flow.
async   false Tidak digunakan lagi Atribut ini tidak digunakan lagi.

Contoh

Contoh berikut menunjukkan beberapa cara untuk menggunakan kebijakan Penangkapan Lonjakan:

Contoh 1

Contoh berikut menetapkan kecepatan ke lima per detik:

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

Kebijakan ini mengoptimalkan tingkat permintaan ke satu permintaan yang diizinkan setiap 200 milidetik (1000/5).

Contoh 2

Contoh berikut menetapkan tarif ke 12 per menit:

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

Kebijakan contoh ini menghaluskan tingkat ke satu permintaan yang diizinkan setiap lima detik (60/12).

Contoh 3

Contoh berikut membatasi permintaan hingga 12 permintaan 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" />
</SpikeArrest>

Selain itu, elemen <MessageWeight> menerima nilai kustom ( weight) yang menyesuaikan bobot pesan untuk aplikasi atau klien tertentu. Ini memberikan kontrol tambahan atas throttling untuk entity yang diidentifikasi dengan Elemen <Identifier>.

Contoh 4

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate ref="request.header.runtime_rate" />
</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 dari <SpikeArrest>.

<DisplayName>

Gunakan selain atribut name untuk memberi label kebijakan di baru dengan nama yang berbeda dan terdengar lebih alami.

Elemen <DisplayName> umum untuk semua kebijakan.

Nilai Default t/a
Wajib? Opsional. Jika Anda menghapus <DisplayName>, nilai atribut atribut name kebijakan digunakan
Jenis String
Elemen Induk &lt;PolicyElement&gt;
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 Penangkapan Lonjakan dapat diterapkan berdasarkan pada klien. Misalnya, Anda dapat mengelompokkan permintaan berdasarkan ID developer, dalam hal ini masing-masing permintaan pengembang akan diperhitungkan dalam tingkat Penangkapan Lonjakan mereka sendiri dan tidak semua permintaan ke {i>proxy<i}.

Gunakan bersama dengan elemen <MessageWeight> agar informasi lebih mendetail mengontrol 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
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 Penangkapan Lonjakan per ID developer:

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

Tabel berikut menjelaskan atribut <Identifier>:

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

Elemen ini juga dibahas dalam postingan Komunitas Apigee berikut: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.

<MessageWeight>

Menentukan pembobotan yang ditentukan untuk setiap pesan. Bobot pesan mengubah dampaknya atas satu permintaan pada perhitungan Tingkat Penahanan Lonjakan. Bobot pesan dapat berupa berapa pun variabel alur, seperti header HTTP, parameter kueri, parameter formulir, atau konten isi pesan. Anda juga dapat menggunakan variabel kustom menggunakan kebijakan JavaScript atau Kebijakan Menetapkan Pesan.

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

Misalnya, jika Spike Arrest <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 permintaan 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" />
</SpikeArrest>

Dalam contoh ini, <MessageWeight> menerima nilai kustom (weight header dalam permintaan) yang menyesuaikan bobot pesan untuk klien tertentu. Ini memberikan kontrol tambahan atas throttling untuk entity yang diidentifikasi dengan Elemen <Identifier>.

Tabel berikut menjelaskan atribut <MessageWeight>:

Atribut Deskripsi Ketersediaan Default
ref Mengidentifikasi variabel alur yang berisi bobot pesan untuk klien tertentu. Ini dapat berupa variabel alur apa pun, seperti sebagai 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 kebijakan Menetapkan Pesan. Wajib T/A

<Rate>

Menentukan rasio untuk membatasi lonjakan (atau burst) traffic dengan menetapkan jumlah yang diizinkan dalam interval per menit atau per detik. Anda juga dapat menggunakan elemen ini dalam bersama dengan <Identifier> dan <MessageWeight> untuk membatasi traffic secara lancar saat runtime dengan menerima nilai dari klien.

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; mengidentifikasi nama variabel flow 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 mengikuti format berikut:

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

Nilai int harus berupa bilangan bulat positif dan bukan nol.

Contoh 1

Contoh berikut menetapkan kecepatan ke lima permintaan per detik:

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

Kebijakan ini mengoptimalkan tingkat permintaan ke satu permintaan yang diizinkan setiap 200 milidetik (1000/5).

Contoh 2

Contoh berikut menetapkan tarif menjadi 12 permintaan per menit:

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

Kebijakan contoh ini menghaluskan tingkat ke satu permintaan yang diizinkan setiap lima detik (60/12).

Tabel berikut menjelaskan atribut <Rate>:

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

Anda juga dapat menggunakan variabel kustom menggunakan kebijakan JavaScript atau kebijakan Menetapkan Pesan.

Jika Anda menentukan ref dan isi elemen ini, nilai ref diterapkan dan lebih diprioritaskan saat variabel flow yang ditetapkan dalam permintaan. (Kebalikannya benar jika variabel diidentifikasi di ref tidak ditetapkan dalam permintaan.)

Contoh:

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

Dalam contoh ini, jika klien tidak meneruskan nilai "custom_rate" {i>header<i}, kemudian untuk proxy API adalah 1 permintaan per menit untuk semua klien. Jika klien meneruskan "tarif_kustom" , maka batas kapasitas menjadi 10 permintaan per detik untuk semua klien proxy — hingga permintaan tanpa "custom_rate" header 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 tarif di bagian isi elemen <Rate> dan klien tidak meneruskan nilai, maka kebijakan Penangkapan Lonjakan menampilkan error.

Opsional t/a

<UseEffectiveCount>

Mendistribusikan jumlah lonjakan Lonjakan ke seluruh Pemroses Pesan (MP) saat menggunakan penskalaan otomatis grup.

Sintaksis

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

Contoh 1

Contoh berikut menetapkan <UseEffectiveCount> ke benar (true):

<SpikeArrest name='Spike-Arrest-1'>
  <Rate>40ps</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

Elemen <UseEffectiveCount> bersifat opsional. Nilai defaultnya adalah false jika elemen tersebut dihilangkan dari kebijakan Penangkapan Spike Anda.

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

Tabel berikut menjelaskan atribut elemen <UseEffectiveCount>:

Atribut Deskripsi Default Ketersediaan
ref Mengidentifikasi variabel yang berisi nilai <UseEffectiveCount>. Dapat berupa variabel alur, seperti parameter kueri HTTP, header, atau konten isi pesan. Untuk selengkapnya informasi tambahan, lihat Referensi variabel flow. Anda juga dapat menetapkan variabel kustom menggunakan kebijakan JavaScript atau kebijakan Menetapkan Pesan. t/a Opsional

Efek <UseEffectiveCount> bergantung pada nilainya:

  • true: Batas kecepatan lonjakan seorang MP adalah <Rate> dibagi dengan jumlah anggota parlemen saat ini dalam pod yang sama. Batas gabungan adalah nilai dari <Rate>. Saat anggota parlemen ditambahkan (atau dihapus) secara dinamis, masing-masing lonjakan batas kapasitas akan meningkat (atau menurun), tetapi batas gabungan akan tetap sama.
  • false (ini adalah nilai default jika dihilangkan): Batas kapasitas lonjakan setiap MP adalah cukup nilai <Rate>-nya. Batas agregat adalah jumlah jumlah anggota parlemen. Ketika anggota parlemen ditambahkan (atau dihapus), batas kapasitas lonjakan individual akan tetap sama, tetapi batas gabungan akan meningkat (atau ).

Tabel berikut menunjukkan efek <UseEffectiveCount> pada batas kapasitas efektif setiap MP:

Nilai <UseEffectiveCount>
false false false true true true
# anggota parlemen 8 4 2 8 4 2
Nilai <Rate> 10 10 10 40 40 40
Tarif Efektif per MP 10 10 10 5 10 20
Batas Gabungan 80 40 20 40* 40* 40*
* Sama seperti <Rate>.

Dalam contoh ini, perhatikan bahwa ketika jumlah anggota parlemen berkurang dari 4 menjadi 2, dan <UseEffectiveCount> adalah false, rasio efektif per MP tetap sama (pada 10.) Namun, jika <UseEffectiveCount> adalah true, rasio efektif per MP berubah dari Dari 10 menjadi 20, jumlah anggota parlemen berkurang dari 4 menjadi 2.

Variabel flow

Saat kebijakan Spike Arrest 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 mengetahui informasi selengkapnya, lihat Referensi variabel flow.

Referensi error

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

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

Kode error Status HTTP Penyebab Perbaiki
policies.ratelimit.FailedToResolveSpikeArrestRate 500 Error ini terjadi jika referensi ke variabel yang berisi setelan tarif dalam elemen <Rate> tidak dapat diselesaikan menjadi nilai dalam Spike Arrest lebih lanjut. Elemen ini bersifat wajib dan digunakan untuk menentukan tingkat penghentian 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 Perbaiki
InvalidAllowedRate Jika rasio berhenti melonjak yang ditentukan dalam elemen <Rate> dari Spike Arrest Kebijakan bukan bilangan bulat atau jika tarif tidak memiliki ps atau pm sebagai akhiran, maka 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 Di mana Contoh
fault.name="fault_name" fault_name adalah nama kesalahan, seperti yang tercantum dalam Tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir 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

Di bawah ini adalah contoh respons error:

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

Contoh aturan kesalahan

Di bawah ini 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 Lonjakan adalah 429 (Terlalu Banyak Permintaan). Untuk mengubah kode status HTTP menjadi 500 (Error Server Internal), setel properti features.isHTTPStatusTooManyRequestEnabled ke false menggunakan Mengupdate API properti organisasi.

Contoh:

curl -u email:password -X POST -H "Content-type:application/xml" http://api.enterprise.apigee.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). Sebagai referensi, skema kebijakan tersedia di GitHub.

Topik terkait