Kebijakan kuota

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

ikon kebijakan

Ringkasan

Kuota adalah alokasi pesan permintaan yang dapat ditangani proxy API selama jangka waktu tertentu, seperti menit, jam, hari, minggu, atau bulan. Kebijakan Kuota mempertahankan penghitung yang menghitung jumlah permintaan yang diterima oleh proxy API. Kemampuan ini memungkinkan penyedia API menerapkan batas pada 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.

Kebijakan ini adalah Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.

Misalnya, jika Kuota ditentukan 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 periode tersebut; tidak ada permintaan tambahan yang diizinkan hingga penghitung Kuota secara otomatis direset pada akhir interval waktu yang ditentukan, atau hingga Kuota direset secara eksplisit menggunakan kebijakan ResetQuota.

Variasi pada kebijakan Kuota, kebijakan SpikeArrest, mencegah lonjakan traffic (atau burst) yang dapat disebabkan oleh peningkatan penggunaan secara tiba-tiba, klien yang bermasalah, atau serangan berbahaya.

Gunakan kebijakan Kuota untuk mengonfigurasi jumlah pesan permintaan yang diizinkan 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 kebijakan Kuota untuk melindungi dari lonjakan traffic secara keseluruhan. Untuk melakukannya, gunakan kebijakan SpikeArrest.

Video

Video ini memperkenalkan pengelolaan kuota dengan Kebijakan kuota:

Pengantar

Kuota Dinamis

Terdistribusi & Sinkron

Bobot Pesan

Kalender

Periode Berjalan

Flexi

Kuota Bersyarat

Variabel Alur

Penanganan Error

Jenis kebijakan kuota

Kebijakan Kuota mendukung beberapa cara berbeda untuk memulai dan mereset penghitung kuota. Anda dapat menentukan atribut yang akan digunakan dengan atribut type pada elemen <Quota>, seperti yang ditunjukkan pada contoh berikut:

<Quota name="QuotaPolicy" type="calendar">
  ...
</Quota>

Nilai type yang valid mencakup:

  • 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 "periode bergulir" untuk menentukan penggunaan kuota. Dengan rollingwindow, Anda menentukan ukuran periode dengan elemen <Interval> dan <TimeUnit>; misalnya, 1 hari. Saat permintaan masuk, Apigee akan melihat waktu persis permintaan tersebut (misalnya, 17.01), menghitung jumlah permintaan yang masuk antara waktu tersebut dan pukul 17.01 hari sebelumnya (1 hari), dan menentukan apakah kuota telah terlampaui selama periode tersebut.
  • flexi: Mengonfigurasi kuota yang menyebabkan penghitung dimulai saat pesan permintaan pertama diterima dari aplikasi, dan mereset berdasarkan nilai <Interval> dan <TimeUnit>.

Tabel berikut menjelaskan reset kuota untuk setiap jenis:

Unit Waktu Jenis
default (atau null) calendar flexi
menit Awal menit berikutnya Satu menit setelah <StartTime> Satu menit setelah permintaan pertama
jam Awal jam berikutnya Satu jam setelah <StartTime> Satu jam setelah permintaan pertama
hari Tengah malam GMT hari ini 24 jam setelah <StartTime> 24 jam setelah permintaan pertama
minggu Minggu tengah malam GMT pada akhir minggu Satu minggu setelah <StartTime> Satu minggu setelah permintaan pertama
bulan Tengah malam GMT pada 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 periode bergulir 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 periode waktu sebelumnya.

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, pada pukul 16.46, permintaan lain masuk. Sekarang kebijakan 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

Saat kebijakan kuota dieksekusi dalam alur proxy API, penghitung kuota akan dikurangi. Jika penghitung mencapai batasnya, tidak ada panggilan API lebih lanjut yang terkait dengan penghitung tersebut yang diizinkan. Bergantung pada konfigurasi Anda, kebijakan kuota dapat menggunakan satu atau beberapa penghitung. Penting untuk memahami kapan beberapa penghitung digunakan dan bagaimana penghitung tersebut berperilaku.

Cara penghitungan kuota untuk produk API

Jika proxy API disertakan dalam produk API, Anda dapat mengonfigurasi kebijakan kuota untuk menggunakan aturan kuota yang ditentukan dalam produk tersebut. Produk API dapat menentukan aturan kuota di tingkat produk atau di tingkat setiap operasi.

