سیاست سهمیه بندی

شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات

چه

از سیاست سهمیه‌بندی برای پیکربندی تعداد پیام‌های درخواستی که یک پروکسی API در یک دوره زمانی، مانند دقیقه، ساعت، روز، هفته یا ماه، اجازه می‌دهد، استفاده کنید. می‌توانید سهمیه را برای همه برنامه‌هایی که به پروکسی API دسترسی دارند، یکسان تنظیم کنید، یا می‌توانید سهمیه را بر اساس موارد زیر تنظیم کنید:

• محصولی که حاوی پروکسی API است
• برنامه‌ای که API را درخواست می‌کند
• توسعه دهنده برنامه
• بسیاری از معیارهای دیگر

از سهمیه برای محافظت در برابر افزایش ناگهانی ترافیک استفاده نکنید. برای این کار، از سیاست Spike Arrest استفاده کنید. به سیاست Spike Arrest مراجعه کنید.

ویدیوها

این ویدیوها مدیریت سهمیه را با سیاست سهمیه‌بندی معرفی می‌کنند:

نمونه‌ها

این نمونه‌های کد سیاست، نحوه شروع و پایان دوره‌های سهمیه‌بندی را با موارد زیر نشان می‌دهند:

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

درباره سیاست سهمیه‌بندی

سهمیه، سهمیه‌ای از پیام‌های درخواست است که یک پروکسی API می‌تواند در یک بازه زمانی، مانند دقیقه، ساعت، روز، هفته یا ماه، مدیریت کند. این سیاست، شمارنده‌هایی را نگهداری می‌کند که تعداد درخواست‌های دریافتی توسط پروکسی API را محاسبه می‌کنند. این قابلیت، ارائه‌دهندگان API را قادر می‌سازد تا محدودیت‌هایی را بر تعداد فراخوانی‌های API انجام شده توسط برنامه‌ها در یک بازه زمانی اعمال کنند. با استفاده از سیاست‌های سهمیه، می‌توانید، به عنوان مثال، برنامه‌ها را به ۱ درخواست در دقیقه یا به ۱۰۰۰۰ درخواست در ماه محدود کنید.

برای مثال، اگر سهمیه به صورت ۱۰،۰۰۰ پیام در ماه تعریف شود، محدود کردن سرعت پس از ۱۰،۰۰۰مین پیام شروع می‌شود. فرقی نمی‌کند که ۱۰،۰۰۰ پیام در روز اول یا آخرین روز آن دوره شمارش شده باشند؛ هیچ ناحیه درخواست اضافی مجاز نیست تا زمانی که شمارنده سهمیه به طور خودکار در پایان بازه زمانی مشخص شده بازنشانی شود، یا تا زمانی که سهمیه به طور صریح با استفاده از سیاست بازنشانی سهمیه بازنشانی شود.

نوعی از سهمیه‌بندی به نام SpikeArrest از افزایش ناگهانی (یا انفجار) ترافیک که می‌تواند ناشی از افزایش ناگهانی استفاده، کلاینت‌های دارای باگ یا حملات مخرب باشد، جلوگیری می‌کند. برای اطلاعات بیشتر در مورد SpikeArrest، به سیاست Spike Arrest مراجعه کنید.

سهمیه‌ها به پروکسی‌های API منفرد اعمال می‌شوند و بین پروکسی‌های API توزیع نمی‌شوند. برای مثال، اگر در یک محصول API سه پروکسی API داشته باشید، یک سهمیه واحد بین هر سه به اشتراک گذاشته نمی‌شود، حتی اگر هر سه از پیکربندی سیاست سهمیه‌بندی یکسانی استفاده کنند.

انواع سیاست سهمیه‌بندی

سیاست سهمیه‌بندی از چندین نوع سیاست مختلف پشتیبانی می‌کند: پیش‌فرض، calendar ، flexi و rollingwindow . هر نوع، زمان شروع و پایان شمارنده‌ی سهمیه‌بندی را مشخص می‌کند، همانطور که در جدول زیر نشان داده شده است:

برای type="calendar" ، باید مقدار <StartTime> را مشخص کنید.

جدول مقدار مربوط به نوع rollingwindow را فهرست نمی‌کند. سهمیه‌بندی پنجره‌ی غلتان با تنظیم اندازه‌ی یک «پنجره» سهمیه، مانند یک پنجره‌ی یک ساعته یا یک روزه، کار می‌کند. وقتی درخواست جدیدی می‌رسد، این سیاست تعیین می‌کند که آیا سهمیه در «پنجره» زمانی گذشته فراتر رفته است یا خیر.

