Kebijakan kuota

Anda sedang melihat dokumentasi Apigee Edge.
Lihat dokumentasi Apigee X.

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 Anda dapat 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 Spike Arrest. Lihat kebijakan Penahanan Lonjakan.

Video

Video berikut memperkenalkan pengelolaan kuota dengan kebijakan Kuota:

Pengantar (New Edge)

Pengantar (Edge Klasik)

Kuota Dinamis

Terdistribusi & Sinkron

Bobot Pesan

Kalender

Geser Jendela

Flexi

Kuota Bersyarat

Variabel Flow

Penanganan Error

Sample

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

Lebih Banyak Kuota Dinamis

<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>

Dengan kuota dinamis, Anda dapat mengonfigurasi satu Kebijakan kuota yang menerapkan setelan Kuota yang berbeda berdasarkan informasi yang diteruskan ke Kebijakan kuota. Istilah lain untuk setelan Kuota dalam konteks ini adalah "Paket Layanan". Kuota dinamis memeriksa "Paket Layanan" aplikasi, lalu menerapkan setelan tersebut.

Catatan: Jika Anda menentukan nilai dan referensi untuk sebuah elemen, referensi akan diprioritaskan. Jika referensi tidak terselesaikan pada saat runtime, nilainya akan digunakan.

Misalnya, saat membuat produk API, Anda dapat memilih untuk menetapkan batas kuota, unit waktu, dan interval yang diizinkan. Namun, menetapkan nilai ini pada produk API tidak memberlakukan penggunaannya di proxy API. Anda juga harus menambahkan Kebijakan kuota ke proxy API yang membaca nilai-nilai ini. Lihat Membuat produk API untuk mengetahui informasi selengkapnya.

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

Opsi lainnya adalah menetapkan atribut khusus pada setiap 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, unit waktu, dan interval. Selanjutnya, Anda dapat merujuk 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 pengembang.

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

  • Variabel flow
  • Properti di produk, aplikasi, atau developer API
  • Peta nilai kunci (KVM)
  • Header, parameter kueri, parameter formulir, dsb.

Untuk setiap proxy API, Anda dapat menambahkan kebijakan Kuota yang mereferensikan variabel yang sama dengan semua kebijakan Kuota lainnya di semua proxy lainnya, atau kebijakan Kuota 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 mengeluarkan error.

Penghitung kuota untuk setiap aplikasi di-refresh 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, pembaruan berikutnya adalah pada pukul 15.30 GMT pada 18 Februari 2017.

Penghitung Akses

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

Proxy API memiliki akses ke variabel flow yang ditetapkan oleh kebijakan Kuota. Anda dapat mengakses variabel flow 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 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 MenetapkanMessage berikut untuk menampilkan nilai variabel alur Kuota 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 satu jam. Kebijakan ini mereset penghitung kuota di bagian atas setiap jam. Jika penghitung mencapai kuota 10.000 panggilan sebelum akhir jam, panggilan di luar 10.000 panggilan 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 pada 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 hingga jumlah tersebut direset di bagian atas jam.

Waktu reset penghitung didasarkan pada kombinasi <Interval> dan <TimeUnit>. Misalnya, jika Anda menyetel <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 pada proxy API Anda. Misalnya, Anda dapat menempatkannya pada PreFlow Proxy agar dapat dieksekusi di setiap permintaan. Atau, Anda dapat menempatkannya pada 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 Anda. Setiap kebijakan Kuota mempertahankan penghitungnya sendiri, berdasarkan atribut name kebijakan.

Tetapkan 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 menetapkan 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 bagi setiap client ID. Pada permintaan ke proxy Anda, aplikasi klien kemudian akan meneruskan header yang berisi clientID, seperti yang ditunjukkan dalam contoh di atas.

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

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

Jika menggunakan kebijakan VerifyAPIKey untuk memvalidasi kunci API, atau kebijakan OAuthV2 dengan token OAuth, Anda dapat menggunakan informasi di token atau kunci API guna menentukan penghitung individual 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 sekarang menentukan penghitungnya sendiri di 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 dengan 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 proxy API selama jangka waktu tertentu, seperti menit, jam, hari, minggu, atau bulan. Kebijakan ini mempertahankan 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 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 dihitung pada hari pertama atau hari terakhir dari periode tersebut; tidak ada area permintaan tambahan yang diizinkan hingga penghitung Kuota secara otomatis direset pada akhir interval waktu yang ditentukan, atau hingga Kuota direset secara eksplisit menggunakan kebijakan Reset Kuota.