Penghitung kuota terpisah dikelola untuk setiap operasi yang ditentukan dalam produk API, dan aturan berikut dipatuhi:

  • Jika operasi memiliki kuota yang ditentukan, aturan kuota operasi akan lebih diutamakan daripada aturan kuota yang ditentukan di tingkat produk. Penghitung kuota terpisah dibuat untuk setiap operasi. Setiap panggilan API ke jalur operasi akan menambah penghitungnya.
  • Jika operasi tidak memiliki kuota yang ditentukan, aturan kuota tingkat produk akan diterapkan; tetapi, penghitung kuota terpisah masih dipertahankan untuk operasi tersebut. Dalam hal ini, penting untuk dipahami bahwa meskipun aturan kuota diambil dari definisi tingkat produk, operasi masih mempertahankan penghitungnya sendiri.
  • Jika produk API tidak menyertakan definisi kuota apa pun -- baik di tingkat produk maupun operasi -- aturan kuota yang ditentukan dalam kebijakan akan berlaku; namun, dalam hal ini, penghitung kuota terpisah akan dipertahankan untuk setiap operasi di produk API.

Bagian berikut menjelaskan opsi dan perilaku penghitung secara lebih mendetail.

Mengonfigurasi penghitung tingkat proxy API

Anda dapat mengonfigurasi produk API untuk mempertahankan jumlah kuota di cakupan proxy API. Dalam hal ini, konfigurasi kuota yang ditentukan di tingkat produk API digunakan bersama oleh semua operasi yang tidak memiliki kuota sendiri yang ditentukan. Efek dari konfigurasi ini adalah membuat penghitung global di tingkat proxy API untuk produk API ini.

Untuk mencapai konfigurasi ini, Anda harus menggunakan /apiproducts Apigee API untuk membuat atau memperbarui produk dan menetapkan quotaCountScope atribut ke PROXY dalam permintaan pembuatan atau pembaruan. Dengan konfigurasi PROXY, semua operasi yang ditentukan untuk produk API yang dikaitkan dengan proxy yang sama, dan tidak memiliki penghitungnya sendiri, akan berbagi penghitung kuota yang sama yang ditetapkan di tingkat produk API.

Pada Gambar 1, Operasi 1 dan 2 dikaitkan dengan Proxy1 dan Operasi 4 dan 5 dikaitkan dengan Proxy3. Karena quotaCounterScope=PROXY ditetapkan dalam produk API, setiap operasi ini memiliki setelan kuota tingkat produk API yang sama. Perhatikan bahwa meskipun operasi ini memiliki konfigurasi kuota yang sama, operasi ini menggunakan penghitung terpisah, berdasarkan pengaitan proxy-nya. Di sisi lain, Operasi 3 memiliki kumpulan konfigurasi kuotanya sendiri, sehingga tidak terpengaruh oleh flag quotaCounterScope.

Gambar 1: Penggunaan flag quotaCounterScope

Secara default, jika operasi tidak memiliki kuota yang ditentukan, aturan kuota tingkat produk akan diterapkan. Namun, penghitung kuota terpisah masih dipertahankan untuk operasi tersebut.

Cara penghitungan kuota jika tidak ada produk API yang digunakan

Jika tidak ada produk API yang terkait dengan proxy API, kebijakan kuota akan mempertahankan satu penghitung, terlepas dari berapa kali Anda mereferensikannya di 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 dalam beberapa alur, kebijakan ini mempertahankan satu penghitung yang diperbarui 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 dieksekusi dan penghitungnya = 4
  • Alur A dijalankan -> MyQuotaPolicy dijalankan dan penghitungnya = 5

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

Menggunakan kebijakan Kuota yang sama di lebih dari satu tempat dalam alur proxy API, yang dapat secara tidak sengaja menyebabkan Kuota habis lebih cepat dari yang Anda harapkan, adalah anti-pola yang dijelaskan dalam Pengantar anti-pola.

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

Membuat beberapa penghitung melalui konfigurasi kebijakan

Anda dapat menggunakan 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 mengetahui informasi selengkapnya tentang cara menggunakan elemen <Class> atau <Identifier>.

Notasi waktu

Semua waktu Kuota ditetapkan ke zona waktu Coordinated Universal Time (UTC).

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

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

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, 2021-02-04 24:00:00 memiliki tanggal dan waktu yang sama dengan 2021-02-05 00:00:00. Notasi kedua biasanya lebih disukai.

Mendapatkan setelan kuota dari konfigurasi produk API

Anda dapat menetapkan batas kuota di konfigurasi produk API. Batas tersebut tidak otomatis menerapkan kuota. Sebagai gantinya, Anda dapat mereferensikan setelan kuota produk dalam kebijakan kuota. Berikut beberapa keuntungan menetapkan kuota pada produk untuk dirujuk oleh 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 akan otomatis memperbarui nilai kuota.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan setelan kuota dari produk API, lihat contoh "Kuota Dinamis" di atas.

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

