Kebijakan kuota

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

Apa

Gunakan kebijakan Kuota untuk mengonfigurasi jumlah pesan permintaan yang diizinkan oleh proxy API selama jangka waktu tertentu, seperti menit, jam, hari, minggu, atau bulan. Anda dapat menetapkan kuota agar sama untuk semua aplikasi yang mengakses proxy API, atau menetapkan kuota berdasarkan:

  • Produk yang berisi proxy API
  • Aplikasi yang meminta API
  • Developer aplikasi
  • Banyak kriteria lainnya

Jangan gunakan Kuota untuk melindungi dari lonjakan traffic secara keseluruhan. Untuk itu, gunakan kebijakan Penangkapan Spike. Lihat kebijakan Penahanan Lonjakan.

Video

Video berikut memperkenalkan pengelolaan kuota dengan kebijakan Kuota:

Pengantar (Edge Baru)

Pengantar (Edge Klasik)

Kuota Dinamis

Terdistribusi & Sinkron

Berat Pesan

Kalender

Jendela Beroda

Fleksibel

Kuota Bersyarat

Variabel Alur

Penanganan Error

Contoh

Contoh kode kebijakan ini mengilustrasikan cara memulai dan mengakhiri periode kuota dengan:

Kuota Dinamis Lebih Banyak

<Quota name="CheckQuota"> 
  <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.quota.interval">1</Interval>
  <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.quota.timeunit">hour</TimeUnit>
  <Allow count="200" countRef="verifyapikey.verify-api-key.apiproduct.developer.quota.limit"/>
</Quota>

Kuota dinamis memungkinkan Anda mengonfigurasi satu kebijakan Kuota yang menerapkan berbagai setelan Kuota berdasarkan informasi yang diteruskan ke kebijakan Kuota. Istilah lain untuk setelan Kuota dalam konteks ini adalah "Paket Layanan". Kuota dinamis memeriksa "Paket Layanan" aplikasi, kemudian menerapkan setelan tersebut.

Catatan: Jika Anda menentukan nilai dan referensi untuk elemen, referensi akan mendapatkan prioritas. Jika referensi tidak di-resolve saat runtime, nilai akan digunakan.

Misalnya, saat membuat produk API, Anda dapat secara opsional menetapkan batas kuota, satuan waktu, dan interval yang diizinkan. Namun, menetapkan nilai ini pada produk API tidak akan menerapkan penggunaannya pada proxy API. Anda juga harus menambahkan kebijakan Kuota ke proxy API yang membaca nilai ini. Lihat Membuat produk API untuk mengetahui informasi selengkapnya.

Pada contoh di atas, proxy API yang berisi kebijakan Kuota menggunakan kebijakan VerifyAPIKey, yang bernama verify-api-key, untuk memvalidasi kunci API yang diteruskan dalam permintaan. Kemudian, kebijakan Kuota akan mengakses variabel flow dari kebijakan VerifyAPIKey untuk membaca nilai kuota yang ditetapkan pada produk API. Untuk informasi selengkapnya tentang variabel alur VerifyAPIKey, lihat Memverifikasi kebijakan Kunci API.

Opsi lainnya adalah menetapkan atribut khusus pada masing-masing developer atau aplikasi, lalu membaca nilai tersebut dalam kebijakan Kuota. Misalnya, Anda ingin menetapkan nilai kuota yang berbeda per developer. Dalam hal ini, Anda menetapkan atribut khusus pada developer yang berisi batas, satuan waktu, dan interval. Selanjutnya, Anda mereferensikan nilai-nilai ini dalam kebijakan Kuota seperti yang ditunjukkan di bawah ini:

<Quota name="DeveloperQuota"> 
  <Identifier ref="verifyapikey.verify-api-key.client_id"/> 
  <Interval ref="verifyapikey.verify-api-key.developer.timeInterval"/> 
  <TimeUnit ref="verifyapikey.verify-api-key.developer.timeUnit"/> 
  <Allow countRef="verifyapikey.verify-api-key.developer.limit"/> 
</Quota>

Contoh ini juga menggunakan variabel alur VerifyAPIKey untuk mereferensikan atribut khusus yang ditetapkan pada developer.

Anda dapat menggunakan variabel apa pun untuk menetapkan parameter kebijakan Kuota. Variabel tersebut dapat berasal dari:

  • Variabel alur
  • Properti pada produk, aplikasi, atau developer API
  • Peta nilai kunci (KVM)
  • Header, parameter kueri, parameter formulir, dll.

Untuk setiap proxy API, Anda dapat menambahkan kebijakan Kuota yang mereferensikan variabel yang sama seperti semua kebijakan Quota lainnya di semua proxy lainnya, atau kebijakan Quota dapat mereferensikan variabel yang unik untuk kebijakan dan proxy tersebut.

Waktu Mulai

<Quota name="QuotaPolicy" type="calendar">
  <StartTime>2017-02-18 10:30:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

Untuk Kuota dengan type yang ditetapkan ke calendar, Anda harus menentukan nilai <StartTime> eksplisit. Nilai waktu adalah waktu GMT, bukan waktu lokal. Jika Anda tidak memberikan nilai <StartTime> untuk kebijakan jenis calendar, Edge akan menghasilkan error.