Variasi dari Quota yang disebut SpikeArrest mencegah lonjakan traffic (atau burst) yang dapat disebabkan oleh peningkatan penggunaan secara tiba-tiba, klien yang berisi bug, atau serangan berbahaya. Untuk mengetahui informasi selengkapnya tentang SpikeArrest, lihat kebijakan Spike Arrest.

Kuota berlaku untuk masing-masing proxy API dan tidak didistribusikan di antara proxy API. Misalnya, jika Anda memiliki tiga proxy API dalam produk API, satu kuota tidak akan dibagikan ke 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 direset, seperti yang ditunjukkan pada tabel berikut:

Unit Waktu Reset (atau null) yang direset kalender direset reset flexi
menit Awal menit berikutnya Satu menit setelah <StartTime> Satu menit setelah permintaan pertama
jam Bagian atas 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 Tengah malam pada hari Minggu di akhir minggu Satu minggu setelah <StartTime> Satu minggu setelah permintaan pertama
bulan GMT tengah malam dari hari terakhir setiap bulan 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 berkelanjutan dapat digunakan dengan menyetel ukuran "periode" kuota, misalnya periode satu jam atau satu hari. Saat permintaan baru masuk, kebijakan ini akan menentukan apakah kuota telah terlampaui dalam "periode" terakhir.

Misalnya, Anda menentukan periode dua jam yang mengizinkan 1.000 permintaan. Permintaan baru masuk pada 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. Kini, kebijakan tersebut menghitung jumlah kuota sejak pukul 14.46 untuk mengetahui apakah batas tersebut telah terlampaui.

Untuk jenis rollingwindow, penghitung tidak akan 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 flow (Alur A, B, dan C) di proxy API. Meskipun digunakan dalam beberapa alur, pendekatan ini mempertahankan satu penghitung yang diperbarui oleh semua instance kebijakan:

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

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

Menggunakan kebijakan Kuota yang sama di lebih dari satu tempat dalam alur proxy API, yang dapat tidak sengaja menyebabkan Kuota habis lebih cepat dari yang Anda harapkan, merupakan anti-pola yang dijelaskan dalam Buku Apigee Edge Antipatterns.

Atau, Anda dapat menentukan beberapa kebijakan Kuota di proxy API Anda dan menggunakan kebijakan yang 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, satu 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 ditentukan dalam ISO 8601 Standar Internasional.

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

Waktu didefinisikan 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. Parameter yang disebut biasanya adalah notasi pilihan.

Mendapatkan setelan kuota dari konfigurasi produk API

Anda dapat menetapkan batas kuota di konfigurasi produk API. Batas tersebut tidak menerapkan kuota secara otomatis. Sebagai gantinya, Anda dapat merujuk setelan kuota produk di kebijakan kuota. Berikut adalah beberapa keuntungan dari menetapkan kuota produk untuk referensi kebijakan kuota:

  • Kebijakan kuota dapat menggunakan setelan yang seragam di semua proxy API dalam produk API.
  • Anda dapat membuat perubahan runtime pada setelan kuota di produk API, dan kebijakan kuota yang mereferensikan nilai tersebut akan otomatis memiliki nilai kuota yang telah diperbarui.

Untuk mengetahui informasi lebih lanjut mengenai 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 konfigurasikan pada kebijakan ini. Perhatikan bahwa beberapa kombinasi elemen saling eksklusif atau tidak diperlukan. Lihat contoh untuk penggunaan tertentu. Variabel verifyapikey.VerifyAPIKey.apiproduct.* di bawah tersedia secara default saat kebijakan Verify API Key yang disebut "VerifyAPIKey" digunakan untuk memeriksa kunci API aplikasi dalam permintaan. Nilai variabel berasal dari setelan kuota pada produk API yang dikaitkan 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 khusus untuk kebijakan ini.

Atribut Deskripsi Default Ketersediaan
tipe

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

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