برای مثال، شما یک بازه زمانی دو ساعته تعریف می‌کنید که ۱۰۰۰ درخواست را مجاز می‌داند. یک درخواست جدید ساعت ۴:۴۵ بعد از ظهر می‌رسد. این سیاست تعداد سهمیه را برای بازه زمانی دو ساعت گذشته محاسبه می‌کند، به این معنی که تعداد درخواست‌ها از ساعت ۲:۴۵ بعد از ظهر به بعد. اگر محدودیت سهمیه در آن بازه زمانی دو ساعته تجاوز نکرده باشد، درخواست مجاز است.

یک دقیقه بعد، ساعت ۴:۴۶ بعد از ظهر، درخواست دیگری می‌رسد. اکنون این خط‌مشی تعداد سهمیه را از ساعت ۲:۴۶ بعد از ظهر محاسبه می‌کند تا مشخص شود که آیا از حد مجاز فراتر رفته است یا خیر.

برای نوع rollingwindow ، شمارنده هرگز بازنشانی نمی‌شود، بلکه در هر درخواست دوباره محاسبه می‌شود.

درک شمارنده‌های سهمیه

به طور پیش‌فرض، یک سیاست سهمیه‌بندی، صرف نظر از اینکه چند بار در یک پروکسی API به آن ارجاع می‌دهید، یک شمارنده واحد را نگهداری می‌کند. نام شمارنده سهمیه‌بندی بر اساس ویژگی name سیاست تعیین می‌شود.

برای مثال، شما یک سیاست سهمیه‌بندی با نام MyQuotaPolicy با محدودیت ۵ درخواست ایجاد می‌کنید و آن را روی چندین جریان (جریان A، B و C) در پروکسی API قرار می‌دهید. اگرچه در چندین جریان استفاده می‌شود، اما یک شمارنده واحد را حفظ می‌کند که توسط همه نمونه‌های این سیاست به‌روزرسانی می‌شود:

• جریان A اجرا می‌شود -> MyQuotaPolicy اجرا می‌شود و شمارنده آن برابر با ۱ است.
• جریان B اجرا می‌شود -> MyQuotaPolicy اجرا می‌شود و شمارنده آن برابر با ۲ است.
• جریان A اجرا می‌شود -> MyQuotaPolicy اجرا می‌شود و شمارنده آن برابر با ۳ است.
• جریان C اجرا می‌شود -> MyQuotaPolicy اجرا می‌شود و شمارنده آن برابر با ۴ می‌شود.
• جریان A اجرا می‌شود -> MyQuotaPolicy اجرا می‌شود و شمارنده آن برابر با ۵ است.

درخواست بعدی به هر یک از سه جریان رد می‌شود زیرا شمارنده سهمیه به حد مجاز خود رسیده است.

استفاده از یک سیاست سهمیه‌بندی یکسان در بیش از یک مکان در جریان پروکسی API، که می‌تواند ناخواسته باعث شود سهمیه‌بندی سریع‌تر از آنچه انتظار دارید تمام شود، یک ضدالگو است که در کتاب ضدالگوهای Apigee Edge شرح داده شده است.

به عنوان یک روش جایگزین، می‌توانید چندین سیاست سهمیه‌بندی را در پروکسی API خود تعریف کنید و در هر جریان از یک سیاست متفاوت استفاده کنید. هر سیاست سهمیه‌بندی، بر اساس ویژگی name سیاست، شمارنده مخصوص به خود را حفظ می‌کند.

یا، از عناصر <Class> یا <Identifier> در سیاست Quota برای تعریف چندین شمارنده منحصر به فرد در یک سیاست واحد استفاده کنید. با استفاده از این عناصر، یک سیاست واحد می‌تواند شمارنده‌های مختلفی را بر اساس برنامه‌ای که درخواست را انجام می‌دهد، توسعه‌دهنده برنامه‌ای که درخواست را انجام می‌دهد، شناسه کلاینت یا شناسه کلاینت دیگر و موارد دیگر، حفظ کند. برای اطلاعات بیشتر در مورد استفاده از عناصر <Class> یا <Identifier> به مثال‌های بالا مراجعه کنید.

نمادگذاری زمان

تمام زمان‌های سهمیه‌بندی بر اساس منطقه زمانی هماهنگ جهانی (UTC) تنظیم شده‌اند.

نمادگذاری زمان سهمیه‌بندی از نمادگذاری تاریخ استاندارد بین‌المللی تعریف‌شده در استاندارد بین‌المللی ISO 8601 پیروی می‌کند.

