Kebijakan kuota

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 mencatat 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. Dengan menggunakan kebijakan Kuota, Anda dapat, misalnya, membatasi aplikasi menjadi 1 permintaan per menit,atau 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 mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, lihat Jenis kebijakan.

Saat proxy API mencapai batas kuotanya, Apigee akan menolak panggilan API berikutnya dan menampilkan pesan error hingga penghitung Kuota direset secara otomatis 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 laju 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 API Model Bahasa Besar (LLM), 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 (atau burst) traffic 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 itu, gunakan kebijakan SpikeArrest.

Video

Video ini memperkenalkan pengelolaan kuota dengan kebijakan Kuota:

Jenis kebijakan kuota

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

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

Nilai type yang valid meliputi:

• calendar: Mengonfigurasi kuota berdasarkan waktu mulai eksplisit. Penghitung kuota untuk setiap aplikasi diperbarui berdasarkan nilai <StartTime>, <Interval>, dan <TimeUnit> yang Anda tetapkan.
• rollingwindow: Mengonfigurasi kuota yang menggunakan "periode berjalan" untuk menentukan penggunaan kuota. Dengan rollingwindow, Anda menentukan ukuran periode waktu dengan elemen <Interval> dan <TimeUnit>; misalnya, 1 hari. Saat permintaan masuk, Apigee akan melihat waktu persis permintaan (misalnya 17.01), menghitung jumlah permintaan yang masuk antara waktu tersebut dan 17.01 pada hari sebelumnya (1 hari), dan menentukan apakah kuota telah terlampaui atau tidak selama jangka waktu 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 kapan kuota direset untuk setiap jenis:

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

Tabel tidak menjelaskan kapan jumlah direset untuk jenis rollingwindow. Hal ini karena kuota periode berjalan berfungsi sedikit berbeda, berdasarkan periode lihat kembali, 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 memungkinkan 1.000 permintaan. Permintaan baru masuk pada pukul 16.45. Kebijakan menghitung jumlah kuota untuk jangka waktu 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, 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 dijalankan dalam alur proxy API, penghitung kuota akan berkurang. Saat 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 cara kerjanya.

Cara penghitungan kuota untuk produk API

Jika proxy API Anda 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 operasi individual.

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

• Jika suatu operasi memiliki kuota yang ditentukan untuknya, aturan kuota operasi tersebut 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 suatu operasi tidak memiliki kuota yang ditentukan untuknya, aturan kuota tingkat produk 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 di tingkat produk maupun operasi -- aturan kuota yang ditentukan dalam kebijakan berlaku; namun, dalam kasus ini juga, penghitung kuota terpisah dipertahankan untuk setiap operasi dalam 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 di tingkat produk API digunakan bersama oleh semua operasi yang tidak memiliki kuota sendiri. Efek konfigurasi ini adalah membuat penghitung global di tingkat proxy API untuk produk API ini.

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

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

Gambar 1: Penggunaan flag quotaCounterScope

Secara default, jika suatu operasi tidak memiliki kuota yang ditentukan, aturan kuota tingkat produk akan diterapkan; namun, penghitung kuota terpisah tetap 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 dalam proxy API. Nama penghitung kuota didasarkan pada atribut name kebijakan.

Misalnya, Anda membuat kebijakan Kuota bernama MyQuotaPolicy dengan batas 5 permintaan dan menempatkannya pada 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 counternya = 1
• Alur B dieksekusi -> MyQuotaPolicy dieksekusi dan counternya = 2
• Alur A dieksekusi -> MyQuotaPolicy dieksekusi dan counternya = 3
• Alur C dieksekusi -> MyQuotaPolicy dieksekusi dan counternya = 4
• Flow A dieksekusi -> MyQuotaPolicy dieksekusi dan counternya = 5

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

Menggunakan kebijakan Kuota yang sama di lebih dari satu tempat dalam alur proxy API, yang secara tidak sengaja dapat menyebabkan Kuota habis lebih cepat dari yang Anda harapkan, adalah antipola yang dijelaskan dalam 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 membuat permintaan, developer aplikasi yang membuat permintaan, ID klien atau ID klien lainnya, dan banyak lagi. 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 merepresentasikan 4 Februari 2021.

Waktu dalam sehari 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 terakhir biasanya lebih disukai.

Mendapatkan setelan kuota dari konfigurasi produk API

Anda dapat menetapkan batas kuota dalam 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 agar kebijakan kuota dapat merujuknya:

• Kebijakan kuota dapat menggunakan setelan seragam di semua proxy API dalam produk API.
• Anda dapat membuat perubahan runtime pada setelan kuota di produk API, dan kebijakan kuota yang mereferensikan nilai tersebut akan otomatis 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

Dalam kasus sederhana, kebijakan Kuota akan menambah penghitungnya satu kali untuk setiap permintaan yang dikirim ke proxy API, selama pemrosesan permintaan awal. Dalam beberapa kasus, Anda mungkin ingin memeriksa apakah kuota terlampaui saat penanganan awal permintaan masuk, tetapi menambah penghitung hanya selama penanganan respons. Hal ini masuk akal jika biaya atau berat 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 masuk, dan mengakumulasi jumlah terhadap kuota berdasarkan informasi yang berasal dari respons target.

Misalnya, Anda memiliki proxy API yang menggunakan LLM sebagai target, dan Anda 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.
• Untuk 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 menunjukkan 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 VerifyAPIKey policy yang disebut my-verify-key-policy digunakan untuk memeriksa kunci API aplikasi dalam permintaan. Nilai variabel berasal dari setelan kuota pada produk API yang terkait dengan kunci, seperti yang dijelaskan dalam Mendapatkan setelan kuota dari konfigurasi produk API.

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

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 diprioritaskan. Jika countRef tidak diselesaikan saat runtime, nilai count akan digunakan.

Anda juga dapat menentukan elemen <Class> sebagai turunan <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>:

<Class>

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

Untuk menggunakan elemen <Class>, tentukan variabel alur 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> (anak dari <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. Mana yang digunakan bergantung pada parameter kueri yang diteruskan, seperti yang ditunjukkan dalam contoh <Class>.

Tabel berikut mencantumkan atribut <Allow>:

<Interval>

Menentukan jumlah jangka waktu saat kuota dihitung.

Gunakan untuk menentukan bilangan bulat (misalnya, 1, 2, 5, 60, dan sebagainya) yang akan dipasangkan 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 unit 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 disetel ke calendar, tentukan tanggal dan waktu saat penghitung kuota mulai menghitung, terlepas dari apakah ada permintaan yang telah diterima dari aplikasi mana pun.

Contoh:

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

<Distributed>

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

Setel 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 Anda 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 serentak.

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

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

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 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 disinkronkan setiap M pesan, dengan M adalah nilai yang ditentukan dalam elemen, atau setiap 10 detik, mana saja yang lebih dulu.
• Jika kedua elemen ada, kuota disinkronkan setiap M pesan atau setiap N detik, mana saja yang lebih dulu.
• Jika <AsynchronousConfiguration> tidak ada atau tidak ada elemen turunan, kuota disinkronkan setiap 10 detik, terlepas dari jumlah pesan yang telah ditangani.

<SyncIntervalInSeconds>

Menggantikan 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 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 Anda tetapkan 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 Alur, dan untuk mengetahui daftar variabel terkenal yang ditentukan oleh Apigee, lihat Referensi variabel alur.

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 kontennya atau nilai panggilan.

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

Atau, jika Anda 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, POST atau GET, hingga penghitung direset.

Nilai yang merepresentasikan <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 alur diselesaikan menjadi 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 VerifyAPIKey policy atau operasi kebijakan ValidateToken dari OAuthv2 policy dalam alur.

Tabel berikut menjelaskan atribut <UseQuotaConfigInAPIProduct>:

Untuk informasi selengkapnya, lihat referensi berikut:

• <DefaultConfig>
• Apa itu 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 atau API produk API dan dalam kebijakan Kuota. Namun, jika Anda melakukannya, setelan pada produk API akan lebih 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 itu produk API?
• Mengelola produk API

<SharedName>

Mengidentifikasi kebijakan Kuota ini sebagai bersama. Semua kebijakan Kuota dalam proxy API dengan nilai <SharedName> yang sama menggunakan 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.

<CountOnly>

Tempatkan kebijakan Kuota dengan elemen ini yang ditetapkan ke true dalam langkah di alur respons ProxyEndpoint untuk menaikkan penghitung kuota pokok tanpa mengirimkan 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 yang ditetapkan ke true dalam alur permintaan proxy API untuk menerapkan kuota tanpa menaikkan penghitung kuota. Konfigurasi ini memungkinkan penegakan batas frekuensi 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 mengetahui informasi dan contoh selengkapnya, lihat Mengonfigurasi penghitung kuota bersama.

Variabel alur

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

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan serta variabel kesalahan yang ditetapkan oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika 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 dijalankan.

Error saat deployment

Variabel kesalahan

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