Penghitung Kuota untuk setiap aplikasi diperbarui berdasarkan nilai <StartTime>, <Interval>, dan <TimeUnit>. Untuk contoh ini, Kuota mulai dihitung pada pukul 10.30 GMT pada 18 Februari 2017, dan diperbarui setiap 5 jam. Oleh karena itu, refresh berikutnya adalah pada pukul 15.30 GMT tanggal 18 Februari 2017.

Penghitung Akses

<Quota name="QuotaPolicy">
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

Proxy API memiliki akses ke variabel alur yang ditetapkan oleh kebijakan Quota. Anda dapat mengakses variabel alur ini di proxy API untuk melakukan pemrosesan bersyarat, memantau kebijakan saat mendekati batas kuota, menampilkan penghitung kuota saat ini ke aplikasi, atau untuk alasan lainnya.

Karena akses variabel alur untuk kebijakan didasarkan pada atribut name kebijakan, untuk kebijakan di atas bernama QuotaPolicy, Anda mengakses variabel alurnya dalam bentuk:

  • ratelimit.QuotaPolicy.allowed.count: Jumlah yang diizinkan.
  • ratelimit.QuotaPolicy.used.count: Nilai penghitung saat ini.
  • ratelimit.QuotaPolicy.expiry.time: Waktu UTC saat penghitung direset.

Ada banyak variabel flow lainnya yang dapat Anda akses, seperti yang dijelaskan di bawah ini.

Misalnya, Anda dapat menggunakan kebijakan BiddingMessage berikut untuk menampilkan nilai variabel alur Quota sebagai header respons:

<AssignMessage async="false" continueOnError="false" enabled="true" name="ReturnQuotaVars">
    <AssignTo createNew="false" type="response"/>
    <Set>
        <Headers>
            <Header name="QuotaLimit">{ratelimit.QuotaPolicy.allowed.count}</Header>
            <Header name="QuotaUsed">{ratelimit.QuotaPolicy.used.count}</Header>
            <Header name="QuotaResetUTC">{ratelimit.QuotaPolicy.expiry.time}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

Permintaan Pertama

<Quota name="MyQuota">
  <Interval>1</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="10000"/>
</Quota>

Gunakan kode contoh ini untuk menerapkan kuota 10.000 panggilan per jam. Kebijakan ini akan mereset penghitung kuota di bagian atas setiap jam. Jika penghitung mencapai kuota 10.000 panggilan sebelum akhir jam tersebut, panggilan di atas 10.000 akan ditolak.

Misalnya, jika penghitung dimulai pada 2017-07-08 07:00:00, penghitung akan direset ke 0 pada 2017-07-08 08:00:00 (1 jam dari waktu mulai). Jika pesan pertama diterima di 2017-07-08 07:35:28 dan jumlah pesan mencapai 10.000 sebelum 2017-07-08 08:00:00, panggilan di luar jumlah tersebut akan ditolak sampai hitungannya direset di bagian atas jam.

Waktu reset penghitung didasarkan pada kombinasi <Interval> dan <TimeUnit>. Misalnya, jika Anda menetapkan <Interval> ke 12 selama <TimeUnit> jam, penghitung akan direset setiap dua belas jam. Anda dapat menyetel <TimeUnit> ke menit, jam, hari, minggu, atau bulan.

Anda dapat merujuk kebijakan ini di beberapa tempat di proxy API Anda. Misalnya, Anda dapat menempatkannya pada Proxy PreFlow sehingga akan dieksekusi pada setiap permintaan. Atau, Anda dapat menempatkannya di beberapa flow di proxy API. Jika Anda menggunakan kebijakan ini di beberapa tempat di proxy, kebijakan ini akan mempertahankan satu penghitung yang diperbarui oleh semua instance kebijakan.

Atau, Anda dapat menentukan beberapa kebijakan Kuota di proxy API. Setiap kebijakan Kuota mempertahankan penghitungnya sendiri, berdasarkan atribut name kebijakan.

Setel ID

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/> 
  <StartTime>2017-02-18 10:00:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

Secara default, kebijakan Kuota menentukan satu penghitung untuk proxy API, terlepas dari asal permintaan. Atau, Anda dapat menggunakan atribut <Identifier> dengan kebijakan Kuota untuk mempertahankan penghitung terpisah berdasarkan nilai atribut <Identifier>.

Misalnya, gunakan tag <Identifier> untuk menentukan penghitung terpisah untuk setiap client ID. Pada permintaan ke proxy Anda, aplikasi klien akan meneruskan header yang berisi clientID, seperti yang ditunjukkan dalam contoh di atas.

Anda dapat menentukan variabel flow apa pun ke atribut <Identifier>. Misalnya, Anda dapat menetapkan bahwa parameter kueri bernama id berisi ID unik:

<Identifier ref="request.queryparam.id"/>

Jika Anda menggunakan kebijakan VerifyAPIKey untuk memvalidasi kunci API, atau kebijakan OAuthV2 dengan token OAuth, Anda dapat menggunakan informasi dalam token atau kunci API untuk menentukan penghitung individu untuk kebijakan Kuota yang sama. Misalnya, tag <Identifier> berikut menggunakan variabel alur client_id dari kebijakan VerifyAPIKey bernama verify-api-key:

<Identifier ref="verifyapikey.verify-api-key.client_id"></Identifier>

Setiap nilai client_id unik kini menentukan penghitungnya sendiri dalam kebijakan Kuota.

Class

<Quota name="QuotaPolicy">
  <Interval>1</Interval>
  <TimeUnit>day</TimeUnit>
  <Allow>
    <Class ref="request.header.developer_segment">
      <Allow class="platinum" count="10000"/>
      <Allow class="silver" count="1000" />
    </Class>
  </Allow>
</Quota>

Anda dapat menetapkan batas Kuota secara dinamis menggunakan jumlah Kuota berbasis class. Dalam contoh ini, batas kuota ditentukan oleh nilai header developer_segment yang diteruskan dengan setiap permintaan. Variabel tersebut dapat memiliki nilai platinum atau silver. Jika header memiliki nilai yang tidak valid, kebijakan akan menampilkan error pelanggaran kuota.


Tentang kebijakan Kuota

Kuota adalah alokasi pesan permintaan yang dapat ditangani oleh proxy API selama jangka waktu tertentu, seperti menit, jam, hari, minggu, atau bulan. Kebijakan ini mengelola penghitung yang menghitung jumlah permintaan yang diterima oleh proxy API. Kemampuan ini memungkinkan penyedia API menerapkan batas jumlah panggilan API yang dilakukan oleh aplikasi selama interval waktu tertentu. Dengan menggunakan kebijakan Kuota, Anda dapat, misalnya, membatasi aplikasi hingga 1 permintaan per menit,atau hingga 10.000 permintaan per bulan.

Misalnya, jika Kuota didefinisikan sebagai 10.000 pesan per bulan, pembatasan kapasitas akan dimulai setelah pesan ke-10.000. Tidak masalah apakah 10.000 pesan telah dihitung pada hari pertama atau hari terakhir periode tersebut. Tidak ada area permintaan tambahan yang diizinkan hingga penghitung Kuota otomatis direset pada akhir interval waktu yang ditentukan, atau hingga Kuota direset secara eksplisit menggunakan kebijakan Reset Kuota.

Variasi pada Kuota yang disebut SpikeArrest mencegah lonjakan (atau burst) traffic yang dapat disebabkan oleh peningkatan penggunaan secara tiba-tiba, klien yang memiliki bug, atau serangan berbahaya. Untuk mengetahui informasi selengkapnya tentang SpikeArrest, lihat kebijakanSpike Arrest.

Kuota berlaku untuk proxy API individual dan tidak didistribusikan di antara proxy API. Misalnya, jika Anda memiliki tiga proxy API dalam satu produk API, satu kuota tidak dibagikan di ketiganya meskipun ketiganya menggunakan konfigurasi kebijakan kuota yang sama.

Jenis kebijakan kuota

Kebijakan Kuota mendukung beberapa jenis kebijakan: default, calendar, flexi, dan rollingwindow. Setiap jenis menentukan kapan penghitung kuota dimulai dan saat penghitung kuota direset, seperti yang ditunjukkan dalam tabel berikut:

Unit Waktu Reset default (atau null) kalender direset reset flexi
menit Awal menit berikutnya Satu menit setelah <StartTime> Satu menit setelah permintaan pertama
hour Bagian atas dalam satu jam berikutnya Satu jam setelah <StartTime> Satu jam setelah permintaan pertama
hari GMT tengah malam hari ini 24 jam setelah <StartTime> 24 jam setelah permintaan pertama
week Minggu tengah malam GMT pada akhir minggu Satu minggu setelah <StartTime> Satu minggu setelah permintaan pertama
bulan GMT tengah malam pada hari terakhir bulan ini Satu bulan (28 hari) setelah <StartTime> Satu bulan (28 hari) setelah permintaan pertama

Untuk type="calendar", Anda harus menentukan nilai <StartTime>.

Tabel tidak mencantumkan nilai untuk jenis rollingwindow. Kuota periode berkelanjutan berfungsi dengan menetapkan ukuran "periode" kuota, seperti periode satu jam atau satu hari. Saat permintaan baru masuk, kebijakan akan menentukan apakah kuota telah terlampaui dalam "jangka waktu" terakhir.

Misalnya, Anda menetapkan jangka waktu dua jam yang memungkinkan 1.000 permintaan. Permintaan baru masuk pukul 16.45. Kebijakan ini menghitung jumlah kuota untuk periode dua jam terakhir, yang berarti jumlah permintaan sejak pukul 14.45. Jika batas kuota belum terlampaui dalam periode dua jam tersebut, permintaan akan diizinkan.

Satu menit kemudian, pukul 16.46, permintaan lain masuk. Sekarang kebijakan tersebut menghitung jumlah kuota sejak pukul 14.46 untuk menentukan apakah batas telah terlampaui.

Untuk jenis rollingwindow, penghitung tidak pernah direset, tetapi dihitung ulang pada setiap permintaan.

Memahami penghitung kuota

Secara default, kebijakan Kuota mempertahankan satu penghitung, terlepas dari berapa kali Anda mereferensikannya dalam proxy API. Nama penghitung kuota didasarkan pada atribut name kebijakan.