Mengonfigurasi penghitung kuota bersama

Biasanya, kebijakan Kuota menghitung semua permintaan yang dikirim ke proxy API. Untuk beberapa kasus penggunaan, Anda dapat menerapkan jumlah kuota permintaan yang masuk, tetapi juga menambah jumlah kuota untuk respons target yang memenuhi kondisi yang ditentukan. Tiga elemen kebijakan Kuota saat digunakan bersama, <SharedName>, <CountOnly>, dan <EnforceOnly>, memungkinkan Anda menyesuaikan kebijakan Kuota untuk menerapkan kuota permintaan masuk dan menghitung respons target berdasarkan kondisi yang Anda tentukan.

Misalnya, Anda ingin menambah penghitung kuota untuk proxy API dengan respons dari target backend memiliki kode status HTTP 200. Untuk mencapai penghitungan khusus ini, lakukan hal berikut:

  • Tambahkan kebijakan Kuota ke alur Permintaan ProxyEndpoint dengan elemen <SharedName> yang ditetapkan dengan nilai nama dan elemen <EnforceOnly> yang ditetapkan ke true.
  • Tambahkan kebijakan Kuota lain ke alur Respons ProxyEndpoint dengan elemen <SharedName> ditetapkan ke nilai nama yang sama dengan kebijakan pertama dan elemen <CountOnly> ditetapkan ke true.
  • Tempatkan kebijakan Kuota kedua (yang memiliki <CountOnly>) dalam langkah kondisional yang menetapkan kondisi untuk menambah penghitung kuota.

Untuk contoh yang menunjukkan cara menggunakan penghitung bersama, lihat Penghitung bersama di bagian Contoh.

Sampel

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

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

Kuota dinamis memungkinkan Anda 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.

Misalnya, saat membuat produk API, Anda dapat menetapkan batas kuota, unit waktu, dan interval yang diizinkan secara opsional. Namun, menetapkan nilai ini pada produk API tidak akan menerapkan penggunaannya di 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, bernama verify-api-key, untuk memvalidasi kunci API yang diteruskan dalam permintaan. Kebijakan kuota kemudian mengakses variabel alur dari kebijakan VerifyAPIKey untuk membaca nilai kuota yang ditetapkan pada produk API.

Opsi lainnya adalah menetapkan atribut kustom pada setiap developer atau aplikasi, lalu membaca nilai tersebut dalam kebijakan Kuota. Misalnya, untuk menetapkan nilai kuota yang berbeda per developer, Anda menetapkan atribut kustom pada developer yang berisi batas, unit waktu, dan interval. Kemudian, Anda mereferensikan 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 kustom yang ditetapkan pada developer.

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

  • Variabel alur
  • Properti di produk, aplikasi, atau developer API
  • Peta nilai kunci (KVM)
  • Header, parameter kueri, parameter formulir, dan lainnya

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>2021-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, Apigee akan menampilkan 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 2021, dan diperbarui setiap 5 jam. Oleh karena itu, pembaruan berikutnya akan dilakukan pada pukul 15.30 GMT pada 18 Februari 2021.

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 Kuota. 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 yang bernama <Quota>, Anda mengakses variabel alur 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 alur lain yang dapat Anda akses, seperti yang dijelaskan di bawah.

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

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

Penghitung bersama

Contoh berikut mengilustrasikan cara mengonfigurasi penghitung bersama untuk proxy API, dengan penghitung kuota juga bertambah saat respons target adalah status HTTP 200. Karena kedua kebijakan Kuota menggunakan nilai <SharedName> yang sama, kedua kebijakan Kuota akan berbagi penghitung kuota yang sama. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi penghitung kuota bersama.

Contoh konfigurasi ProxyEndpoint: 

<ProxyEndpoint name="default">
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>Enforce-Only</Name>  <!--First quota policy enforces quota count -->
            </Step>
        </Request>
        <Response>
            <Step>
                <Name>Count-Only</Name>   <!-- Second quota policy counts quota if call is successful -->
                <Condition>response.status.code = 200</Condition>
            </Step>
        </Response>
        <Response/>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <HTTPProxyConnection>
        <BasePath>/quota-shared-name</BasePath>
    </HTTPProxyConnection>
    <RouteRule name="noroute"/>
</ProxyEndpoint>

Contoh kebijakan kuota pertama:

<Quota continueOnError="false" enabled="true" name="Enforce-Only" type="rollingwindow">
    <DisplayName>Enforce-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <EnforceOnly>true</EnforceOnly>
    <SharedName>common-proxy</SharedName>  <!-- Notice that SharedName value is the same for both Quota policies -->
