Kebijakan kuota

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca 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 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 merupakan Kebijakan yang dapat diperluas, dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau pemanfaatan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.

Misalnya, jika Kuota ditetapkan sebagai 10.000 pesan per bulan, pembatasan kapasitas akan dimulai setelah pesan ke-10.000. Tidak masalah apakah 10.000 pesan telah dihitung pada hari pertama atau hari terakhir periode tersebut; tidak ada permintaan tambahan yang diizinkan hingga penghitung Kuota 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 (atau burst) traffic yang dapat disebabkan oleh peningkatan penggunaan yang tiba-tiba, klien yang memiliki bug, atau serangan berbahaya.

Gunakan kebijakan Kuota untuk mengonfigurasi jumlah pesan permintaan yang diizinkan oleh proxy API selama jangka waktu tertentu, seperti satu 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 lain

Jangan gunakan kebijakan Kuota untuk melindungi dari lonjakan traffic secara keseluruhan. Untuk itu, gunakan kebijakan SpikeArrest.

Video

Video berikut memperkenalkan pengelolaan kuota dengan kebijakan Kuota:

Pengantar

Kuota Dinamis

Terdistribusi & Sinkron

Berat Pesan

Kalender

Jendela Beroda

Fleksibel

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

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 Bagian atas satu jam berikutnya Satu jam setelah <StartTime> Satu jam setelah permintaan pertama
hari GMT tengah malam hari ini 24 jam setelah <StartTime> 24 jam setelah permintaan pertama
minggu Minggu tengah malam GMT di akhir minggu Satu minggu setelah <StartTime> Satu minggu setelah permintaan pertama
bulan GMT tengah malam pada hari terakhir bulan ini Satu bulan (28 hari) setelah <StartTime> Satu bulan (28 hari) setelah permintaan pertama

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

Tabel tidak mencantumkan nilai untuk jenis rollingwindow. Kuota periode berjalan 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 terakhir.

Misalnya, Anda menentukan periode dua jam yang memungkinkan 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 jangka waktu dua jam tersebut, permintaan akan diizinkan.

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

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

Memahami penghitung kuota

Saat kebijakan kuota dijalankan di alur proxy API, penghitung kuota akan dikurangi. Saat penghitung mencapai batasnya, panggilan API yang terkait dengan penghitung tersebut tidak diizinkan. Bergantung pada konfigurasi Anda, kebijakan kuota dapat menggunakan satu atau beberapa penghitung. Penting untuk memahami kapan beberapa penghitung digunakan dan bagaimana perilakunya.

Cara penghitungan kuota untuk produk API

Jika proxy API disertakan dalam produk API, Anda dapat mengonfigurasi kebijakan kuota untuk menggunakan aturan kuota yang ditetapkan dalam produk tersebut. Produk API dapat menentukan aturan kuota pada tingkat produk atau pada tingkat operations individual.

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

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

Bagian berikut menjelaskan opsi dan perilaku penghitung secara lebih mendetail.

Mengonfigurasi penghitung tingkat proxy API

Produk API dapat dikonfigurasi untuk mempertahankan jumlah kuota pada cakupan proxy API. Dalam hal ini, konfigurasi kuota yang ditentukan pada level produk API digunakan bersama oleh semua operasi yang tidak memiliki kuotanya sendiri yang ditetapkan. Efek dari konfigurasi ini adalah membuat penghitung global pada level proxy API untuk produk API ini.

Untuk mencapai konfigurasi ini, Anda harus menggunakan /apiproducts Apigee API untuk membuat atau memperbarui produk dan menetapkan atribut quotaCountScope ke PROXY dalam permintaan buat atau perbarui. Dengan konfigurasi PROXY, semua operasi yang ditetapkan untuk produk API yang terkait dengan proxy yang sama, dan tidak memiliki penghitung sendiri, akan berbagi penghitung kuota yang sama dengan yang ditetapkan pada level produk API.

Pada Gambar 1, Operasi 1 dan 2 terkait dengan Proxy1, sedangkan Operasi 4 dan 5 berhubungan dengan Proxy3. Karena quotaCounterScope=PROXY ditetapkan dalam produk API, setiap operasi ini menggunakan setelan kuota API tingkat produk yang sama. Perlu diperhatikan bahwa meskipun operasi ini berbagi konfigurasi kuota yang sama, operasi tersebut menggunakan penghitung terpisah, berdasarkan asosiasi proxy-nya. Di sisi lain, Operasi 3 memiliki konfigurasi kuota yang telah ditetapkan sendiri, sehingga tidak terpengaruh oleh flag quotaCounterScope.

Gambar 1: Penggunaan flag quotaCounterScope

Secara default, jika suatu operasi tidak memiliki kuota yang ditentukan untuk operasi tersebut, aturan kuota tingkat produk akan diterapkan; namun, penghitung kuota terpisah tetap dipertahankan untuk operasi tersebut.