تاریخ‌ها به صورت سال، ماه و روز و با فرمت زیر تعریف می‌شوند: YYYY-MM-DD . برای مثال، 2015-02-04 ‎ نشان دهنده ۴ فوریه ۲۰۱۵ است.

زمان روز به صورت ساعت، دقیقه و ثانیه با فرمت زیر تعریف می‌شود: hours:minutes:seconds . برای مثال، 23:59:59 نشان‌دهنده‌ی زمانی است که یک ثانیه قبل از نیمه‌شب است.

توجه داشته باشید که دو نمادگذاری، 00:00:00 و 24:00:00 ، برای تمایز دو نیمه‌شب مرتبط با یک تاریخ در دسترس هستند. بنابراین، تاریخ و زمان 2015-02-04 24:00:00 با تاریخ و زمان 2015-02-05 00:00:00 یکسان است. نمادگذاری دوم معمولاً ترجیح داده می‌شود.

دریافت تنظیمات سهمیه از پیکربندی محصول API

شما می‌توانید محدودیت‌های سهمیه را در پیکربندی‌های محصول API تنظیم کنید. این محدودیت‌ها به طور خودکار سهمیه را اعمال نمی‌کنند. در عوض، می‌توانید تنظیمات سهمیه محصول را در یک سیاست سهمیه‌بندی ارجاع دهید. در اینجا برخی از مزایای تعیین سهمیه روی محصول برای ارجاع به سیاست‌های سهمیه‌بندی آورده شده است:

• سیاست‌های سهمیه‌بندی می‌توانند از یک تنظیم یکسان در تمام پروکسی‌های API در محصول API استفاده کنند.
• شما می‌توانید در زمان اجرا، تنظیمات سهمیه‌بندی را روی یک محصول API تغییر دهید، و سیاست‌های سهمیه‌بندی که به طور خودکار به مقدار اشاره می‌کنند، مقادیر سهمیه‌بندی به‌روزرسانی‌شده‌ای دارند.

برای اطلاعات بیشتر در مورد استفاده از تنظیمات سهمیه از یک محصول API، به مثال "سهمیه پویا" در بالا مراجعه کنید .

برای اطلاعات بیشتر در مورد پیکربندی محصولات API با محدودیت‌های سهمیه، به بخش ایجاد محصولات API مراجعه کنید.

مرجع عنصر

در ادامه عناصر و ویژگی‌هایی که می‌توانید در این خط‌مشی پیکربندی کنید، آمده است. توجه داشته باشید که برخی از ترکیبات عناصر متقابلاً منحصر به فرد هستند یا مورد نیاز نیستند. برای کاربرد خاص، به نمونه‌ها مراجعه کنید. متغیرهای verifyapikey.VerifyAPIKey.apiproduct.* زیر به طور پیش‌فرض در دسترس هستند، زمانی که از یک خط‌مشی Verify API Key به نام "VerifyAPIKey" برای بررسی کلید API برنامه در درخواست استفاده می‌شود. مقادیر متغیر از تنظیمات سهمیه در محصول API که کلید با آن مرتبط است، همانطور که در "دریافت تنظیمات سهمیه از پیکربندی محصول 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>

ویژگی‌های <Quota>

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

ویژگی‌های زیر مختص این سیاست هستند.

جدول زیر ویژگی هایی را توصیف می کند که برای همه عناصر اصلی خط مشی مشترک هستند:

عنصر <DisplayName>

علاوه بر ویژگی name برای برچسب‌گذاری خط‌مشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.

<DisplayName>Policy Display Name</DisplayName>

عنصر <مجاز>

محدودیت تعداد برای سهمیه را مشخص می‌کند. اگر شمارنده‌ی سیاست به این مقدار محدود برسد، فراخوانی‌های بعدی تا زمان تنظیم مجدد شمارنده رد می‌شوند.

در زیر سه روش برای تنظیم عنصر <Allow> نشان داده شده است:

<Allow count="2000"/>

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

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

اگر هم count و هم countRef را مشخص کنید، countRef اولویت پیدا می‌کند. اگر countRef در زمان اجرا حل نشود، از مقدار count استفاده می‌شود.

ویژگی‌ها

عنصر <Allow>/<Class>

عنصر <Class> به شما امکان می‌دهد مقدار عنصر <Allow> را بر اساس مقدار یک متغیر جریان، مشروط کنید. برای هر تگ فرزند <Allow> متفاوت از <Class> ، این سیاست یک شمارنده متفاوت را حفظ می‌کند.