Nilai yang valid mencakup:

  • calendar: Mengonfigurasi kuota berdasarkan waktu mulai eksplisit. Penghitung Kuota untuk setiap aplikasi dimuat ulang 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. Saat permintaan masuk, Edge melihat waktu persis permintaan (misalnya pukul 17.01), menghitung jumlah permintaan yang masuk antara pukul 17.01 dan 17.01 pada hari sebelumnya (1 hari), dan menentukan apakah kuota telah terlampaui selama periode tersebut atau tidak.
  • flexi: Mengonfigurasi kuota yang akan menyebabkan penghitung dimulai saat pesan permintaan pertama diterima dari aplikasi, dan direset berdasarkan nilai <Interval>, serta <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.

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

T/A Wajib
continueOnError

Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Hal ini wajar untuk sebagian besar kebijakan.

Tetapkan ke true agar eksekusi flow dapat dilanjutkan bahkan setelah kebijakan gagal.

false Opsional
enabled

Tetapkan ke true untuk menerapkan kebijakan.

Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan ini tidak akan diterapkan meskipun tetap dilampirkan ke flow.

benar Opsional
async

Atribut ini tidak digunakan lagi.

false Tidak digunakan lagi

Elemen <DisplayName>

Selain atribut name, beri label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa natural yang berbeda.

<DisplayName>Policy Display Name</DisplayName>
Default

T/A

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

Ketersediaan Opsional
Type String

Elemen <Allow>

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

Berikut 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, maka countRef akan diprioritaskan. Jika countRef tidak di-resolve pada runtime, nilai count akan digunakan.

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

Atribut

Atribut Deskripsi Default Ketersediaan
jumlah

Gunakan untuk menentukan jumlah pesan untuk kuota.

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

2.000 Opsional
countRef

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

tidak ada Opsional

Elemen <Allow>/<Class>

Elemen <Class> memungkinkan Anda mengondisikan nilai elemen <Allow> berdasarkan nilai variabel alur. Untuk setiap tag turunan <Allow> yang berbeda dari <Class>, kebijakan ini mempertahankan penghitung yang berbeda.

Untuk menggunakan elemen <Class>, tentukan variabel flow menggunakan atribut ref ke tag <Class>. Kemudian, Edge 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 yang ditunjukkan di bawah:

<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
Rujukan

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

tidak ada Wajib diisi

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

Elemen <Allow> menentukan batas penghitung kuota yang ditentukan oleh elemen <Class>. Untuk setiap tag turunan <Allow> yang berbeda dari <Class>, kebijakan akan 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 mempertahankan dua penghitung kuota yang 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 diisi
jumlah Menentukan batas kuota untuk penghitung. tidak ada Wajib diisi

Elemen <Interval>

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

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

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

Atribut

Atribut Deskripsi Default Ketersediaan
Rujukan

Gunakan untuk menentukan variabel flow yang berisi interval untuk kuota. ref lebih diprioritaskan daripada nilai interval eksplisit. Jika referensi dan nilai ditentukan, referensi akan diprioritaskan. Jika ref tidak di-resolve pada runtime, nilainya akan digunakan.

tidak ada Opsional

Elemen <TimeUnit>

Gunakan untuk menentukan unit waktu yang berlaku untuk kuota.

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

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

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

Atribut

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

Elemen <StartTime>

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

Anda harus memberikan StartTime eksplisit saat type ditetapkan secara eksplisit ke calendar,. Anda tidak dapat menggunakan referensi ke variabel flow. Jika Anda 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 Pemroses Pesan untuk memproses permintaan. Tetapkan 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 true:

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

Elemen <Synchronous>

Tetapkan ke true untuk memperbarui penghitung kuota terdistribusi secara sinkron. Hal ini berarti bahwa pembaruan pada penghitung dibuat pada saat yang sama dengan kuota yang diperiksa pada permintaan ke API. Setel ke true jika Anda tidak mengizinkan panggilan API melebihi kuota.

Tetapkan ke false untuk memperbarui penghitung kuota secara asinkron. Artinya, beberapa panggilan API yang melebihi kuota mungkin akan diteruskan, bergantung pada kapan penghitung kuota di repositori pusat diperbarui secara asinkron. Namun, Anda tidak akan melihat potensi dampak performa yang berkaitan dengan update sinkron.

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

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

Elemen <AsyncConfiguration>

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

Anda dapat menyinkronkan setelah jangka waktu atau jumlah pesan, menggunakan elemen turunan SyncIntervalInSeconds atau SyncMessageCount. Saling eksklusif. 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 <AsyncConfiguration>/<SyncIntervalInseconds>

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

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

Interval sinkronisasi harus lebih dari 10 detik seperti yang dijelaskan di topik Batas.

