Kebijakan kuota

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Ringkasan

Kuota adalah alokasi permintaan yang akan diterima 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.

Saat proxy API mencapai batas kuotanya, Apigee menolak panggilan API berikutnya dan menampilkan pesan error hingga penghitung Kuota otomatis direset di akhir interval waktu yang ditentukan, atau hingga Kuota direset secara eksplisit menggunakan kebijakan ResetQuota.

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 bulan tersebut.

Dengan Apigee, setiap panggilan API dapat diberi bobot secara dinamis. Misalnya, dengan Large Language Model (LLM) API, Anda dapat menerapkan batas kapasitas berdasarkan jumlah token dalam permintaan atau respons, atau keduanya. Selain itu, batas kuota itu sendiri dapat bersifat dinamis, yang berarti Anda dapat menerapkan kuota yang lebih ketat saat sistem lebih sibuk, atau melonggarkan kuota selama jam non-puncak.

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.

Anda dapat menetapkan kuota yang sama untuk semua aplikasi yang mengakses proxy API, atau Anda dapat menetapkan batas kuota yang berbeda, bergantung pada:

• Produk yang berisi proxy API
• Aplikasi yang meminta API
• Developer aplikasi
• Layanan upstream
• Banyak kriteria lainnya
• Kombinasi dari kriteria yang tersedia

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:

Jenis kebijakan kuota

Kebijakan Kuota mendukung beberapa cara yang 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 kapan kuota direset untuk setiap jenis:

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

Tabel tidak menjelaskan kapan penghitungan direset untuk jenis rollingwindow. Hal ini karena kuota periode bergulir berfungsi sedikit berbeda, berdasarkan periode lihat balik, seperti satu jam atau satu hari. Untuk jenis rollingwindow, penghitung tidak pernah direset, tetapi dihitung ulang pada setiap permintaan. Saat permintaan baru masuk, kebijakan akan menentukan apakah kuota telah terlampaui dalam jangka 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.

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

Dalam kasus sederhana, kebijakan Kuota akan menambahkan penghitungnya sekali untuk setiap permintaan yang dikirim ke proxy API, selama pemrosesan permintaan awal. Dalam beberapa kasus, Anda mungkin ingin memeriksa apakah kuota terlampaui pada penanganan awal permintaan yang masuk, tetapi hanya menambahkan penghitung selama penanganan respons. Hal ini masuk akal jika biaya atau bobot panggilan API hanya dapat diketahui setelah sistem upstream atau target merespons. Dalam kasus LLM API, ukuran respons dalam token dapat menentukan biaya. Dalam kasus BigQuery API, total_slot_ms dalam respons dapat menentukan biaya.

Tiga elemen Kebijakan kuota—<SharedName>, <CountOnly>, dan <EnforceOnly>—jika digunakan bersama, memungkinkan Anda menyesuaikan Kebijakan kuota untuk menerapkan kuota pada permintaan yang masuk, dan mengakumulasi jumlah terhadap kuota berdasarkan informasi yang berasal dari respons target.

Misalnya, Anda memiliki proxy API yang menggunakan LLM sebagai target, dan ingin menerapkan kuota 100.000 token per jam. Respons LLM memberikan nilai totalTokenCount. Untuk melakukannya, lakukan hal berikut:

• Lampirkan kebijakan Kuota ke alur Permintaan ProxyEndpoint dengan elemen <SharedName> yang ditetapkan dengan nilai nama dan elemen <EnforceOnly> yang ditetapkan ke true.
• Ke alur Respons ProxyEndpoint, lampirkan kebijakan ExtractVariables untuk mengekstrak nilai totalTokenCount dari respons yang diterima dari target LLM.
• Lampirkan kebijakan Kuota kedua ke alur Respons ProxyEndpoint dengan elemen <SharedName> yang ditetapkan ke nilai nama yang sama dengan kebijakan Kuota pertama dan elemen <CountOnly> yang ditetapkan ke true. Tetapkan elemen <MessageWeight> untuk menggunakan nilai totalTokenCount yang diekstrak.

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:

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

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

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

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

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

<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>Quota-Enforce-Only</Name>
      </Step>
    </Request>
    <Response>
      <Step>
        <Name>EV-Token-Count</Name>
      </Step>
      <Step>
        <Name>Quota-Count-Only</Name>
      </Step>
    </Response>
    <Response/>
  </PreFlow>
  <Flows/>
  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
  <HTTPProxyConnection>
    <BasePath>/quota-shared-name</BasePath>
  </HTTPProxyConnection>
  <RouteRule name="noroute"/>