</Quota>

Contoh kebijakan Kuota kedua:

<Quota continueOnError="false" enabled="true" name="Count-Only" type="rollingwindow">
    <DisplayName>Count-Only</DisplayName>
    <Properties/>
    <Allow count="5"/>
    <Interval>2</Interval>
    <TimeUnit>minute</TimeUnit>
    <Distributed>true</Distributed>
    <Synchronous>true</Synchronous>
    <CountOnly>true</CountOnly>
    <SharedName>common-proxy</SharedName>  <!-- Same name as the first policy -->
</Quota>

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 atas 10.000 akan ditolak.

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

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

Anda dapat mereferensikan kebijakan ini di beberapa tempat di proxy API. Misalnya, Anda dapat menempatkannya di Proxy PreFlow sehingga dieksekusi pada setiap permintaan. Atau, Anda dapat menempatkannya di beberapa alur di proxy API. Jika Anda menggunakan kebijakan ini di beberapa tempat dalam 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.

Menetapkan ID

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/>
  <StartTime>2021-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 kemudian meneruskan header yang berisi clientID, seperti yang ditunjukkan pada contoh di atas.

Anda dapat menentukan variabel alur 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 kunci API atau token untuk menentukan penghitung individual untuk kebijakan Kuota yang sama. Misalnya, elemen <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 Quota.

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.

Elemen <Quota>

Berikut adalah atribut dan elemen turunan <Quota>. Perhatikan bahwa beberapa kombinasi elemen bersifat eksklusif atau tidak diperlukan. Lihat contoh untuk penggunaan tertentu.

Variabel verifyapikey.my-verify-key-policy.apiproduct.* di bawah tersedia secara default saat kebijakan VerifyAPIKey yang disebut my-verify-key-policy digunakan untuk memeriksa kunci API aplikasi dalam permintaan. Nilai variabel berasal dari setelan kuota di produk API yang terkait dengan kunci, seperti yang dijelaskan dalam artikel Mendapatkan setelan kuota dari konfigurasi produk API.

<Quota continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="UPPER_REQUEST_LIMIT" countRef="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="UPPER_LIMIT_DURING_PEAK"/>
        <Allow class="off_peak_time" count="UPPER_LIMIT_DURING_OFFPEAK"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
   <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2021-7-16 12:00:00</StartTime>
   <Distributed>false</Distributed>
   <Synchronous>false</Synchronous>
   <AsynchronousConfiguration>
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
      <SyncMessageCount>5</SyncMessageCount>
   </AsynchronousConfiguration>
   <Identifier/>
   <MessageWeight/>
   <UseQuotaConfigInAPIProduct>
     <DefaultConfig>
       <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.my-verify-key-policy.apiproduct.developer.quota.interval">1</Interval>
       <TimeUnit ref="verifyapikey.my-verify-key-policy.apiproduct.developer.quota.timeunit">month</TimeUnit>
     </DefaultConfig>
   </UseQuotaConfigInAPIProduct>
   </SharedName>
   </CountOnly>
   </EnforceOnly>
</Quota>

Atribut berikut khusus untuk kebijakan ini:

Atribut Deskripsi Default Kehadiran
jenis

Menetapkan Jenis kebijakan kuota, yang menentukan waktu dan cara penghitung kuota memeriksa penggunaan kuota serta cara meresetnya.

Jika Anda tidak menetapkan type, penghitung akan dimulai pada awal menit/jam/hari/minggu/bulan.

Nilai yang valid mencakup:

  • calendar
  • rollingwindow
  • flexi

Untuk deskripsi lengkap setiap jenis, lihat Jenis kebijakan kuota.

 T/A Opsional

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

Atribut Deskripsi Default Kehadiran
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 pada 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. Perilaku ini wajar terjadi untuk sebagian besar kebijakan.

Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga:

 false Opsional
enabled

Tetapkan ke true untuk menerapkan kebijakan.

Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.

 benar Opsional
async

Atribut ini tidak digunakan lagi.

 false Tidak digunakan lagi

Elemen <DisplayName>

Gunakan selain atribut name untuk melabeli kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

<DisplayName>Policy Display Name</DisplayName>
Default

T/A

Jika Anda menghapus elemen ini, nilai atribut name kebijakan akan digunakan.
Kehadiran Opsional
Jenis String

<Allow>

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

Juga dapat berisi elemen <Class> yang mengondisikan elemen <Allow> berdasarkan variabel flow.

Nilai Default t/a
Wajib? Opsional
Jenis Jenis Bilangan Bulat atau Kompleks
Elemen Induk <Quota>
Elemen Turunan <Class>

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, countRef akan mendapatkan prioritas. Jika countRef tidak di-resolve saat runtime, nilai count akan digunakan.