Misalnya, Anda membuat kebijakan Kuota bernama MyQuotaPolicy dengan batas 5 permintaan dan menempatkannya di beberapa alur (Alur A, B, dan C) di proxy API. Meskipun digunakan di beberapa alur, penghitung tunggal mempertahankan satu penghitung yang diupdate oleh semua instance kebijakan:

  • Alur A dieksekusi -> MyQuotaPolicy dieksekusi dan penghitungnya = 1
  • Alur B dieksekusi -> MyQuotaPolicy dieksekusi dan penghitungnya = 2
  • Alur A dieksekusi -> MyQuotaPolicy dieksekusi dan penghitungnya = 3
  • Alur C dieksekusi -> MyQuotaPolicy dijalankan dan penghitungnya = 4
  • Alur A dieksekusi -> MyQuotaPolicy dieksekusi dan penghitungnya = 5

Permintaan berikutnya ke salah satu dari tiga alur ditolak karena penghitung kuota telah mencapai batasnya.

Menggunakan kebijakan Kuota yang sama di lebih dari satu tempat dalam alur proxy API, yang secara tidak sengaja dapat menyebabkan Kuota habis lebih cepat dari yang Anda harapkan, adalah antipola yang dijelaskan dalam The Book of Apigee Edge Antipatterns.

Atau, Anda dapat menentukan beberapa kebijakan Kuota di proxy API dan menggunakan kebijakan berbeda di setiap alur. Setiap kebijakan Kuota mempertahankan penghitungnya sendiri, berdasarkan atribut name kebijakan.

Atau, gunakan elemen <Class> atau <Identifier> dalam kebijakan Kuota untuk menentukan beberapa penghitung unik dalam satu kebijakan. Dengan menggunakan elemen ini, sebuah kebijakan dapat mempertahankan penghitung yang berbeda berdasarkan aplikasi yang membuat permintaan, developer aplikasi yang membuat permintaan, client ID atau ID klien lainnya, dan lainnya. Lihat contoh di atas untuk informasi selengkapnya tentang penggunaan elemen <Class> atau <Identifier>.

Notasi waktu

Semua waktu Kuota ditetapkan ke zona waktu Waktu Universal Terkoordinasi (UTC).

Notasi waktu kuota mengikuti notasi tanggal standar internasional yang didefinisikan dalam Standar Internasional ISO 8601.

Tanggal ditentukan sebagai tahun, bulan, dan hari, dalam format berikut: YYYY-MM-DD. Misalnya, 2015-02-04 mewakili 4 Februari 2015.

Waktu ditentukan sebagai jam, menit, dan detik dalam format berikut: hours:minutes:seconds. Misalnya, 23:59:59 mewakili waktu satu detik sebelum tengah malam.

Perhatikan bahwa dua notasi, 00:00:00 dan 24:00:00, tersedia untuk membedakan dua tengah malam yang dapat dikaitkan dengan satu tanggal. Oleh karena itu, 2015-02-04 24:00:00 adalah tanggal dan waktu yang sama dengan 2015-02-05 00:00:00. Yang kedua biasanya adalah notasi yang disukai.

Mendapatkan setelan kuota dari konfigurasi produk API

Anda dapat menetapkan batas kuota dalam konfigurasi produk API. Batasan tersebut tidak otomatis menerapkan kuota. Sebagai gantinya, Anda dapat melihat setelan kuota produk dalam kebijakan kuota. Berikut ini beberapa keuntungan menetapkan kuota pada produk untuk referensi kebijakan kuota:

  • Kebijakan kuota dapat menggunakan setelan seragam di semua proxy API dalam produk API.
  • Anda dapat mengubah runtime pada setelan kuota pada produk API, dan kebijakan kuota yang merujuk nilai tersebut akan otomatis memperbarui nilai kuota.

Untuk informasi lebih lanjut tentang penggunaan setelan kuota dari produk API, lihat contoh "Kuota Dinamis" di atas..

Untuk info tentang cara mengonfigurasi produk API dengan batas kuota, lihat Membuat produk API.

Referensi elemen

Berikut adalah elemen dan atribut yang dapat Anda konfigurasi di kebijakan ini. Perhatikan bahwa beberapa kombinasi elemen bersifat eksklusif satu sama lain atau tidak diperlukan. Lihat contoh untuk penggunaan spesifik. Variabel verifyapikey.VerifyAPIKey.apiproduct.* di bawah tersedia secara default saat kebijakan Kunci API Verifikasi yang disebut "VerifyAPIKey" digunakan untuk memeriksa kunci API aplikasi dalam permintaan. Nilai variabel berasal dari setelan kuota pada produk API yang terkait dengan kunci, seperti yang dijelaskan dalam Mendapatkan setelan kuota dari konfigurasi produk API.

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="5000"/>
        <Allow class="off_peak_time" count="1000"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval> 
   <TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2017-7-16 12:00:00</StartTime> 
   <Distributed>false</Distributed> 
   <Synchronous>false</Synchronous> 
   <AsynchronousConfiguration> 
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds> 
      <SyncMessageCount>5</SyncMessageCount> 
   </AsynchronousConfiguration> 
   <Identifier/> 
   <MessageWeight/> 
</Quota>

Atribut <Quota>

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">

Atribut berikut bersifat khusus untuk kebijakan ini.

Atribut Deskripsi Default Ketersediaan
tipe