برای استفاده از عنصر <Class> ، یک متغیر جریان را با استفاده از ویژگی ref به برچسب <Class> مشخص کنید. سپس Edge از مقدار متغیر جریان برای انتخاب یکی از برچسب‌های فرزند <Allow> برای تعیین تعداد مجاز خط‌مشی استفاده می‌کند. Edge مقدار متغیر جریان را با ویژگی class برچسب <Allow> مطابقت می‌دهد، همانطور که در زیر نشان داده شده است:

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

در این مثال، شمارنده سهمیه فعلی توسط مقدار پارامتر query مربوط به time_variable که با هر درخواست ارسال می‌شود، تعیین می‌شود. آن متغیر می‌تواند مقدار peak_time یا off_peak_time داشته باشد. اگر پارامتر query حاوی مقدار نامعتبری باشد، این خط‌مشی خطای نقض سهمیه را برمی‌گرداند.

ویژگی‌ها

عنصر <Allow>/<Class>/<Allow>

عنصر <Allow> محدودیت شمارنده سهمیه تعریف شده توسط عنصر <Class> را مشخص می‌کند. برای هر برچسب فرزند <Allow> متفاوت از <Class> ، این سیاست یک شمارنده متفاوت را حفظ می‌کند.

برای مثال:

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

در این مثال، سیاست سهمیه‌بندی دو شمارنده سهمیه‌بندی به نام‌های peak_time و off_peak_time را نگهداری می‌کند.

ویژگی‌ها

عنصر <فاصله>

برای مشخص کردن یک عدد صحیح (مثلاً ۱، ۲، ۵، ۶۰ و غیره) که با TimeUnit که مشخص می‌کنید (دقیقه، ساعت، روز، هفته یا ماه) جفت می‌شود تا یک دوره زمانی را تعیین کند که در طی آن Edge سهمیه استفاده را محاسبه می‌کند، استفاده کنید.

برای مثال، یک Interval 24 با TimeUnit hour به این معنی است که سهمیه در طول ۲۴ ساعت محاسبه خواهد شد.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>

ویژگی‌ها

عنصر <TimeUnit>

برای مشخص کردن واحد زمانی مربوط به سهمیه استفاده کنید.

برای مثال، یک Interval 24 با TimeUnit hour به این معنی است که سهمیه در طول ۲۴ ساعت محاسبه خواهد شد.

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

ویژگی‌ها

عنصر <زمان شروع>

وقتی type روی calendar, تاریخ و زمانی را مشخص می‌کند که شمارنده سهمیه شروع به شمارش می‌کند، صرف نظر از اینکه آیا درخواستی از هر برنامه‌ای دریافت شده است یا خیر.

برای مثال:

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

عنصر <توزیع‌شده>

نصب Edge می‌تواند از یک یا چند پردازنده پیام برای پردازش درخواست‌ها استفاده کند. این عنصر را روی true تنظیم کنید تا مشخص شود که این سیاست باید یک شمارنده مرکزی را حفظ کند و به طور مداوم آن را در تمام پردازنده‌های پیام همگام‌سازی کند. پردازنده‌های پیام می‌توانند در مناطق و/یا مناطق مختلف در دسترس باشند.

اگر از مقدار پیش‌فرض false استفاده کنید، ممکن است از سهمیه خود تجاوز کنید زیرا تعداد برای هر پردازنده پیام به اشتراک گذاشته نمی‌شود:

<Distributed>true</Distributed>

برای تضمین همگام‌سازی و به‌روزرسانی شمارنده‌ها در هر درخواست، <Distributed> و <Synchronous> را روی true تنظیم کنید:

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

عنصر <همزمان>

برای به‌روزرسانی همزمان شمارنده سهمیه توزیع‌شده، روی true تنظیم کنید. این بدان معناست که به‌روزرسانی شمارنده همزمان با بررسی سهمیه در درخواستی به API انجام می‌شود. اگر ضروری است که هیچ فراخوانی API روی سهمیه مجاز نباشد، روی true تنظیم کنید.

برای به‌روزرسانی غیرهمزمان شمارنده سهمیه، آن را روی false تنظیم کنید. این بدان معناست که بسته به زمان به‌روزرسانی غیرهمزمان شمارنده سهمیه در مخزن مرکزی، ممکن است برخی از فراخوانی‌های API که از سهمیه تجاوز می‌کنند، انجام شوند. با این حال، با تأثیرات بالقوه عملکرد مرتبط با به‌روزرسانی‌های همزمان مواجه نخواهید شد.