Anda juga dapat menentukan elemen <Class> sebagai turunan dari <Allow> untuk menentukan jumlah kebijakan yang diizinkan berdasarkan variabel alur. Apigee mencocokkan nilai variabel alur dengan atribut class elemen <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>

Tabel berikut mencantumkan atribut <Allow>:

Atribut Deskripsi Default Kehadiran
count

Gunakan untuk menentukan jumlah pesan untuk kuota.

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

 2000 Opsional
countRef

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

 tidak ada Opsional

<Class>

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

Nilai Default t/a
Wajib? Opsional
Jenis Jenis kompleks
Elemen Induk <Allow>
Elemen Turunan <Allow> (turunan <Class>)

Untuk menggunakan elemen <Class>, tentukan variabel flow menggunakan atribut ref ke elemen <Class>. Apigee kemudian menggunakan nilai variabel alur untuk memilih salah satu elemen turunan <Allow> guna menentukan jumlah kebijakan yang diizinkan. Apigee mencocokkan nilai variabel alur dengan atribut class elemen <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.

Tabel berikut mencantumkan atribut <Class>:

Atribut Deskripsi Default Kehadiran
ref Gunakan untuk menentukan variabel alur yang berisi class kuota untuk kuota. tidak ada Wajib

<Allow> (turunan <Class>)

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

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

Contoh:

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

Dalam contoh ini, kebijakan Kuota mempertahankan dua penghitung kuota bernama peak_time dan off_peak_time. Manakah dari opsi ini yang digunakan bergantung pada parameter kueri yang diteruskan, seperti yang ditunjukkan dalam contoh <Class>.

Tabel berikut mencantumkan atribut <Allow>:

Atribut Deskripsi Default Kehadiran
class Menentukan nama penghitung kuota. tidak ada Wajib
count Menentukan batas kuota untuk penghitung. tidak ada Wajib

<Interval>

Menentukan jumlah jangka waktu penghitungan kuota.

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

Gunakan untuk menentukan bilangan bulat (misalnya, 1, 2, 5, 60, dan seterusnya) yang akan disambungkan dengan elemen <TimeUnit> yang Anda tentukan (menit, jam, hari, minggu, atau bulan) untuk menentukan jangka waktu saat Apigee menghitung penggunaan kuota.

Misalnya, interval 24 dengan <TimeUnit> hour berarti kuota akan dihitung selama 24 jam.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>

Tabel berikut mencantumkan atribut <Interval>:

Atribut Deskripsi Default Kehadiran
ref

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

 tidak ada Opsional

<TimeUnit>

Menentukan satuan waktu yang berlaku untuk kuota.

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

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

Misalnya, Interval 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
Jenis: String

Tabel berikut mencantumkan atribut <TimeUnit>:

Atribut Deskripsi Default Kehadiran
ref Menentukan variabel alur yang berisi unit waktu untuk kuota. ref lebih diutamakan daripada nilai interval eksplisit. Jika ref tidak di-resolve saat runtime, nilai interval akan digunakan. tidak ada Opsional

<StartTime>

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

Nilai Default t/a
Wajib? Opsional (Wajib jika type ditetapkan ke calendar)
Jenis String dalam format tanggal dan waktu ISO 8601
Elemen Induk <Quota>
Elemen Turunan Tidak ada

Anda harus memberikan <StartTime> eksplisit saat type ditetapkan ke calendar; Anda tidak dapat menggunakan referensi ke variabel alur. Jika Anda menentukan nilai <StartTime> saat tidak ada nilai type yang ditetapkan, Apigee akan menampilkan error.

Contoh:

<StartTime>2021-7-16 12:00:00</StartTime>

<Distributed>

Menentukan apakah Apigee menggunakan satu atau beberapa node untuk memproses permintaan.

Nilai Default false
Wajib? Opsional
Jenis Boolean
Elemen Induk <Quota>
Elemen Turunan Tidak ada

Tetapkan ke true untuk menentukan bahwa kebijakan harus mempertahankan penghitung pusat dan terus menyinkronkannya di semua node. Node dapat berada di seluruh zona ketersediaan dan/atau region.

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

<Distributed>false</Distributed>

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

<Distributed>true</Distributed>
<Synchronous>true</Synchronous>

<Synchronous>

Menentukan apakah akan memperbarui penghitung kuota terdistribusi secara sinkron.

Nilai Default false
Wajib? Opsional
Jenis Boolean
Elemen Induk <Quota>
Elemen Turunan Tidak ada

