Kebijakan kuota

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Apa

Gunakan kebijakan Kuota untuk mengonfigurasi jumlah pesan permintaan yang diizinkan oleh proxy API selama jangka waktu tertentu, seperti menit, jam, hari, minggu, atau bulan. Anda dapat menetapkan kuota agar sama untuk semua aplikasi yang mengakses proxy API, atau Anda dapat menetapkan kuota berdasarkan:

• Produk yang berisi proxy API
• Aplikasi yang meminta API
• Developer aplikasi
• Banyak kriteria lainnya

Jangan gunakan Kuota untuk melindungi dari lonjakan traffic secara keseluruhan. Untuk melakukannya, gunakan kebijakan Spike Arrest. Lihat kebijakan Penghentian Peningkatan Lalu Lintas.

Video

Video ini memperkenalkan pengelolaan kuota dengan Kebijakan kuota:

Contoh

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>2017-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 async="false" continueOnError="false" enabled="true" name="ReturnQuotaVars">
    <AssignTo createNew="false" type="response"/>
    <Set>
        <Headers>
            <Header name="QuotaLimit">{ratelimit.QuotaPolicy.allowed.count}</Header>
            <Header name="QuotaUsed">{ratelimit.QuotaPolicy.used.count}</Header>
            <Header name="QuotaResetUTC">{ratelimit.QuotaPolicy.expiry.time}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

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

<Quota name="QuotaPolicy" type="calendar">
  <Identifier ref="request.header.clientId"/> 
  <StartTime>2017-02-18 10:00:00</StartTime>
  <Interval>5</Interval>
  <TimeUnit>hour</TimeUnit>
  <Allow count="99"/>
</Quota>

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

Tentang Kebijakan kuota

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

Misalnya, jika Kuota ditentukan sebagai 10.000 pesan per bulan, pembatasan kapasitas akan dimulai setelah pesan ke-10.000. Tidak masalah apakah 10.000 pesan dihitung pada hari pertama atau hari terakhir periode tersebut; tidak ada area permintaan tambahan yang diizinkan hingga penghitung Kuota secara otomatis direset pada akhir interval waktu yang ditentukan, atau hingga Kuota direset secara eksplisit menggunakan kebijakan Reset Kuota.

Variasi pada Kuota yang disebut SpikeArrest mencegah lonjakan traffic (atau burst) yang dapat disebabkan oleh peningkatan penggunaan secara tiba-tiba, klien yang bermasalah, atau serangan berbahaya. Untuk mengetahui informasi selengkapnya tentang SpikeArrest, lihat Kebijakan Spike Arrest.

Kuota berlaku untuk setiap proxy API dan tidak didistribusikan di antara proxy API. Misalnya, jika Anda memiliki tiga proxy API dalam produk API, satu kuota tidak akan dibagikan ke ketiganya meskipun ketiganya menggunakan konfigurasi kebijakan kuota yang sama.

Jenis kebijakan kuota

Kebijakan Kuota mendukung beberapa jenis kebijakan: default, calendar, flexi, dan rollingwindow. Setiap jenis menentukan kapan penghitung kuota dimulai dan direset, seperti yang ditunjukkan dalam tabel berikut:

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

Tabel tidak mencantumkan nilai untuk jenis rollingwindow. Kuota periode bergulir berfungsi dengan menetapkan ukuran "periode" kuota, seperti periode satu jam atau satu hari. Saat permintaan baru masuk, kebijakan akan menentukan apakah kuota telah terlampaui dalam "periode" waktu sebelumnya.

Misalnya, Anda menentukan periode dua jam yang mengizinkan 1.000 permintaan. Permintaan baru masuk pada pukul 16.45. Kebijakan ini menghitung jumlah kuota untuk periode dua jam terakhir, yang berarti jumlah permintaan sejak pukul 14.45. Jika batas kuota belum terlampaui dalam periode dua jam tersebut, permintaan akan diizinkan.

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

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

Memahami penghitung kuota

Secara default, kebijakan Kuota 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 kerja 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 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 perkirakan, adalah anti-pola yang dijelaskan dalam The Book of Apigee Edge Antipatterns.

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.

Atau, gunakan elemen <Class> atau <Identifier> dalam kebijakan Kuota untuk menentukan beberapa penghitung unik dalam satu kebijakan. Dengan menggunakan elemen ini, satu kebijakan dapat mempertahankan penghitung yang berbeda berdasarkan aplikasi yang membuat permintaan, developer aplikasi yang membuat permintaan, client ID atau ID klien lainnya, dan lainnya. Lihat contoh di atas untuk 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, 2015-02-04 mewakili 4 Februari 2015.

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, 2015-02-04 24:00:00 memiliki tanggal dan waktu yang sama dengan 2015-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 Membuat produk API.

Referensi elemen