فاصله زمانی پیش‌فرض به‌روزرسانی ناهمزمان ۱۰ ثانیه است. از عنصر AsynchronousConfiguration برای پیکربندی این رفتار ناهمزمان استفاده کنید.

<Synchronous>false</Synchronous>

عنصر <AsynchronousConfiguration>

فاصله همگام‌سازی بین شمارنده‌های سهمیه توزیع‌شده را زمانی که عنصر پیکربندی سیاست <Synchronous> یا وجود ندارد یا وجود دارد و روی false تنظیم شده است، پیکربندی می‌کند.

شما می‌توانید با استفاده از عناصر فرزند SyncIntervalInSeconds یا SyncMessageCount ، همگام‌سازی را پس از یک دوره زمانی یا پس از شمارش پیام انجام دهید. این عناصر متقابلاً منحصر به فرد هستند. برای مثال،

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

یا

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

عنصر <AsynchronousConfiguration>/<SyncIntervalInSeconds>

از این برای لغو رفتار پیش‌فرض که در آن به‌روزرسانی‌های ناهمزمان پس از یک فاصله زمانی 10 ثانیه‌ای انجام می‌شوند، استفاده کنید.

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

فاصله همگام‌سازی باید ≥ 10 ثانیه باشد، همانطور که در مبحث محدودیت‌ها توضیح داده شده است.

عنصر <AsynchronousConfiguration>/<SyncMessageCount>

تعداد درخواست‌ها در تمام پردازنده‌های پیام Apigee بین به‌روزرسانی‌های سهمیه را مشخص می‌کند.

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

این مثال مشخص می‌کند که تعداد سهمیه هر 5 درخواست در هر پردازنده پیام Apigee Edge به‌روزرسانی می‌شود.

عنصر <شناسه>

از عنصر <Identifier> برای پیکربندی سیاست ایجاد شمارنده‌های منحصر به فرد بر اساس یک متغیر جریان استفاده کنید.

اگر از این عنصر استفاده نکنید، این سیاست از یک شمارنده واحد استفاده می‌کند که بر اساس سهمیه اعمال می‌شود.

این عنصر همچنین در پست زیر از انجمن Apigee با عنوان «شناسه سهمیه در سیاست‌های مختلف» مورد بحث قرار گرفته است.

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

ویژگی‌ها

عنصر <وزن پیام>

برای تعیین وزن اختصاص داده شده به هر پیام استفاده کنید. از وزن پیام برای افزایش تأثیر پیام‌های درخواستی که، برای مثال، منابع محاسباتی بیشتری نسبت به سایرین مصرف می‌کنند، استفاده کنید.

برای مثال، می‌خواهید پیام‌های POST را دو برابر "سنگین" یا گران‌تر از پیام‌های GET بشمارید. بنابراین، MessageWeight را برای POST روی ۲ و برای GET روی ۱ تنظیم می‌کنید. حتی می‌توانید MessageWeight را روی ۰ تنظیم کنید تا درخواست روی شمارنده تأثیر نگذارد. در این مثال، اگر سهمیه ۱۰ پیام در دقیقه باشد و MessageWeight برای درخواست‌های POST برابر 2 باشد، سهمیه اجازه ۵ درخواست POST را در هر فاصله ۱۰ دقیقه‌ای می‌دهد. هر درخواست اضافی، POST یا GET، قبل از تنظیم مجدد شمارنده رد می‌شود.

مقداری که نشان‌دهنده‌ی MessageWeight است باید توسط یک متغیر جریان مشخص شود و می‌تواند از هدرهای HTTP، پارامترهای پرس‌وجو، یک درخواست XML یا JSON یا هر متغیر جریان دیگری استخراج شود. برای مثال، شما آن را در یک هدر به نام weight تنظیم می‌کنید:

<MessageWeight ref="message_weight"/>

متغیرهای جریان

متغیرهای جریان از پیش تعریف شده زیر هنگام اجرای سیاست سهمیه بندی به طور خودکار پر می شوند. برای اطلاعات بیشتر در مورد متغیرهای جریان، به مرجع متغیرها مراجعه کنید.

مرجع خطا

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطا را که توسط Edge تنظیم می‌شوند، هنگامی که این خط‌مشی خطا را راه‌اندازی می‌کند، توضیح می‌دهد. این اطلاعات برای دانستن اینکه آیا در حال توسعه قوانین خطا برای رسیدگی به خطاها هستید، مهم است. برای کسب اطلاعات بیشتر، آنچه را که باید در مورد خطاهای خط مشی و مدیریت خطاها بدانید را ببینید.

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای سیاست رخ دهند.