Digunakan untuk menentukan waktu dan cara penghitung kuota memeriksa penggunaan kuota. Lihat Jenis kebijakan kuota untuk mengetahui informasi selengkapnya.

Jika Anda menghilangkan nilai type, penghitung akan dimulai di awal menit/jam/hari/minggu/bulan.

Nilai yang valid meliputi:

  • calendar: Mengonfigurasi kuota berdasarkan waktu mulai eksplisit. Penghitung Kuota untuk setiap aplikasi diperbarui berdasarkan nilai <StartTime>, <Interval>, dan <TimeUnit> yang Anda tetapkan.
  • rollingwindow: Mengonfigurasi kuota yang menggunakan "rolling window" untuk menentukan penggunaan kuota. Dengan rollingwindow, Anda menentukan ukuran jendela dengan elemen <Interval> dan <TimeUnit>; misalnya, 1 hari. Ketika permintaan masuk, Edge akan melihat waktu persis permintaan (misalnya pukul 17.01), menghitung jumlah permintaan yang masuk antara pukul 17.01 hingga pukul 17.01 di hari sebelumnya (1 hari), dan menentukan apakah kuota telah terlampaui atau tidak selama periode tersebut.
  • flexi: Mengonfigurasi kuota yang menyebabkan penghitung dimulai saat pesan permintaan pertama diterima dari aplikasi, dan direset berdasarkan nilai <Interval>, dan <TimeUnit>.
kalender Opsional

Tabel berikut menjelaskan atribut yang sama untuk semua elemen induk kebijakan:

Atribut Deskripsi Default Ketersediaan
name

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.

T/A Wajib
continueOnError

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.

false Opsional
enabled

Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.

true Opsional
async

Atribut ini sudah tidak digunakan lagi.

false Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.

<DisplayName>Policy Display Name</DisplayName>
Default

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.

Ketersediaan Opsional
Jenis String

Elemen <Allow>

Menentukan batas jumlah untuk kuota. Jika penghitung untuk kebijakan mencapai nilai batas ini, panggilan berikutnya akan ditolak sampai penghitung direset.

Di bawah ini adalah tiga cara untuk menetapkan elemen <Allow>:

<Allow count="2000"/> 
<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 
<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 

Jika Anda menentukan count dan countRef, countRef akan mendapatkan prioritas. Jika countRef tidak di-resolve saat runtime, nilai count akan digunakan.

Default: T/A
Kehadiran: Opsional
Jenis: Bilangan Bulat

Atribut

Atribut Deskripsi Default Ketersediaan
jumlah

Gunakan untuk menentukan jumlah pesan bagi kuota.

Misalnya, nilai atribut count 100, Interval 1, dan TimeUnit bulan menentukan kuota 100 pesan per bulan.

2000 Opsional
countRef

Gunakan untuk menentukan variabel flow yang berisi jumlah pesan untuk kuota. countRef lebih diprioritaskan daripada atribut count.

tidak ada Opsional

Elemen <Allow>/<Class>

Elemen <Class> memungkinkan Anda mengkondisikan nilai elemen <Allow> berdasarkan nilai variabel flow. Untuk setiap tag turunan <Allow> dari <Class> yang berbeda, kebijakan akan mempertahankan penghitung yang berbeda.

Untuk menggunakan elemen <Class>, tentukan variabel flow menggunakan atribut ref ke tag <Class>. Edge kemudian menggunakan nilai variabel flow untuk memilih salah satu tag turunan <Allow> guna menentukan jumlah kebijakan yang diizinkan. Edge mencocokkan nilai variabel flow dengan atribut class tag <Allow>, seperti ditunjukkan di bawah ini:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

Dalam contoh ini, penghitung kuota saat ini ditentukan oleh nilai parameter kueri time_variable yang diteruskan dengan setiap permintaan. Variabel tersebut dapat memiliki nilai peak_time atau off_peak_time. Jika parameter kueri berisi nilai yang tidak valid, kebijakan akan menampilkan error pelanggaran kuota.

Default: T/A
Kehadiran: Opsional
Jenis: T/A

Atribut

Atribut Deskripsi Default Ketersediaan
referensi

Gunakan untuk menentukan variabel flow yang berisi class kuota untuk kuota.

tidak ada Wajib

Elemen <Allow>/<Class>/<Allow>

Elemen <Allow> menentukan batas untuk penghitung kuota yang ditentukan oleh elemen <Class>. Untuk setiap tag turunan <Allow> dari <Class> yang berbeda, kebijakan mempertahankan penghitung yang berbeda.

Contoh:

<Allow>
  <Class ref="request.queryparam.time_variable">
    <Allow class="peak_time" count="5000"/>
    <Allow class="off_peak_time" count="1000"/>
  </Class>
</Allow>

Dalam contoh ini, kebijakan Kuota menyimpan dua penghitung kuota bernama peak_time dan off_peak_time.

Default: T/A
Kehadiran: Opsional
Jenis: T/A

Atribut

Atribut Deskripsi Default Ketersediaan
class

Menentukan nama penghitung kuota.

tidak ada Wajib
jumlah Menentukan batas kuota untuk penghitung. tidak ada Wajib

Elemen <Interval>