Tetapkan ke true untuk memperbarui penghitung kuota terdistribusi secara sinkron. Hal ini berarti bahwa pembaruan penghitung dilakukan bersamaan dengan pemeriksaan kuota pada permintaan ke API. Tetapkan ke true jika Anda tidak boleh mengizinkan panggilan API melebihi kuota.

Tetapkan ke false untuk memperbarui penghitung kuota secara asinkron. Artinya, beberapa panggilan API yang melebihi kuota mungkin akan berhasil, bergantung pada waktu penghitung kuota di repositori pusat diperbarui 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>

<AsynchronousConfiguration>

Mengonfigurasi interval sinkronisasi di antara penghitung kuota terdistribusi saat elemen konfigurasi kebijakan <Synchronous> tidak ada atau ada dan ditetapkan ke false. Apigee mengabaikan elemen ini jika <Synchronous> ditetapkan ke true.

Nilai Default t/a
Wajib? Opsional
Jenis Jenis kompleks
Elemen Induk <Quota>
Elemen Turunan <SyncIntervalInSeconds>
<SyncMessageCount>

Anda dapat menentukan perilaku sinkronisasi menggunakan elemen turunan <SyncIntervalInSeconds> atau <SyncMessageCount>. Gunakan salah satu atau kedua elemen. Misalnya,

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

atau

<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
   <SyncMessageCount>5</SyncMessageCount>
</AsynchronousConfiguration>
  • Jika hanya <SyncIntervalInSeconds> yang ada, kuota akan disinkronkan setiap N detik, dengan N adalah nilai yang ditentukan dalam elemen, terlepas dari jumlah pesan yang telah ditangani.
  • Jika hanya <SyncMessageCount> yang ada, kuota akan menyinkronkan setiap pesan M, dengan M adalah nilai yang ditentukan dalam elemen, atau setiap 10 detik, mana saja yang lebih dulu tercapai.
  • Jika kedua elemen tersebut ada, kuota akan menyinkronkan setiap M pesan atau setiap N detik, mana saja yang lebih dulu tercapai.
  • Jika <AsynchronousConfiguration> tidak ada atau tidak ada elemen turunan, kuota akan disinkronkan setiap 10 detik, terlepas dari jumlah pesan yang telah ditangani.

<SyncIntervalInSeconds>

Mengganti perilaku default saat update asinkron dilakukan setelah interval 10 detik.

Nilai Default 10 detik
Wajib? Opsional
Jenis Bilangan bulat
Elemen Induk <AsynchronousConfiguration>
Elemen Turunan Tidak ada
 
<AsynchronousConfiguration>
   <SyncIntervalInSeconds>20</SyncIntervalInSeconds>
</AsynchronousConfiguration>

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

<SyncMessageCount>

Menentukan jumlah permintaan yang akan diproses sebelum menyinkronkan penghitung kuota.

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

Dengan menggunakan konfigurasi dalam contoh ini, di setiap node, jumlah kuota akan disinkronkan setelah setiap 5 permintaan, atau setiap 10 detik, mana saja yang lebih dulu.

<Identifier>

Mengonfigurasi kebijakan untuk membuat penghitung unik berdasarkan variabel alur.

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

Melalui elemen ID, Anda dapat mengalokasikan jumlah panggilan ke bucket berbeda yang ditentukan oleh nilai dalam variabel alur. Misalnya, Anda dapat menggunakan variabel developer.id, yang diisi setelah kebijakan VerifyAPIKey, untuk menerapkan satu batas kuota ke semua instance dari semua aplikasi yang dibuat oleh setiap developer tertentu, atau Anda dapat menggunakan client_id untuk menerapkan batas kuota untuk setiap aplikasi tertentu. Konfigurasi untuk yang terakhir terlihat seperti ini:

<Identifier ref="client_id"/>

Anda dapat merujuk ke variabel kustom yang mungkin ditetapkan dengan kebijakan AssignMessage atau kebijakan JavaScript, atau variabel yang ditetapkan secara implisit, seperti yang ditetapkan oleh kebijakan VerifyAPIKey atau kebijakan VerifyJWT. Untuk mengetahui informasi selengkapnya tentang variabel, lihat Menggunakan Variabel Flow, dan untuk mengetahui daftar variabel umum yang ditentukan oleh Apigee, lihat Referensi variabel flow.

Jika Anda tidak menggunakan elemen ini, kebijakan akan mengalokasikan semua jumlah panggilan ke dalam satu penghitung untuk kebijakan Kuota tertentu.

Elemen ini juga dibahas dalam artikel Bagaimana cara kerja kebijakan Kuota jika tidak ada ID yang ditentukan?