خطاهای استقرار

متغیرهای خطا

این متغیرها زمانی تنظیم می شوند که این خط مشی خطایی را ایجاد کند. برای اطلاعات بیشتر، به آنچه باید در مورد خطاهای خط مشی بدانید مراجعه کنید.

نمونه پاسخ خطا

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

مثال قانون خطا

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

طرحواره‌ها

مباحث مرتبط

سیاست بازنشانی سهمیه

سیاست SpikeArrest

مقایسه سیاست‌های سهمیه‌بندی، توقف ناگهانی و محدودیت نرخ همزمان

شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات

چه

از سیاست سهمیه‌بندی برای پیکربندی تعداد پیام‌های درخواستی که یک پروکسی API در یک دوره زمانی، مانند دقیقه، ساعت، روز، هفته یا ماه، اجازه می‌دهد، استفاده کنید. می‌توانید سهمیه را برای همه برنامه‌هایی که به پروکسی API دسترسی دارند، یکسان تنظیم کنید، یا می‌توانید سهمیه را بر اساس موارد زیر تنظیم کنید:

• محصولی که حاوی پروکسی API است
• برنامه‌ای که API را درخواست می‌کند
• توسعه دهنده برنامه
• بسیاری از معیارهای دیگر

از سهمیه برای محافظت در برابر افزایش ناگهانی ترافیک استفاده نکنید. برای این کار، از سیاست Spike Arrest استفاده کنید. به سیاست Spike Arrest مراجعه کنید.

ویدیوها

این ویدیوها مدیریت سهمیه را با سیاست سهمیه‌بندی معرفی می‌کنند:

نمونه‌ها

این نمونه‌های کد سیاست، نحوه شروع و پایان دوره‌های سهمیه‌بندی را با موارد زیر نشان می‌دهند:

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

About the Quota policy

A Quota is an allotment of request messages that an API proxy can handle over a time period, such as minute, hour, day, week, or month. The policy maintains counters that tally the number of requests received by the API proxy. This capability enables API providers to enforce limits on the number of API calls made by apps over an interval of time. Using Quota policies you can, for example, limit apps to 1 request per minute, or to 10,000 requests per month.

For example, if a Quota is defined as 10,000 messages per month, rate-limiting begins after the 10,000th message. It doesn't matter whether 10,000 messages were counted on the first day or the last day of that period; no additional requests area allowed until the Quota counter automatically resets at the end of the specified time interval, or until the Quota is explicitly reset using Reset Quota policy .

A variation on Quota called SpikeArrest prevents traffic spikes (or bursts) that can be caused by a sudden increase in usage, buggy clients, or malicious attacks. For more information on SpikeArrest, see Spike Arrest policy .

Quotas apply to individual API proxies and are not distributed among API proxies. For example, if you have three API proxies in an API product, a single quota is not shared across all three even if all three use the same quota policy configuration.

Quota policy types

The Quota policy supports several different types of policies: default, calendar , flexi , and rollingwindow . Each type defines when the quota counter starts and when it resets, as shown in the following table:

For type="calendar" , you must specify the value of <StartTime> .

The table does not list the value for the rollingwindow type. Rolling window quotas work by setting the size of a quota "window", such as a one hour or one day window. When a new request comes in, the policy determines if the quota has been exceeded in the past "window" of time.

For example, you define a two hour window that allows 1000 requests. A new request comes in at 4:45 PM.The policy calculates the quota count for the past two hour window, meaning the number of requests since 2:45 PM. If the quota limit has not been exceeded in that two-hour window, then the request is allowed.

One minute later, at 4:46 PM, another request comes in. Now the policy calculates the quota count since 2:46 PM to determine if the limit has been exceeded.

For the rollingwindow type, the counter never resets, but is recalculated on each request.

Understanding quota counters

By default, a Quota policy maintains a single counter, regardless of how many times you reference it in an API proxy. The name of the quota counter is based on the name attribute of the policy.

For example, you create a Quota policy named MyQuotaPolicy with a limit of 5 requests and place it on multiple flows (Flow A, B, and C) in the API proxy. Even though it is used in multiple flows, it maintains a single counter that is updated by all instances of the policy:

• Flow A is executed -> MyQuotaPolicy is executed and its counter = 1
• Flow B is executed -> MyQuotaPolicy is executed and its counter = 2
• Flow A is executed -> MyQuotaPolicy is executed and its counter = 3
• Flow C is executed -> MyQuotaPolicy is executed and its counter = 4
• Flow A is executed -> MyQuotaPolicy is executed and its counter = 5