Cara kuota dihitung 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 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 di beberapa alur, metode ini mempertahankan satu penghitung yang diupdate oleh semua instance kebijakan:

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

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

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

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 mengajukan permintaan, developer aplikasi yang membuat permintaan, client ID atau ID klien lainnya, dan lainnya. Lihat contoh di atas untuk mengetahui 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 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 merepresentasikan 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 adalah tanggal dan waktu yang sama dengan 2021-02-05 00:00:00. Yang kedua biasanya adalah notasi yang disukai.

Mendapatkan setelan kuota dari konfigurasi produk API

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

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

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

Untuk informasi 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 mungkin ingin memberlakukan jumlah kuota permintaan yang masuk, sekaligus menambah jumlah kuota untuk respons target yang memenuhi kondisi tertentu. Tiga elemen kebijakan Kuota jika digunakan bersama-sama, yaitu <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 menambahkan 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> yang ditetapkan ke nilai nama yang sama dengan kebijakan pertama dan elemen <CountOnly> yang ditetapkan ke true.
  • Tempatkan kebijakan Kuota kedua (yang satu dengan <CountOnly>) pada langkah bersyarat yang menetapkan kondisi untuk meningkatkan 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 Dinamis Lebih Banyak

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

Kuota dinamis memungkinkan Anda mengonfigurasi satu kebijakan Kuota yang menerapkan setelan kuota 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 secara opsional menetapkan batas kuota, satuan waktu, dan interval yang diizinkan. Namun, menetapkan nilai ini pada produk API tidak akan menerapkan penggunaannya dalam proxy API. Anda juga harus menambahkan kebijakan Kuota ke proxy API yang membaca nilai ini. Lihat Membuat produk API untuk informasi selengkapnya.

Dalam contoh di atas, proxy API yang berisi kebijakan Kuota menggunakan kebijakan VerifyAPIKey, bernama verify-api-key, untuk memvalidasi kunci API yang diteruskan dalam permintaan. Kemudian, kebijakan Kuota akan mengakses variabel flow dari kebijakan VerifyAPIKey untuk membaca nilai kuota yang ditetapkan pada produk API.

Opsi lainnya adalah menetapkan atribut khusus pada masing-masing developer atau aplikasi, lalu membaca nilai tersebut pada kebijakan Kuota. Misalnya, untuk menetapkan nilai kuota yang berbeda untuk setiap developer, Anda menetapkan atribut khusus pada developer yang berisi batas, unit waktu, dan interval. Selanjutnya, Anda merujuk nilai-nilai ini dalam kebijakan Kuota seperti yang ditunjukkan di bawah ini:

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

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

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

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

Untuk setiap proxy API, Anda dapat menambahkan kebijakan Kuota yang mereferensikan variabel yang sama seperti 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 berjenis calendar, Apigee akan menghasilkan error.

Penghitung Kuota untuk setiap aplikasi diperbarui berdasarkan nilai <StartTime>, <Interval>, dan <TimeUnit>. Untuk contoh ini, Kuota mulai dihitung pukul 10.30 GMT pada 18 Februari 2021, dan diperbarui setiap 5 jam. Oleh karena itu, refresh berikutnya 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 karena alasan lainnya.

Karena akses variabel alur untuk kebijakan didasarkan pada atribut name kebijakan, untuk kebijakan di atas bernama <Quota>, 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 alur lainnya yang dapat Anda akses, seperti yang dijelaskan di bawah ini.

Misalnya, Anda dapat menggunakan kebijakanAssignMessage berikut untuk menampilkan nilai variabel Quota flow 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, saat penghitung kuota juga bertambah saat respons target adalah status HTTP 200. Karena kedua kebijakan Kuota menggunakan nilai <SharedName> yang sama, kedua kebijakan Kuota akan menggunakan penghitung kuota yang sama. Untuk 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 jam. Kebijakan ini akan mereset penghitung kuota di bagian atas setiap jam. Jika penghitung mencapai kuota 10.000 panggilan sebelum akhir jam, panggilan yang melebihi 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 sampai hitungan tersebut direset di bagian atas jam tersebut.

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 merujuk kebijakan ini di beberapa tempat dalam proxy API Anda. Misalnya, Anda dapat menempatkannya di PraFlow Proxy sehingga akan dijalankan pada setiap permintaan. Atau, Anda dapat menempatkannya di beberapa alur 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.

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 mengelola 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 akan meneruskan header yang berisi clientID, seperti yang ditunjukkan dalam contoh di atas.

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

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

Jika Anda menggunakan kebijakan VerifyAPIKey untuk memvalidasi kunci API, atau kebijakan OAuthV2 dengan token OAuth, Anda dapat menggunakan informasi dalam token atau kunci API untuk menentukan penghitung 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 Kuota.