Gunakan untuk menentukan bilangan bulat (misalnya 1, 2, 5, 60, dan seterusnya) yang akan disambungkan dengan TimeUnit yang Anda tentukan (menit, jam, hari, minggu, atau bulan) untuk menentukan periode waktu selama Edge menghitung penggunaan kuota.

Misalnya, Interval dari 24 dengan TimeUnit bernilai hour berarti kuota akan dihitung selama 24 jam.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>
Default: tidak ada
Kehadiran: Wajib
Jenis: Bilangan Bulat

Atribut

Atribut Deskripsi Default Ketersediaan
referensi

Gunakan untuk menentukan variabel flow yang berisi interval untuk kuota. ref lebih diprioritaskan daripada nilai interval eksplisit. Jika referensi dan nilai ditetapkan, referensi akan mendapatkan prioritas. Jika ref tidak di-resolve saat runtime, nilai akan digunakan.

tidak ada Opsional

Elemen <TimeUnit>

Gunakan untuk menentukan satuan waktu yang berlaku untuk kuota.

Misalnya, Interval dari 24 dengan TimeUnit bernilai hour berarti kuota akan dihitung selama 24 jam.

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
Default: tidak ada
Kehadiran: Wajib
Jenis:

String. Pilih dari minute, hour, day, week, atau month.

Atribut

Atribut Deskripsi Default Ketersediaan
referensi Gunakan untuk menentukan variabel flow yang berisi unit waktu untuk kuota. ref lebih diprioritaskan daripada nilai interval eksplisit. Jika ref tidak di-resolve saat runtime, nilai tersebut akan digunakan. tidak ada Opsional

Elemen <StartTime>

Jika type ditetapkan ke calendar,, akan ditentukan tanggal dan waktu penghitung kuota akan mulai dihitung, terlepas dari apakah ada permintaan yang telah diterima dari aplikasi apa pun.

Anda harus menyediakan StartTime eksplisit jika type ditetapkan secara eksplisit ke calendar,. Anda tidak dapat menggunakan referensi ke variabel alur. Jika menentukan nilai StartTime saat tidak ada nilai type yang ditetapkan, Anda akan menerima error.

Contoh:

<StartTime>2017-7-16 12:00:00</StartTime>
Default: tidak ada
Kehadiran: Wajib jika type ditetapkan ke calendar.
Jenis:

String dalam format tanggal dan waktu ISO 8601.

Elemen <Distributed>

Penginstalan Edge dapat menggunakan satu atau beberapa Message Processors untuk memproses permintaan. Setel elemen ini ke true untuk menentukan bahwa kebijakan harus mempertahankan penghitung pusat dan terus menyinkronkannya di semua Pemroses Pesan. Pemroses pesan dapat berada di seluruh zona ketersediaan dan/atau region.

Jika menggunakan nilai default false, Anda mungkin melebihi kuota karena jumlah untuk setiap Pemroses Pesan tidak dibagikan:

<Distributed>true</Distributed>

Untuk menjamin bahwa penghitung disinkronkan dan diperbarui pada setiap permintaan, tetapkan <Distributed> dan <Synchronous> ke benar (true):

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>
Default: false
Kehadiran: Opsional
Jenis: Boolean

Elemen <Synchronous>

Tetapkan ke true untuk mengupdate penghitung kuota terdistribusi secara sinkron. Ini berarti update pada penghitung dilakukan bersamaan dengan pemeriksaan kuota pada permintaan ke API. Tetapkan ke true jika Anda tidak boleh mengizinkan panggilan API apa pun melebihi kuota.

Tetapkan ke false untuk memperbarui penghitung kuota secara asinkron. Artinya, ada kemungkinan bahwa beberapa panggilan API yang melebihi kuota akan berjalan, bergantung pada kapan penghitung kuota di repositori pusat diupdate secara asinkron. Namun, Anda tidak akan menghadapi potensi dampak performa yang terkait dengan update sinkron.

Interval update asinkron default adalah 10 detik. Gunakan elemen AsynchronousConfiguration untuk mengonfigurasi perilaku asinkron ini.

<Synchronous>false</Synchronous>
Default: false
Kehadiran: Opsional
Jenis: Boolean

Elemen <AsynchronousConfiguration>

Mengonfigurasi interval sinkronisasi di antara penghitung kuota terdistribusi saat elemen konfigurasi kebijakan <Synchronous> tidak ada atau ada dan disetel ke false.

Anda dapat menyinkronkan setelah jangka waktu tertentu atau jumlah pesan, menggunakan elemen turunan SyncIntervalInSeconds atau SyncMessageCount. Keduanya bersifat eksklusif satu sama lain. Misalnya,

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

atau

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
Default: SyncIntervalInSeconds = 10 detik
Kehadiran: Opsional; diabaikan jika <Synchronous> ditetapkan ke true.
Jenis:

Kompleks

Elemen <AsynchronousConfiguration>/<SyncIntervalInSeconds>

Gunakan metode ini untuk mengganti perilaku default yang menjalankan update asinkron setelah interval 10 detik.

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

Interval sinkronisasi harus >= 10 detik seperti yang dijelaskan dalam topik Batas.

Default: 10
Kehadiran: Opsional
Jenis:

Bilangan Bulat

Elemen <AsynchronousConfiguration>/<SyncMessageCount>