The next request to any of the three flows is rejected because the quota counter has reached its limit.

Using the same Quota policy in more than one place in an API proxy flow, which can unintentionally cause Quota to run out faster than you expected, is an anti-pattern described in The Book of Apigee Edge Antipatterns .

Alternatively, you can define multiple Quota policies in your API proxy and use a different policy in each flow. Each Quota policy maintains its own counter, based on the name attribute of the policy.

Or, use the <Class> or <Identifier> elements in the Quota policy to define multiple, unique counters in a single policy. By using these elements, a single policy can maintain different counters based on the app making the request, the app developer making the request, a client ID or other client identifier, and more. See the examples above for more information on using the <Class> or <Identifier> elements.

نمادگذاری زمان

All Quota times are set to the Coordinated Universal Time (UTC) time zone.

Quota time notation follows the international standard date notation defined in International Standard ISO 8601 .

Dates are defined as year, month, and day, in the following format: YYYY-MM-DD . For example, 2015-02-04 represents February 4, 2015.

Time of day is defined as hours, minutes, and seconds in the following format: hours:minutes:seconds . For example, 23:59:59 represents the time one second before midnight.

Note that two notations, 00:00:00 and 24:00:00 , are available to distinguish the two midnights that can be associated with one date. Therefore 2015-02-04 24:00:00 is the same date and time as 2015-02-05 00:00:00 . The latter is usually the preferred notation.

Getting quota settings from the API product configuration

You can set quota limits in API product configurations. Those limits don't automatically enforce quota. Instead, you can reference product quota settings in a quota policy. Here are some advantages of setting a quota on the product for quota policies to reference:

• Quota policies can use a uniform setting across all API proxies in the API product.
• You can make runtime changes to the quota setting on an API product, and quota policies that reference the value automatically have updated quota values.

For more information on using quota settings from an API product, see the "Dynamic Quota" example above. .

For info on configuring API products with quota limits, see Create API products .

مرجع عنصر

Following are elements and attributes you can configure on this policy. Note that some element combinations are mutually exclusive or not required. See the samples for specific usage. The verifyapikey.VerifyAPIKey.apiproduct.* variables below are available by default when a Verify API Key policy called "VerifyAPIKey" is used to check the app's API key in the request. The variable values come from the quota settings on the API product that the key is associated with, as described in Getting quota settings from the API product configuration .

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

<Quota> attributes

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

The following attributes are specific to this policy.

جدول زیر ویژگی هایی را توصیف می کند که برای همه عناصر اصلی خط مشی مشترک هستند:

عنصر <DisplayName>

علاوه بر ویژگی name برای برچسب‌گذاری خط‌مشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و به زبان طبیعی، از آن استفاده کنید.

<DisplayName>Policy Display Name</DisplayName>

<Allow> element

Specifies the count limit for the quota. If the counter for the policy reaches this limit value, subsequent calls are rejected until the counter resets.

Shown below are three ways to set the <Allow> element:

<Allow count="2000"/>

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

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

If you specify both count and countRef , then countRef gets the priority. If countRef does not resolve at runtime, then the value of count is used.

ویژگی‌ها

<Allow>/<Class> element

The <Class> element lets you conditionalize the value of the <Allow> element based on the value of a flow variable. For each different <Allow> child tag of <Class> , the policy maintains a different counter.

To use the <Class> element, specify a flow variable using the ref attribute to the <Class> tag. Edge then uses the value of the flow variable to select one of the <Allow> child tags to determine the allowed count of the policy. Edge matches the value of the flow variable to the class attribute of the <Allow> tag, as shown below:

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

In this example, the current quota counter is determined by the value of the time_variable query param passed with each request. That variable can have a value of peak_time or off_peak_time . If the query param contains an invalid value, the policy returns a quota violation error.

ویژگی‌ها

<Allow>/<Class>/<Allow> element

The <Allow> element specifies the limit for a quota counter defined by the <Class> element. For each different <Allow> child tag of <Class> , the policy maintains a different counter.

برای مثال:

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

In this example, the Quota policy maintains two quota counters named of peak_time and off_peak_time .

ویژگی‌ها

<Interval> element

Use to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the TimeUnit you specify (minute, hour, day, week, or month) to determine a time period during which Edge calculates quota use.

For example, an Interval of 24 with a TimeUnit of hour means that the quota will be calculated over the course of 24 hours.

<Interval ref="verifyapikey.VerifyAPIKey.apiproduct.developer.quota.interval">1</Interval>

ویژگی‌ها

<TimeUnit> element