</ProxyEndpoint>

<Quota name="Quota-Enforce-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>
  <EnforceOnly>true</EnforceOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
</Quota>

<ExtractVariables name='EV-Token-Count'>
  <Source>response</Source>
  <VariablePrefix>extracted</VariablePrefix>
  <JSONPayload>
    <Variable name='tokenCount'>
      <JSONPath>$[1].usageMetadata.totalTokenCount</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

<Quota name="Quota-Count-Only" type="rollingwindow">
  <SharedName>common-counter</SharedName>  <!-- Same name as the first Quota policy -->
  <CountOnly>true</CountOnly>
  <Allow count="15000"/>
  <Interval>30</Interval>
  <TimeUnit>minute</TimeUnit>
  <Distributed>true</Distributed>
  <MessageWeight ref="extracted.tokenCount"/>
</Quota>

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

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

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

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

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

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

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

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>

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

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 flow. 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>:

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

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

<Allow> (turunan <Class>)

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

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

<Interval>

Menentukan jumlah jangka waktu penghitungan kuota.

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

<TimeUnit>

Menentukan satuan waktu yang berlaku untuk kuota.

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>

Tabel berikut mencantumkan atribut <TimeUnit>:

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

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.

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.

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.

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.

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

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

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 Bagaimana cara kerja kebijakan Kuota jika tidak ada ID yang ditentukan?

Tabel berikut menjelaskan atribut <Identifier>:

<MessageWeight>

Menentukan biaya yang ditetapkan untuk setiap pesan untuk tujuan kuota. Gunakan elemen ini untuk menetapkan dampak yang berbeda pada permintaan API berdasarkan konten atau nilai panggilannya.

Misalnya, saat Apigee mengelola Large Language Model (LLM) API, Anda dapat menggunakan jumlah token dalam permintaan atau respons, atau keduanya, sebagai <MessageWeight>.

Atau, jika ingin menghitung pesan POST sebagai dua kali lebih mahal daripada pesan GET, Anda akan menetapkan <MessageWeight> ke 2 untuk POST dan 1 untuk GET. Misalkan kuotanya adalah 10 pesan per menit dan proxy memproses 5 permintaan POST dalam 35 detik pertama. Proxy akan menolak permintaan tambahan apa pun, POST atau GET, hingga penghitung direset.

Nilai yang mewakili <MessageWeight> harus ditentukan menggunakan variabel alur, dan dapat diekstrak dari header HTTP, parameter kueri, payload permintaan XML atau JSON, atau variabel alur lainnya. Misalnya, Anda dapat mengekstrak nilai dari payload respons ke dalam variabel bernama extracted.message_weight, lalu menggunakannya untuk <MessageWeight>:

<MessageWeight ref="extracted.message_weight"/>

Jika variabel flow me-resolve ke 0, permintaan tidak akan memengaruhi penghitung.

<UseQuotaConfigInAPIProduct>

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

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

Untuk informasi selengkapnya, lihat referensi berikut:

• <DefaultConfig>
• Apa yang dimaksud dengan produk API?
• Mengelola produk API

<DefaultConfig>

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

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:

• Apa yang dimaksud dengan produk API?
• Mengelola produk API

<SharedName>

Mengidentifikasi kebijakan Kuota ini sebagai dibagikan. 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 informasi dan contoh selengkapnya, lihat Mengonfigurasi penghitung kuota bersama.

<CountOnly>

Tempatkan kebijakan Kuota dengan elemen ini ditetapkan ke true dalam langkah dalam alur respons ProxyEndpoint untuk menambah penghitung kuota yang mendasarinya tanpa mengirim error kembali ke klien saat batas kuota terlampaui. Jika elemen ini ada, elemen <SharedName> juga harus ada dan elemen <EnforceOnly> tidak boleh ada.

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

<EnforceOnly>

Tempatkan kebijakan Kuota dengan elemen ini ditetapkan ke true dalam alur permintaan proxy API untuk menerapkan kuota tanpa menambah penghitung kuota. Konfigurasi ini memungkinkan penerapan batas kapasitas yang ditangguhkan berdasarkan bobot pesan yang hanya dapat diketahui dalam alur respons. Jika elemen ini ada, <SharedName> juga harus ada dan elemen <CountOnly> tidak boleh ada.

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

Variabel alur

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

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

Error saat deployment

Variabel error

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

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