Tabel berikut menjelaskan atribut <Identifier>:

Atribut Deskripsi Default Kehadiran
ref

Menentukan variabel alur yang mengidentifikasi penghitung yang akan digunakan untuk permintaan. Variabel ini dapat merujuk ke header HTTP, parameter kueri, parameter formulir, atau elemen konten pesan, atau beberapa nilai lain untuk mengidentifikasi cara mengalokasikan jumlah panggilan.

client_id biasanya digunakan sebagai variabel. client_id juga dikenal sebagai kunci API atau kunci konsumen, dan dibuat untuk aplikasi saat didaftarkan di organisasi di Apigee. Anda dapat menggunakan ID ini jika telah mengaktifkan kebijakan otorisasi OAuth atau kunci API untuk API Anda.

 T/A Opsional

<MessageWeight>

Menentukan biaya yang ditetapkan untuk setiap pesan untuk tujuan kuota. Gunakan elemen ini untuk meningkatkan dampak pesan permintaan yang, misalnya, menggunakan lebih banyak resource komputasi daripada yang lain.

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

Misalnya, Anda ingin menghitung pesan POST sebagai dua kali lebih mahal dibandingkan 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 kuotanya adalah 10 pesan per menit dan <MessageWeight> untuk permintaan POST adalah 2, kuota akan mengizinkan 5 permintaan POST dalam interval 10 menit. Setiap permintaan tambahan, POST atau GET, sebelum reset penghitung 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 alur lainnya. Misalnya, Anda menetapkannya di header bernama weight:

<MessageWeight ref="message_weight"/>

<UseQuotaConfigInAPIProduct>

Menentukan setelan kuota untuk produk API, seperti unit waktu, interval, dan maksimum yang diizinkan.

Nilai Default t/a
Wajib? Opsional
Jenis Jenis kompleks
Elemen Induk <Quota>
Elemen Turunan <DefaultConfig>

Jika Anda menambahkan elemen <UseQuotaConfigInAPIProduct> ke kebijakan Kuota, Apigee akan mengabaikan elemen turunan <Allow>, <Interval>, dan <TimeUnit> dari <Quota>.

Elemen <UseQuotaConfigInAPIProduct> hanyalah penampung untuk setelan default yang Anda tentukan menggunakan elemen <DefaultConfig>, seperti yang ditunjukkan dalam contoh berikut:

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>...</DefaultConfig>
</UseQuotaConfigInAPIProduct>

Anda dapat menggunakan atribut stepName untuk mereferensikan kebijakan VerifyAPIKey atau operasi kebijakan ValidateToken dari kebijakan OAuthv2 dalam alur.

Tabel berikut menjelaskan atribut <UseQuotaConfigInAPIProduct>:

Atribut Deskripsi Default Kehadiran
stepName Mengidentifikasi nama kebijakan autentikasi dalam alur. Targetnya dapat berupa kebijakan VerifyAPIKey atau kebijakan OAuthv2. T/A Wajib

Untuk informasi selengkapnya, lihat referensi berikut:

<DefaultConfig>

Berisi nilai default untuk kuota produk API. Saat Anda menentukan <DefaultConfig>, ketiga elemen turunan diperlukan.

Nilai Default t/a
Wajib? Opsional
Jenis Jenis kompleks
Elemen Induk <UseQuotaConfigInAPIProduct>
Elemen Turunan <Allow>
<Interval>
<TimeUnit>