Menentukan jumlah permintaan di seluruh pemroses pesan Apigee di antara pembaruan kuota.

<AsynchronousConfiguration>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>

Contoh ini menetapkan bahwa jumlah kuota diperbarui setiap 5 permintaan di setiap pemroses pesan Apigee Edge.

Default: t/a
Kehadiran: Opsional
Jenis:

Bilangan Bulat

Elemen <Identifier>

Gunakan elemen <Identifier> untuk mengonfigurasi kebijakan guna membuat penghitung unik berdasarkan variabel flow.

Anda dapat membuat penghitung unik untuk karakteristik yang ditentukan oleh variabel flow. Misalnya, Anda dapat menggunakan alamat email developer untuk mengaitkan kuota ke developer tertentu. Anda dapat menggunakan berbagai variabel untuk mengidentifikasi kuota, baik Anda menggunakan variabel kustom maupun variabel yang telah ditetapkan, seperti yang tersedia pada kebijakan Verifikasi Kunci API. Lihat juga Referensi variabel.

Jika Anda tidak menggunakan elemen ini, kebijakan akan menggunakan penghitung tunggal yang diterapkan terhadap kuota.

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.

<Identifier ref="verifyapikey.verify-api-key.client_id"/>
Default: T/A
Kehadiran: Opsional
Jenis:

String

Atribut

Atribut Deskripsi Default Ketersediaan
referensi

Menentukan variabel flow yang mengidentifikasi penghitung yang akan digunakan untuk permintaan. ID dapat berupa header HTTP, parameter kueri, parameter formulir, atau konten pesan yang unik untuk setiap aplikasi, pengguna aplikasi, developer aplikasi, produk API, atau karakteristik lainnya.

<Identifier> yang paling umum digunakan untuk mengidentifikasi aplikasi secara unik adalah client_id. client_id adalah nama lain untuk kunci API, atau kunci konsumen, yang dibuat untuk aplikasi saat didaftarkan dalam organisasi di Apigee Edge. Anda dapat menggunakan ID ini jika telah mengaktifkan kunci API atau kebijakan otorisasi OAuth untuk API Anda.

Dalam situasi tertentu, Setelan kuota harus diambil jika client_id tidak tersedia, seperti saat tidak ada kebijakan keamanan yang diterapkan. Dalam situasi tersebut, Anda dapat menggunakan kebijakan Access Entity untuk mengambil setelan produk API yang sesuai, lalu mengekstrak nilai menggunakan ExtractVariables, lalu menggunakan variabel konteks yang diekstrak dalam kebijakan Quota. Untuk mengetahui informasi selengkapnya, lihat kebijakan Akses Entitas.

T/A Opsional

Elemen <MessageWeight>

Gunakan untuk menentukan berat yang ditetapkan pada setiap pesan. Gunakan bobot pesan untuk meningkatkan dampak pesan permintaan yang, misalnya, mengonsumsi lebih banyak resource komputasi daripada yang lain.

Misalnya, Anda ingin menghitung pesan POST dua kali lebih "berat" atau mahal, dibandingkan pesan GET. Oleh karena itu, tetapkan MessageWeight ke 2 untuk POST dan 1 untuk GET. Anda bahkan dapat menetapkan MessageWeight ke 0 sehingga permintaan tidak memengaruhi penghitung. Dalam contoh ini, jika kuota adalah 10 pesan per menit dan MessageWeight untuk permintaan POST adalah 2, maka kuota akan mengizinkan 5 permintaan POST dalam interval 10 menit. Permintaan tambahan apa pun, POST atau GET, sebelum reset penghitung ditolak.

Nilai yang mewakili MessageWeight harus ditentukan oleh variabel flow, dan dapat diekstrak dari header HTTP, parameter kueri, payload permintaan XML atau JSON, atau variabel flow lainnya. Misalnya, Anda menetapkannya dalam header bernama weight:

<MessageWeight ref="message_weight"/>
Default: T/A
Kehadiran: Opsional
Jenis:

Bilangan Bulat

Variabel alur

Variabel Alur yang telah ditetapkan berikut secara otomatis diisi saat kebijakan Kuota dijalankan. Untuk informasi selengkapnya tentang variabel Alur, lihat Referensi variabel.

Variabel Jenis Izin Deskripsi
ratelimit.{policy_name}.allowed.count Panjang Hanya Baca Menampilkan jumlah kuota yang diizinkan
ratelimit.{policy_name}.used.count Panjang Hanya Baca Menampilkan kuota saat ini yang digunakan dalam interval kuota
ratelimit.{policy_name}.available.count Panjang Hanya Baca Menampilkan jumlah kuota yang tersedia dalam interval kuota
ratelimit.{policy_name}.exceed.count Panjang Hanya Baca Menampilkan 1 setelah kuota terlampaui.
ratelimit.{policy_name}.total.exceed.count Panjang Hanya Baca Menampilkan 1 setelah kuota terlampaui.
ratelimit.{policy_name}.expiry.time Panjang Hanya Baca

Menampilkan waktu UTC dalam milidetik yang menentukan kapan masa berlaku kuota berakhir dan interval kuota baru dimulai.

Jika jenis kebijakan Kuota adalah rollingwindow, nilai ini tidak valid karena interval kuota tidak akan pernah berakhir.