Class

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

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

Elemen <Quota>

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

Variabel verifyapikey.my-verify-key-policy.apiproduct.* di bawah ini 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 pada produk API yang dikaitkan dengan kunci tersebut, seperti yang dijelaskan dalam 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 Quota policy type, yang menentukan waktu dan cara penghitung kuota memeriksa penggunaan kuota serta cara reset.

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

Nilai yang valid meliputi:

  • calendar
  • rollingwindow
  • flexi

Untuk deskripsi lengkap tentang setiap jenis, lihat Jenis kebijakan kuota.

 T/A Opsional

Tabel berikut menjelaskan atribut yang sama 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.

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

 T/A Diperlukan
continueOnError

Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal. Lihat juga:

 false Opsional
enabled

Setel ke true untuk menerapkan kebijakan.

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

 true Opsional
async

Atribut ini sudah tidak digunakan lagi.

 false Tidak digunakan lagi

Elemen <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
Default

T/A

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

<Allow>

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

Dapat juga berisi elemen <Class> yang mengondisikan elemen <Allow> berdasarkan variabel flow.

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

Di bawah ini adalah tiga cara untuk menyetel 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 flow. Apigee mencocokkan nilai variabel flow dengan atribut class elemen <Allow>, seperti ditunjukkan di bawah ini:

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

Tabel berikut mencantumkan atribut <Allow>:

Atribut Deskripsi Default Kehadiran
count

Gunakan untuk menentukan jumlah pesan untuk kuota.

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

 2.000 Opsional
countRef

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

 tidak ada Opsional

<Class>

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

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

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

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

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

Tabel berikut mencantumkan atribut <Class>:

Atribut Deskripsi Default Kehadiran
referensi Gunakan untuk menentukan variabel flow yang berisi class kuota untuk kuota. tidak ada Diperlukan

<Allow> (turunan dari <Class>)

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

Nilai Default t/a
Wajib? Opsional
Type 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 berikut yang akan 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 Diperlukan
count Menentukan batas kuota untuk penghitung. tidak ada Diperlukan

<Interval>

Menentukan jumlah jangka waktu penghitungan kuota.

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

Gunakan untuk menentukan bilangan bulat (misalnya, 1, 2, 5, 60, dan seterusnya) yang akan dipasangkan dengan elemen <TimeUnit> yang Anda tentukan (menit, jam, hari, minggu, atau bulan) untuk menentukan jangka waktu selama 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
referensi

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

 tidak ada Opsional

<TimeUnit>

Menentukan satuan waktu yang berlaku pada kuota.

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

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

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

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

Tabel berikut mencantumkan atribut <TimeUnit>:

Atribut Deskripsi Default Kehadiran
referensi Menentukan variabel alur yang berisi satuan waktu untuk kuota. ref lebih diprioritaskan 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 dihitung, terlepas dari apakah ada permintaan yang telah diterima dari aplikasi apa pun.

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

Anda harus menyediakan <StartTime> eksplisit jika type ditetapkan ke calendar; Anda tidak dapat menggunakan referensi ke variabel flow. Jika Anda menentukan nilai <StartTime> ketika 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
Type Boolean
Elemen Induk <Quota>
Elemen Turunan Tidak ada

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

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

<Distributed>false</Distributed>

Untuk menjamin bahwa 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
Type Boolean
Elemen Induk <Quota>
Elemen Turunan Tidak ada

Tetapkan ke true untuk memperbarui penghitung kuota terdistribusi secara sinkron. Artinya, update pada penghitung dilakukan bersamaan dengan pemeriksaan kuota berdasarkan permintaan ke API. Tetapkan ke true jika Anda tidak mengizinkan panggilan API apa pun melebihi kuota.

Tetapkan ke false untuk memperbarui penghitung kuota secara asinkron. Artinya, ada kemungkinan bahwa beberapa panggilan API yang melebihi kuota akan berhasil, bergantung pada kapan 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 disetel ke false. Apigee mengabaikan elemen ini jika <Synchronous> ditetapkan ke true.

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

Anda dapat menyinkronkan setelah jangka waktu tertentu atau jumlah pesan, menggunakan elemen turunan <SyncIntervalInSeconds> atau <SyncMessageCount>. Kedua fitur tersebut bersifat eksklusif satu sama lain. Misalnya,

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

atau

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

<SyncIntervalInSeconds>

Mengganti perilaku default yang mana update asinkron dilakukan setelah interval 10 detik.

Nilai Default 10 detik
Wajib? Opsional
Type 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 di semua node di antara update kuota.

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

Contoh ini menetapkan bahwa jumlah kuota diperbarui setiap 5 permintaan di setiap node.

<Identifier>

Mengonfigurasi kebijakan untuk membuat penghitung unik berdasarkan variabel alur.

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