Anda dapat menentukan nilai ini pada operasi produk API (baik dengan UI maupun API produk API dan dalam kebijakan Kuota. Namun, jika Anda melakukannya, setelan pada produk API akan diprioritaskan dan setelan pada kebijakan Kuota akan diabaikan.

Sintaksis untuk elemen ini adalah sebagai berikut:

<UseQuotaConfigInAPIProduct stepName="POLICY_NAME">
  <DefaultConfig>
    <Allow>allow_count</Allow>
    <Interval>interval</Interval>
    <TimeUnit>[minute|hour|day|week|month]</TimeUnit>
  </DefaultConfig>
</UseQuotaConfigInAPIProduct>

Contoh berikut menentukan kuota 10.000 setiap minggu:

<DefaultConfig>
  <Allow>10000</Allow>
  <Interval>1</Interval>
  <TimeUnit>week</TimeUnit>
</DefaultConfig>

Untuk informasi selengkapnya, lihat referensi berikut:

<SharedName>

Mengidentifikasi kebijakan Kuota ini sebagai dibagikan. Semua kebijakan Kuota di proxy API dengan nilai <SharedName> yang sama memiliki penghitung kuota dasar yang sama. Jika elemen ini ada, elemen <EnforceOnly> atau <CountOnly> juga harus ada.

Untuk informasi dan contoh selengkapnya, lihat Mengonfigurasi penghitung kuota bersama.

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

<CountOnly>

Tempatkan kebijakan Kuota dengan elemen ini ditetapkan ke true dalam langkah kondisional di alur respons ProxyEndpoint untuk secara kondisional menambah penghitung kuota yang mendasarinya. Jika elemen ini ada, elemen <SharedName> dan <EnforceOnly> juga harus ada.

Untuk informasi dan contoh selengkapnya, lihat Mengonfigurasi penghitung kuota bersama.

Nilai Default false
Wajib? Opsional
Jenis Boolean
Elemen Induk <Quota>
Elemen Turunan Tidak ada

<EnforceOnly>

Tempatkan kebijakan Kuota dengan elemen ini ditetapkan ke true dalam alur permintaan proxy API. Konfigurasi ini memungkinkan jumlah kuota dibagikan untuk kebijakan Kuota di proxy API dengan nilai <SharedName> yang sama. Jika elemen ini ada, elemen <SharedName> dan <CountOnly> juga harus ada.

Untuk informasi dan contoh selengkapnya, lihat Mengonfigurasi penghitung kuota bersama.

Nilai Default false
Wajib? Opsional
Jenis Boolean
Elemen Induk <Quota>
Elemen Turunan Tidak ada

Variabel alur

Variabel Flow bawaan berikut diisi secara otomatis saat kebijakan Kuota dijalankan. Untuk informasi selengkapnya, lihat Referensi variabel alur.

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

Menampilkan waktu UTC (dalam milidetik), yang menentukan kapan kuota berakhir dan kapan interval kuota baru dimulai.

Jika jenis kebijakan Kuota adalah rollingwindow, nilai ini tidak valid karena interval kuota tidak pernah berakhir.
ratelimit.{policy_name}.identifier String Hanya Baca Menampilkan referensi ID (klien) yang dilampirkan ke kebijakan
ratelimit.{policy_name}.class String Hanya Baca Menampilkan class yang terkait dengan client ID
ratelimit.{policy_name}.class.allowed.count Long Hanya Baca Menampilkan jumlah kuota yang diizinkan yang ditentukan dalam class
ratelimit.{policy_name}.class.used.count Long Hanya Baca Menampilkan kuota yang digunakan dalam class
ratelimit.{policy_name}.class.available.count Long Hanya Baca Menampilkan jumlah kuota yang tersedia di class
ratelimit.{policy_name}.class.exceed.count Long Hanya Baca Menampilkan jumlah permintaan yang melebihi batas di class dalam interval kuota saat ini
ratelimit.{policy_name}.class.total.exceed.count Long Hanya Baca Menampilkan jumlah total permintaan yang melebihi batas di class di 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 (benar atau salah).

Referensi error

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

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kerusakan Status HTTP Penyebab Perbaiki
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Terjadi jika elemen <Interval> tidak ditentukan dalam kebijakan Quota. Elemen ini wajib diisi 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 Quota. Elemen ini 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 alur 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 di elemen <Interval>, 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, deployment proxy API akan gagal.
StartTimeNotSupported Jika elemen <StartTime> ditentukan dengan jenis kuota yang 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 di elemen <Quota>, deployment proxy API akan gagal.
InvalidTimeUnitForDistributedQuota Jika elemen <Distributed> ditetapkan ke true dan elemen <TimeUnit> ditetapkan ke second, deployment proxy API akan gagal. Timeunit second tidak valid untuk kuota yang didistribusikan.
InvalidSynchronizeIntervalForAsyncConfiguration Jika nilai yang ditentukan untuk elemen <SyncIntervalInSeconds> dalam elemen <AsynchronousConfiguration> dalam kebijakan Quota kurang dari nol, deployment proxy API akan gagal.
InvalidAsynchronizeConfigurationForSynchronousQuota Jika nilai elemen <AsynchronousConfiguration> ditetapkan ke true dalam kebijakan Quota, yang juga memiliki konfigurasi asinkron yang ditentukan menggunakan elemen <AsynchronousConfiguration>, deployment proxy API akan gagal.

Variabel error

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

Variabel Dari mana Contoh
fault.name="fault_name" fault_name adalah nama error, seperti yang tercantum dalam tabel Runtime errors di atas. Nama error adalah bagian terakhir dari kode error. fault.name Matches "QuotaViolation"
ratelimit.policy_name.failed policy_name adalah nama kebijakan yang ditentukan pengguna yang menampilkan error. 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 error

<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 dan Penghentian Lonjakan