ratelimit.{policy_name}.identifier String Hanya Baca Menampilkan referensi ID (klien) yang dilampirkan pada kebijakan
ratelimit.{policy_name}.class String Hanya Baca Menampilkan class yang terkait dengan ID klien
ratelimit.{policy_name}.class.allowed.count Panjang Hanya Baca Menampilkan jumlah kuota yang diizinkan yang ditentukan di class
ratelimit.{policy_name}.class.used.count Panjang Hanya Baca Menampilkan kuota yang telah digunakan dalam sebuah class
ratelimit.{policy_name}.class.available.count Panjang Hanya Baca Menampilkan jumlah kuota yang tersedia di class
ratelimit.{policy_name}.class.exceed.count Panjang Hanya Baca Menampilkan jumlah permintaan yang melebihi batas di class dalam interval kuota saat ini
ratelimit.{policy_name}.class.total.exceed.count Panjang Hanya Baca Menampilkan jumlah total permintaan yang melebihi batas di class pada semua interval kuota, sehingga merupakan jumlah class.exceed.count untuk semua interval kuota.
ratelimit.{policy_name}.failed Boolean Hanya Baca

Menunjukkan apakah kebijakan gagal atau tidak (true atau false).

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Edge 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 Perbaiki
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Terjadi jika elemen <Interval> tidak ditentukan dalam kebijakan Kuota. Elemen ini bersifat wajib dan digunakan untuk menentukan interval waktu yang berlaku untuk kuota. Interval waktu dapat berupa menit, jam, hari, minggu, atau bulan seperti yang ditentukan dengan elemen <TimeUnit>.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Terjadi jika elemen <TimeUnit> tidak ditentukan dalam kebijakan Kuota. Elemen ini bersifat wajib dan digunakan untuk menentukan satuan waktu yang berlaku untuk kuota. Interval waktunya dapat dalam menit, jam, hari, minggu, atau bulan.
policies.ratelimit.InvalidMessageWeight 500 Terjadi jika nilai elemen <MessageWeight> yang ditentukan melalui variabel flow tidak valid (nilai non-bilangan bulat).
policies.ratelimit.QuotaViolation 500 Batas kuota terlampaui. T/A

Error saat deployment

Nama error Penyebab Perbaiki
InvalidQuotaInterval Jika interval kuota yang ditentukan dalam elemen <Interval> bukan bilangan bulat, deployment proxy API akan gagal. Misalnya, jika interval kuota yang ditentukan adalah 0,1 dalam elemen <Interval>, deployment proxy API akan gagal.
InvalidQuotaTimeUnit Jika unit waktu yang ditentukan dalam elemen <TimeUnit> tidak didukung, deployment proxy API akan gagal. Satuan waktu yang didukung adalah minute, hour, day, week, dan month.
InvalidQuotaType Jika jenis kuota yang ditentukan oleh atribut type di elemen <Quota> tidak valid, deployment proxy API akan gagal. Jenis kuota yang didukung adalah default, calendar, flexi, dan rollingwindow.
InvalidStartTime Jika format waktu yang ditentukan dalam elemen <StartTime> tidak valid, deployment proxy API akan gagal. Format yang valid adalah yyyy-MM-dd HH:mm:ss, yang merupakan format tanggal dan waktu ISO 8601. Misalnya, jika waktu yang ditetapkan dalam elemen <StartTime> adalah 7-16-2017 12:00:00, deployment proxy API akan gagal.
StartTimeNotSupported Jika elemen <StartTime> ditentukan yang jenis kuotanya bukan jenis calendar, deployment proxy API akan gagal. Elemen <StartTime> hanya didukung untuk jenis kuota calendar. Misalnya, jika atribut type ditetapkan ke flexi atau rolling window dalam elemen <Quota>, deployment proxy API akan gagal.
InvalidTimeUnitForDistributedQuota Jika elemen <Distributed> disetel ke true dan elemen <TimeUnit> disetel ke second, deployment proxy API akan gagal. Unit waktu second tidak valid untuk kuota yang didistribusikan.
InvalidSynchronizeIntervalForAsyncConfiguration Jika nilai yang ditentukan untuk elemen <SyncIntervalInSeconds> dalam elemen <AsynchronousConfiguration> dalam kebijakan Kuota kurang dari nol, deployment proxy API akan gagal.
InvalidAsynchronizeConfigurationForSynchronousQuota Jika nilai elemen <AsynchronousConfiguration> disetel ke true dalam kebijakan Kuota, yang juga memiliki konfigurasi asinkron yang ditetapkan menggunakan elemen <AsynchronousConfiguration>, deployment proxy API akan gagal.

Variabel kesalahan

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

Variabel Dari 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 dari kode kesalahan. fault.name Matches "QuotaViolation"
ratelimit.policy_name.failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. ratelimit.QT-QuotaPolicy.failed = true

Contoh respons error

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.QuotaViolation"
      },
      "faultstring":"Rate limit quota violation. Quota limit  exceeded. Identifier : _default"
   }
}

Contoh aturan kesalahan

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

Skema

Topik terkait

Kebijakan ResetQuota

Kebijakan SpikeArrest

Membandingkan Kebijakan Kuota, Penahanan Lonjakan, dan Batas Kapasitas Serentak