Use to specify the unit of time applicable to the quota.

For example, an Interval of 24 with a TimeUnit of hour means that the quota will be calculated over the course of 24 hours.

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

ویژگی‌ها

<StartTime> element

When type is set to calendar, specifies the date and time when the quota counter will begin counting, regardless of whether any requests have been received from any apps.

برای مثال:

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

<Distributed> element

An installation of Edge can use one or more Message Processors to process requests. Set this element to true to specify that the policy should maintain a central counter and continuously synchronize it across all Message Processors. The message processors can be across availability zones and/or regions.

If you use the default value of false , then you might exceed your quota because the count for each Message Processor is not shared:

<Distributed>true</Distributed>

To guarantee that the counters are synchronized, and updated on every request, set <Distributed> and <Synchronous> to true:

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

<Synchronous> element

Set to true to update a distributed quota counter synchronously. This means that the update to the counter are made at the same time the quota is checked on a request to the API. Set to true if it is essential that you not allow any API calls over the quota.

Set to false to update the quota counter asynchronously. This means that it is possible that some API calls exceeding the quota will go through, depending on when the quota counter in the central repository is asynchronously updated. However, you will not face the potential performance impacts associated with synchronous updates.

The default asynchronous update interval is 10 seconds. Use the AsynchronousConfiguration element to configure this asynchronous behavior.

<Synchronous>false</Synchronous>

<AsynchronousConfiguration> element

Configures the synchronization interval amongst distributed quota counters when the policy configuration element <Synchronous> is either not present or present and set to false .

You can synchronize either after a time period or a message count, using either the SyncIntervalInSeconds or SyncMessageCount child elements. They are mutually exclusive. For example,

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

یا

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

<AsynchronousConfiguration>/<SyncIntervalInSeconds> element

Use this to override the default behavior in which asynchronous updates are performed after an interval of 10 seconds.

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

The sync interval must be >= 10 seconds as described in the Limits topic.

<AsynchronousConfiguration>/<SyncMessageCount> element

Specifies the number of requests across all Apigee message processors between quota updates.

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

This example specifies that the quota count is updated every 5 requests across each Apigee Edge message processor.

<Identifier> element

Use the <Identifier> element to configure the policy to create unique counters based on a flow variable.

If you don't use this element, the policy uses a single counter that is applied against the quota.

This element is also discussed in the following Apigee Community post: Quota identifier across different policies .

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

ویژگی‌ها

<MessageWeight> element

Use to specify the weight assigned to each message. Use message weight to increase impact of request messages that, for example, consume more computational resources than others.

For example, you want to count POST messages as being twice as "heavy" or expensive, as GET messages. Therefore, you set the MessageWeight to 2 for a POST and 1 for a GET. You can even set the MessageWeight to 0 so the request does not affect the counter. In this example, if the quota is 10 messages per minute and the MessageWeight for POST requests is 2 , then the quota will permits 5 POST requests in any 10 minute interval. Any additional request, POST or GET, before the counter resets are rejected.

A value representing MessageWeight must be specified by a flow variable, and can be extracted from HTTP headers, query parameters, an XML or JSON request payload, or any other flow variable. For example, you set it in a header named weight :

<MessageWeight ref="message_weight"/>

متغیرهای جریان

The following predefined Flow variables are automatically populated when a Quota policy executes. For more information about Flow variables, see Variables reference .

مرجع خطا

این بخش کدهای خطا و پیام‌های خطایی را که برگردانده می‌شوند و متغیرهای خطا را که توسط Edge تنظیم می‌شوند، هنگامی که این خط‌مشی خطا را راه‌اندازی می‌کند، توضیح می‌دهد. این اطلاعات برای دانستن اینکه آیا در حال توسعه قوانین خطا برای رسیدگی به خطاها هستید، مهم است. برای کسب اطلاعات بیشتر، آنچه را که باید در مورد خطاهای خط مشی و مدیریت خطاها بدانید را ببینید.

خطاهای زمان اجرا

این خطاها ممکن است هنگام اجرای سیاست رخ دهند.

خطاهای استقرار

متغیرهای خطا

این متغیرها زمانی تنظیم می شوند که این خط مشی خطایی را ایجاد کند. برای اطلاعات بیشتر، به آنچه باید در مورد خطاهای خط مشی بدانید مراجعه کنید.

نمونه پاسخ خطا

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

مثال قانون خطا

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

طرحواره‌ها

مباحث مرتبط

ResetQuota policy

SpikeArrest policy

Comparing Quota, Spike Arrest, and Concurrent Rate Limit Policies