Kebijakan kuota

Anda sedang melihat dokumentasi Apigee Edge.
Lihat dokumentasi Apigee X.

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 itu, gunakan kebijakan Spike Arrest. Lihat kebijakan Penahanan Lonjakan.

Video

Video berikut memperkenalkan pengelolaan kuota dengan kebijakan Kuota:

Sample

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 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 jumlah panggilan API yang dilakukan oleh aplikasi selama interval waktu tertentu. Dengan kebijakan Kuota, Anda dapat, misalnya, membatasi aplikasi hingga 1 permintaan per menit,atau hingga 10.000 permintaan per bulan.

Misalnya, jika Kuota didefinisikan 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 dari 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 dari Quota yang disebut SpikeArrest mencegah lonjakan traffic (atau burst) yang dapat disebabkan oleh peningkatan penggunaan secara tiba-tiba, klien yang berisi bug, atau serangan berbahaya. Untuk mengetahui informasi selengkapnya tentang SpikeArrest, lihat kebijakan Spike Arrest.

Kuota berlaku untuk masing-masing 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 saat direset, seperti yang ditunjukkan pada tabel berikut:

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

Tabel tidak mencantumkan nilai untuk jenis rollingwindow. Kuota berkelanjutan dapat digunakan dengan menyetel ukuran "periode" kuota, misalnya periode satu jam atau satu hari. Saat permintaan baru masuk, kebijakan ini akan menentukan apakah kuota telah terlampaui dalam "periode" terakhir.

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, pukul 16.46, permintaan lain masuk. Kini, kebijakan tersebut menghitung jumlah kuota sejak pukul 14.46 untuk mengetahui apakah batas tersebut telah terlampaui.

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

Memahami penghitung kuota

Secara default, kebijakan Kuota 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 dalam beberapa alur, pendekatan ini mempertahankan satu penghitung yang diperbarui oleh semua instance kebijakan:

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

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

Menggunakan kebijakan Kuota yang sama di lebih dari satu tempat dalam alur proxy API, yang dapat tidak sengaja menyebabkan Kuota habis lebih cepat dari yang Anda harapkan, merupakan anti-pola yang dijelaskan dalam Buku Apigee Edge Antipatterns.

Atau, Anda dapat menentukan beberapa kebijakan Kuota di proxy API Anda 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 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 ISO 8601 Standar Internasional.

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

Waktu didefinisikan 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 adalah tanggal dan waktu yang sama dengan 2015-02-05 00:00:00. Parameter yang disebut biasanya adalah notasi pilihan.

Mendapatkan setelan kuota dari konfigurasi produk API

Anda dapat menetapkan batas kuota di konfigurasi produk API. Batas tersebut tidak menerapkan kuota secara otomatis. Sebagai gantinya, Anda dapat merujuk setelan kuota produk di kebijakan kuota. Berikut adalah beberapa keuntungan dari menetapkan kuota produk untuk referensi 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 tersebut akan otomatis memiliki nilai kuota yang telah diperbarui.

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

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

Referensi elemen

Berikut adalah elemen dan atribut yang dapat Anda konfigurasikan pada kebijakan ini. Perhatikan bahwa beberapa kombinasi elemen saling eksklusif atau tidak diperlukan. Lihat contoh untuk penggunaan tertentu. Variabel verifyapikey.VerifyAPIKey.apiproduct.* di bawah tersedia secara default saat kebijakan Verify API Key yang disebut "VerifyAPIKey" digunakan untuk memeriksa kunci API aplikasi dalam permintaan. Nilai variabel berasal dari setelan kuota pada produk API yang dikaitkan dengan kunci, seperti yang dijelaskan dalam 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 khusus untuk kebijakan ini.

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

Elemen <DisplayName>

Selain atribut name, beri label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa natural 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, maka countRef akan diprioritaskan. Jika countRef tidak di-resolve pada runtime, nilai count akan digunakan.

Atribut

Elemen <Allow>/<Class>

Elemen <Class> memungkinkan Anda mengondisikan nilai elemen <Allow> berdasarkan nilai variabel alur. Untuk setiap tag turunan <Allow> yang berbeda dari <Class>, kebijakan ini mempertahankan penghitung yang berbeda.

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

Atribut

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

Elemen <Allow> menentukan batas 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 yang bernama peak_time dan off_peak_time.

Atribut

Elemen <Interval>

Gunakan untuk menentukan bilangan bulat (misalnya, 1, 2, 5, 60, dan seterusnya) yang akan dipasangkan dengan TimeUnit yang Anda tentukan (menit, jam, hari, minggu, atau bulan) untuk menentukan jangka waktu selama Edge menghitung penggunaan kuota.

Misalnya, Interval dari 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 unit waktu yang berlaku untuk kuota.

Misalnya, Interval dari 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, terlepas dari apakah ada permintaan yang diterima dari aplikasi apa pun.

Anda harus memberikan StartTime eksplisit saat type ditetapkan secara eksplisit ke calendar,. Anda tidak dapat menggunakan referensi ke variabel flow. Jika Anda menentukan nilai StartTime saat tidak ada nilai type yang ditetapkan, Anda akan menerima error.

Contoh:

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

Elemen <Distributed>

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

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

<Distributed>true</Distributed>

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

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

Elemen <Synchronous>

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

Tetapkan ke false untuk memperbarui penghitung kuota secara asinkron. Artinya, beberapa panggilan API yang melebihi kuota mungkin akan diteruskan, bergantung pada kapan penghitung kuota di repositori pusat diperbarui secara asinkron. Namun, Anda tidak akan melihat potensi dampak performa yang berkaitan dengan update sinkron.

Interval pembaruan asinkron default adalah 10 detik. Gunakan elemen AsynchronousConfiguration untuk mengonfigurasi perilaku asinkron ini.

<Synchronous>false</Synchronous>

Elemen <AsyncConfiguration>

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

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

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

atau

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

Elemen <AsyncConfiguration>/<SyncIntervalInseconds>

Gunakan metode ini untuk mengganti perilaku default yang digunakan untuk melakukan update asinkron setelah interval 10 detik.

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

Interval sinkronisasi harus lebih dari 10 detik seperti yang dijelaskan di topik Batas.

Elemen <AsyncConfiguration>/<SyncMessageCount>

Menentukan jumlah permintaan di seluruh pemroses pesan Apigee antara pembaruan 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 flow.

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 memakai lebih banyak resource komputasi daripada pesan lainnya.

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 kuota adalah 10 pesan per menit dan MessageWeight untuk permintaan POST adalah 2, kuota akan mengizinkan 5 permintaan POST dalam interval 10 menit. Permintaan tambahan apa pun, yaitu POST atau GET, sebelum penghitung direset akan 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 flow lainnya. Misalnya, Anda menetapkannya dalam header bernama weight:

<MessageWeight ref="message_weight"/>

Variabel flow

Variabel Flow yang telah ditentukan berikut ini akan otomatis diisi saat kebijakan Kuota dijalankan. Untuk informasi selengkapnya tentang Variabel alur, lihat Referensi variabel.

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan error yang dikembalikan, serta variabel kesalahan yang disetel oleh Edge saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan fault untuk menangani fault. 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 deployment

Variabel kesalahan

Variabel ini ditetapkan saat kebijakan ini memicu error. Untuk 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, Kuota Spike, dan Batas Tarif Serentak