Berikut adalah elemen dan atribut yang dapat Anda konfigurasi pada kebijakan ini. Perhatikan bahwa beberapa kombinasi elemen bersifat eksklusif atau tidak diperlukan. Lihat contoh untuk penggunaan tertentu. Variabel verifyapikey.VerifyAPIKey.apiproduct.* di bawah tersedia secara default saat kebijakan Verifikasi Kunci API yang disebut "VerifyAPIKey" digunakan untuk memeriksa kunci API aplikasi dalam permintaan. Nilai variabel berasal dari setelan kuota di produk API yang terkait dengan kunci, seperti yang dijelaskan dalam artikel Mendapatkan setelan kuota dari konfigurasi produk API.

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">
   <DisplayName>Quota 3</DisplayName>
   <Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/>
   <Allow>
      <Class ref="request.queryparam.time_variable">
        <Allow class="peak_time" count="5000"/>
        <Allow class="off_peak_time" count="1000"/>
      </Class>
   </Allow>
   <Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval> 
   <TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>
   <StartTime>2017-7-16 12:00:00</StartTime> 
   <Distributed>false</Distributed> 
   <Synchronous>false</Synchronous> 
   <AsynchronousConfiguration> 
      <SyncIntervalInSeconds>20</SyncIntervalInSeconds> 
      <SyncMessageCount>5</SyncMessageCount> 
   </AsynchronousConfiguration> 
   <Identifier/> 
   <MessageWeight/> 
</Quota>

Atribut <Quota>

<Quota async="false" continueOnError="false" enabled="true" name="Quota-3" type="calendar">

Atribut berikut bersifat khusus untuk kebijakan ini.

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

&lt;DisplayName&gt; elemen

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

<DisplayName>Policy Display Name</DisplayName>

Elemen <Allow>

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

Berikut adalah tiga cara untuk menetapkan elemen <Allow>:

<Allow count="2000"/> 

<Allow countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 

<Allow count="2000" countRef="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.limit"/> 

Jika Anda menentukan count dan countRef, countRef akan mendapatkan prioritas. Jika countRef tidak di-resolve saat runtime, nilai count akan digunakan.

Atribut

Elemen <Allow>/<Class>

Elemen <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 tag <Class>. Edge kemudian menggunakan nilai variabel alur untuk memilih salah satu tag turunan <Allow> guna menentukan jumlah kebijakan yang diizinkan. Edge mencocokkan nilai variabel alur dengan atribut class tag <Allow>, seperti yang 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.

Atribut

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

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

Contoh:

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

Dalam contoh ini, kebijakan Kuota mempertahankan dua penghitung kuota bernama peak_time dan off_peak_time.

Atribut

Elemen <Interval>

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

Atribut

Elemen <TimeUnit>

Gunakan untuk menentukan satuan waktu yang berlaku untuk kuota.

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

<TimeUnit ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.timeunit">month</TimeUnit>

Atribut

Elemen <StartTime>

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

Contoh:

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

Elemen <Distributed>

Penginstalan Edge dapat menggunakan satu atau beberapa Message Processor untuk memproses permintaan. Tetapkan elemen ini ke true untuk menentukan bahwa kebijakan harus mempertahankan penghitung pusat dan terus menyinkronkannya di semua Message Processor. Pemroses pesan dapat berada di seluruh zona dan/atau region ketersediaan.

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

<Distributed>true</Distributed>

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

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

Elemen <Synchronous>

Tetapkan ke true untuk memperbarui penghitung kuota terdistribusi secara sinkron. Hal ini berarti pembaruan pada 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>

Elemen <AsynchronousConfiguration>

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

Anda dapat menyinkronkan setelah jangka waktu atau jumlah pesan, menggunakan elemen turunan SyncIntervalInSeconds atau SyncMessageCount. Keduanya bersifat eksklusif. Misalnya,

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

atau

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

Elemen <AsynchronousConfiguration>/<SyncIntervalInSeconds>

Gunakan ini untuk 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 topik Batas.

<AsynchronousConfiguration>/<SyncMessageCount> element

Menentukan jumlah permintaan di semua pemroses pesan Apigee di antara update kuota.

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

Contoh ini menentukan bahwa jumlah kuota diperbarui setiap 5 permintaan di setiap pemroses pesan Apigee Edge.

Elemen <Identifier>

Gunakan elemen <Identifier> untuk mengonfigurasi kebijakan guna membuat penghitung unik berdasarkan variabel alur.

Jika Anda tidak menggunakan elemen ini, kebijakan akan menggunakan satu penghitung yang diterapkan terhadap kuota.

Elemen ini juga dibahas dalam postingan Komunitas Apigee berikut: http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html.

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

Atribut

Elemen <MessageWeight>

Gunakan untuk menentukan bobot yang ditetapkan ke setiap pesan. Gunakan bobot pesan untuk meningkatkan dampak pesan permintaan yang, misalnya, menggunakan lebih banyak resource komputasi daripada yang lain.

Misalnya, Anda ingin menghitung pesan POST sebagai dua kali lebih "berat" atau mahal, seperti pesan GET. Oleh karena itu, Anda menetapkan MessageWeight ke 2 untuk POST dan 1 untuk GET. Anda bahkan dapat menetapkan MessageWeight ke 0 sehingga permintaan tidak memengaruhi penghitung. Dalam contoh ini, jika kuotanya adalah 10 pesan per menit dan MessageWeight untuk permintaan POST adalah 2, kuota akan mengizinkan 5 permintaan POST dalam interval 10 menit. Setiap permintaan tambahan, POST atau GET, sebelum reset penghitung ditolak.

Nilai yang mewakili MessageWeight harus ditentukan oleh variabel alur, dan dapat diekstrak dari header HTTP, parameter kueri, payload permintaan XML atau JSON, atau variabel alur lainnya. Misalnya, Anda menetapkannya di header bernama weight:

<MessageWeight ref="message_weight"/>

Variabel alur

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

Referensi error

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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, Penghentian Lonjakan, dan Batas Laju Serentak