Default: 10
Kehadiran: Opsional
Jenis:

Bilangan bulat

Elemen <AsyncConfiguration>/<SyncMessageCount>

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

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

Contoh ini menentukan 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 dengan developer tertentu. Anda dapat menggunakan berbagai variabel untuk mengidentifikasi kuota, baik menggunakan variabel khusus atau variabel yang telah ditetapkan, seperti variabel yang tersedia dengan kebijakan Kunci API Verifikasi. Baca juga Referensi variabel.

Jika Anda tidak menggunakan elemen ini, kebijakan akan menggunakan satu penghitung 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
Rujukan

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 beberapa situasi, setelan Kuota harus diambil jika client_id tidak tersedia, misalnya ketika tidak ada kebijakan keamanan yang diterapkan. Dalam situasi tersebut, Anda dapat menggunakan kebijakan Entitas Akses untuk mengambil setelan produk API yang sesuai, lalu mengekstrak nilai menggunakan ExtractVariables, lalu menggunakan variabel konteks yang diekstrak dalam kebijakan Kuota. Untuk informasi selengkapnya, lihat kebijakan Akses Entitas.

T/A Opsional

Elemen <MessageWeight>

Gunakan untuk menentukan bobot yang ditetapkan ke setiap pesan. Gunakan bobot pesan untuk meningkatkan dampak pesan permintaan, yang memakai lebih banyak resource komputasi daripada pesan lainnya.

Misalnya, Anda ingin menghitung pesan POST sebagai dua kali lebih "berat" atau mahal, seperti pesan GET. Oleh karena itu, Anda menetapkan 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, kuota akan mengizinkan 5 permintaan POST dalam interval 10 menit. Permintaan tambahan apa pun, yaitu POST atau GET, sebelum penghitung direset akan ditolak.

Nilai yang mewakili MessageWeight harus ditentukan oleh variabel alur, 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 flow

Variabel Flow yang telah ditentukan berikut ini akan otomatis diisi saat kebijakan Kuota dijalankan. Untuk informasi selengkapnya tentang Variabel alur, lihat Referensi variabel.

Variabel Type 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 kuota berakhir dan interval kuota baru dimulai.

Jika jenis Kebijakan kuota adalah rollingwindow, nilai ini tidak valid karena interval kuota tidak akan berakhir.

ratinglimit.{policy_name}.identifier String Hanya Baca Menampilkan referensi ID (klien) yang dilampirkan ke kebijakan
ratinglimit.{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 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}.gagal Boolean Hanya Baca

Menunjukkan apakah kebijakan gagal (benar atau salah).

Referensi error

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

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

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 tersebut. Interval waktu dapat berupa menit, jam, hari, minggu, atau bulan sebagaimana ditetapkan 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 waktu dapat berupa 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 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 ditetapkan adalah 0,1 di elemen <Interval>, maka deployment proxy API akan gagal.
InvalidQuotaTimeUnit Jika unit waktu yang ditentukan dalam elemen <TimeUnit> tidak didukung, deployment proxy API akan gagal. Unit waktu yang didukung adalah minute, hour, day, week, dan month.
InvalidQuotaType Jika jenis kuota yang ditentukan oleh atribut type dalam 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 ditentukan dalam elemen <StartTime> adalah 7-16-2017 12:00:00, maka deployment proxy API akan gagal.
StartTimeNotSupported Jika elemen <StartTime> ditentukan yang jenis kuotanya bukan jenis calendar, maka deployment proxy API akan gagal. Elemen <StartTime> hanya didukung untuk jenis kuota calendar. Misalnya, jika atribut type ditetapkan ke flexi atau rolling window di elemen <Quota>, deployment proxy API akan gagal.
InvalidTimeUnitForDistributedQuota Jika elemen <Distributed> disetel ke true dan elemen <TimeUnit> disetel ke second, maka 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 ditentukan menggunakan elemen <AsynchronousConfiguration>, maka 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 Lokasi Contoh
fault.name="fault_name" fault_name adalah nama fault, seperti yang tercantum pada tabel Error runtime di atas. Nama fault adalah bagian terakhir dari kode fault. fault.name Matches "QuotaViolation"
ratelimit.policy_name.failed policy_name adalah nama kebijakan yang ditentukan oleh pengguna yang melemparkan 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, Kuota Spike, dan Batas Tarif Serentak