Melalui elemen ID, Anda dapat mengalokasikan jumlah panggilan ke bucket berbeda yang ditentukan berdasarkan nilai dalam variabel alur. Misalnya, Anda dapat menggunakan variabel developer.id, yang diisi setelah kebijakan VerifyAPIKey, untuk menerapkan satu batas kuota untuk 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 aplikasi yang terakhir terlihat seperti ini:

<Identifier ref="client_id"/>

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

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

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

Tabel berikut menjelaskan atribut <Identifier>:

Atribut Deskripsi Default Kehadiran
referensi

Menentukan variabel alur yang mengidentifikasi penghitung yang akan digunakan untuk permintaan. Variabel ini dapat merujuk pada 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 dalam organisasi di Apigee. Anda dapat menggunakan ID ini jika telah mengaktifkan kunci API atau kebijakan otorisasi OAuth untuk API.

 T/A Opsional

<MessageWeight>

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

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

Misalnya, Anda ingin menghitung pesan POST dua kali lebih mahal dari pesan GET. Oleh karena itu, tetapkan <MessageWeight> ke 2 untuk POST dan 1 untuk GET. Anda bahkan dapat menetapkan <MessageWeight> ke 0 sehingga permintaan tidak memengaruhi penghitung.

Dalam contoh ini, jika kuotanya adalah 10 pesan per menit dan <MessageWeight> untuk permintaan POST adalah 2, kuota akan mengizinkan 5 permintaan POST dalam setiap interval 10 menit. Semua 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 dalam header bernama weight:

<MessageWeight ref="message_weight"/>

<UseQuotaConfigInAPIProduct>

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

Nilai Default t/a
Wajib? Opsional
Type 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 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 Diperlukan

Untuk informasi selengkapnya, lihat referensi berikut:

<DefaultConfig>

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

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

Nilai ini dapat ditentukan pada operasi produk API (baik dengan UI atau 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 bersama. Semua kebijakan Kuota di proxy API dengan nilai <SharedName> yang sama memiliki penghitung kuota pokok yang sama. Jika elemen ini ada, elemen <EnforceOnly> atau <CountOnly> juga harus ada.

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

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

<CountOnly>

Tempatkan kebijakan Quota dengan elemen ini yang disetel ke true pada langkah kondisional dalam alur respons ProxyEndpoint untuk meningkatkan penghitung kuota dasar secara bersyarat. Jika elemen ini ada, elemen <SharedName> dan <EnforceOnly> juga harus ada.

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

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

<EnforceOnly>

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

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

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

Variabel alur

Variabel Alur standar berikut diisi secara otomatis saat kebijakan Kuota dieksekusi. Untuk informasi selengkapnya, lihat Referensi variabel flow.

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 pada kebijakan
ratelimit.{policy_name}.class String Hanya-Baca Menampilkan class yang terkait dengan ID klien
ratelimit.{policy_name}.class.allowed.count Long Hanya-Baca Menampilkan jumlah kuota yang diizinkan yang ditentukan di class
ratelimit.{policy_name}.class.used.count Long Hanya-Baca Menampilkan kuota yang digunakan dalam sebuah 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 pada semua interval kuota, sehingga merupakan jumlah class.exceed.count untuk semua interval kuota.
ratelimit.{policy_name}.failed Boolean Hanya-Baca

Menunjukkan apakah kebijakan gagal (true atau false).

Referensi error

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

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kesalahan Status HTTP Penyebab Perbaikan
policies.ratelimit.FailedToResolveQuotaIntervalReference 500 Terjadi jika elemen <Interval> tidak ditentukan dalam kebijakan Quota. Elemen ini bersifat wajib dan digunakan untuk menentukan interval waktu yang berlaku untuk kuota. Interval waktu dapat berupa menit, jam, hari, minggu, atau bulan seperti yang ditentukan dengan elemen <TimeUnit>.
policies.ratelimit.FailedToResolveQuotaIntervalTimeUnitReference 500 Terjadi jika elemen <TimeUnit> tidak ditentukan dalam kebijakan Quota. Elemen ini bersifat wajib dan digunakan untuk menentukan satuan waktu yang berlaku untuk kuota. Interval waktunya dapat dalam menit, jam, hari, minggu, atau bulan.
policies.ratelimit.InvalidMessageWeight 500 Terjadi jika nilai elemen <MessageWeight> yang ditentukan melalui variabel flow tidak valid (nilai non-bilangan bulat).
policies.ratelimit.QuotaViolation 500 Batas kuota terlampaui. T/A

Error saat deployment

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

Variabel kesalahan

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

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

Contoh respons error

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

Contoh aturan kesalahan

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

Skema

Topik terkait

Kebijakan ResetQuota

Kebijakan SpikeArrest

Membandingkan kebijakan Kuota dan Penangkapan Lonjakan