خط‌مشی SpikeArrest

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

خط‌مشی «مهار جهش» با عنصر <Rate> دربرابر جهش‌های ترافیک محافظت می‌کند. این عنصر تعداد درخواست‌های پردازش‌شده توسط پراکسی API و ارسال‌شده به زیرینه را محدود می‌کند و از تأخیر در عملکرد و زمان خرابی محافظت می‌کند.

‫<SpikeArrest> عنصر

خط‌مشی «مهار جهش» را تعریف می‌کند.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <DisplayName>display_name</DisplayName>
  <Properties/>
  <Identifier ref="flow_variable"/>
  <MessageWeight ref="flow_variable"/>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest async="false" continueOnError="false" enabled="true" name="Spike-Arrest-1">
  <DisplayName>Spike Arrest-1</DisplayName>
  <Properties/>
  <Identifier ref="request.header.some-header-name"/>
  <MessageWeight ref="request.header.weight"/>
  <Rate>30ps</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

This element has the following attributes that are common to all policies:

مثال‌ها

مثال‌های زیر برخی‌از روش‌هایی را نشان می‌دهد که می‌توانید از خط‌مشی «مهار جهش» استفاده کنید:

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
</SpikeArrest>

<SpikeArrest async="false" continueOnError="false" enabled="true" name="SpikeArreast">
  <DisplayName>SpikeArreast</DisplayName>
  <Rate>300pm</Rate>
</SpikeArrest>

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
</SpikeArrest>

<SpikeArrest name="Spike-Arrest-1">
  <Rate ref="request.header.runtime_rate" />
</SpikeArrest>

curl http://myorg-myenv.apigee.net/price -H 'runtime_rate:30ps'

مرجع عنصر فرزند

این بخش عناصر فرزند <SpikeArrest> را شرح می‌دهد.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

The <DisplayName> element uses the following syntax:

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

The <DisplayName> element has no attributes or child elements.

<Identifier>

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

برای کنترل دقیق‌تر محدودسازی درخواست، از آن همراه با عنصر <MessageWeight> استفاده کنید.

اگر عنصر <Identifier> را خالی بگذارید، یک حد نرخ برای همه درخواست‌ها در آن پراکسی API اعمال می‌شود.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Identifier ref="flow_variable"/>
</SpikeArrest>
        

<SpikeArrest name="Spike-Arrest-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
</SpikeArrest>

جدول زیر مشخصه‌های <Identifier> را شرح می‌دهد:

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

<MessageWeight>

وزن تعریف‌شده برای هر پیام را مشخص می‌کند. وزن پیام تأثیر یک درخواست واحد بر محاسبه نرخ «مهار جهش» را تغییر می‌دهد. وزن پیام می‌تواند هر متغیر جریانی باشد، مثل سرایند HTTP، پارامتر پُرسمان، پارامتر فرم، یا محتوای بدنه پیام. همچنین می‌توانید بااستفاده از خط‌مشی جاوا اسکریپت یا خط‌مشی AssignMessage از متغیرهای سفارشی استفاده کنید.

برای محدود کردن بیشتر درخواست‌ها براساس کارخواه‌ها یا برنامه‌های خاص، همراه با <Identifier> استفاده کنید.

برای مثال، اگر «مهار کردن جهش» <Rate> روی 10pm تنظیم شده باشد و برنامه‌ای درخواست‌هایی با وزن 2 ارسال کند، در این‌صورت فقط پنج پیام در دقیقه از آن کارخواه مجاز است زیرا هر درخواست به‌عنوان ۲ محاسبه می‌شود.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <MessageWeight ref="flow_variable"/>
</SpikeArrest>

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <MessageWeight ref="request.header.weight" />
</SpikeArrest>

جدول زیر مشخصه‌های <MessageWeight> را شرح می‌دهد:

<Rate>

نرخی را که براساس آن باید جهش‌های ترافیک (یا انفجارها) را محدود کرد مشخص می‌کند. این کار با تنظیم تعداد درخواست‌هایی که در فواصل زمانی یک دقیقه یا یک ثانیه مجاز هستند انجام می‌شود. همچنین می‌توانید از این عنصر در ترکیب با <Identifier> و <MessageWeight> برای کنترل روان ترافیک در زمان اجرا با پذیرفتن مقادیر از مشتری استفاده کنید.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
</SpikeArrest>

<SpikeArrest name="Spike-Arrest-1">
  <Rate>5ps</Rate>
</SpikeArrest>

<SpikeArrest async="false" continueOnError="false" enabled="true" name="SpikeArreast">
  <DisplayName>SpikeArreast</DisplayName>
  <Rate>300pm</Rate>
</SpikeArrest>

جدول زیر مشخصه‌های <Rate> را شرح می‌دهد:

<Rate ref="request.header.custom_rate">1pm</Rate>

<UseEffectiveCount>

وقتی از گروه‌های مقیاس‌بندی خودکار استفاده می‌کنید، تعداد «مهار سنبله» را در «پردازنده‌های پیام» (MPs) توزیع می‌کند.

<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
</SpikeArrest>

<SpikeArrest name='Spike-Arrest-1'>
  <Rate>40ps</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</SpikeArrest>

عنصر <UseEffectiveCount> اختیاری است. وقتی عنصر از خط‌مشی «مهار جهش» شما حذف می‌شود، مقدار پیش‌فرض false است.

جدول زیر مشخصه‌های عنصر <UseEffectiveCount> را شرح می‌دهد:

تأثیر <UseEffectiveCount> به مقدار آن بستگی دارد:

• true: حد نرخ جهش MP عبارت است از <Rate> تقسیم بر تعداد فعلی MP در همان گروه. حد تجمیعی مقدار <Rate> است. وقتی «اعضای گروه» به‌صورت پویا اضافه (یا حذف) می‌شوند، محدودیت‌های نرخ جهش فردی آن‌ها افزایش (یا کاهش) می‌یابد، اما محدودیت کلی ثابت می‌ماند.
• ‫false: حد نرخ جهش هر MP به‌سادگی مقدار <Rate> آن است. حد مجموع عبارت است از مجموع نرخ‌های همه نمایندگان مجلس. وقتی «نقاط پایانی پیام» اضافه (یا برداشته) می‌شوند، حدود نرخ جهشی فردی آن‌ها بدون تغییر می‌ماند، اما حد تجمیعی افزایش (یا کاهش) می‌یابد.

خط‌مشی SpikeArrest از الگوریتم «توکن باکت» استفاده می‌کند که با تقسیم کردن حد نرخ مشخص‌شده به بازه‌های زمانی کوچک‌تر، جهش‌های ترافیک را هموار می‌کند. یکی از معایب این رویکرد این است که ممکن است چندین درخواست قانونی که در یک بازه زمانی کوتاه ارسال می‌شوند، رد شوند.

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

• نرخ‌های در دقیقه به درخواست‌های کامل مجاز در فواصل ثانیه تبدیل می‌شوند.
  

  برای مثال، ۳۰ درخواست در دقیقه به این صورت هموار می‌شود:
  ۶۰ ثانیه (۱ دقیقه) / ۳۰ درخواست در دقیقه = فواصل ۲ ثانیه‌ای، یا ۱ درخواست مجاز در هر ۲ ثانیه. درخواست دوم در عرض ۲ ثانیه انجام نخواهد شد. همچنین، درخواست سی‌ویکم در یک دقیقه ناموفق خواهد بود.

• نرخ‌های در ثانیه به درخواست‌های کامل مجاز در فواصل زمانی میلی‌ثانیه تبدیل می‌شوند.

  برای مثال، ۱۰ps به‌این‌صورت هموار می‌شود:
  ۱۰۰۰ میلی‌ثانیه (۱ ثانیه) / ۱۰ps = فاصله‌های ۱۰۰ میلی‌ثانیه‌ای، یا ۱ درخواست مجاز در هر ۱۰۰ میلی‌ثانیه. درخواست دوم در فاصله ۱۰۰ میلی‌ثانیه انجام نخواهد شد. همچنین، درخواست یازدهم در یک ثانیه انجام نخواهد شد.

جدول زیر تأثیر <UseEffectiveCount> را بر حد نرخ مؤثر هر MP نشان می‌دهد:

در این مثال، توجه کنید که وقتی تعداد «واحد قیمت» از ۴ به ۲ کاهش می‌یابد، و <UseEffectiveCount> برابر با false است، نرخ مؤثر به‌ازای هر «واحد قیمت» یکسان می‌ماند (در ۱۰). اما وقتی <UseEffectiveCount> برابر با true باشد، نرخ مؤثر به‌ازای هر مگاپیکسل وقتی تعداد مگاپیکسل‌ها از ۴ به ۲ کاهش می‌یابد از ۱۰ به ۲۰ می‌رسد.

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

وقتی خط‌مشی «مهار جهش» اجرا می‌شود، متغیر جریان زیر تکمیل می‌شود:

برای اطلاعات بیشتر، به مرجع متغیرهای جریان مراجعه کنید.

مرجع خطا

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

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

Shown below is an example error response:

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.ratelimit.SpikeArrestViolation"
      },
      "faultstring":"Spike arrest violation. Allowed rate : 10ps"
   }
}

Example fault rule

Shown below is an example fault rule to handle a SpikeArrestViolation fault:

<FaultRules>
    <FaultRule name="Spike Arrest Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "SpikeArrestViolation") </Condition>
        </Step>
        <Condition>ratelimit.Spike-Arrest-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

کد وضعیت HTTP فعلی برای فراتر رفتن از حد نرخ تعیین‌شده توسط خط‌مشی «سهمیه» یا «مهار جهش» 429 (درخواست‌های بسیار زیاد) است. برای تغییر کد وضعیت HTTP به 500 (خطای سرور داخلی)، دارایی features.isHTTPStatusTooManyRequestEnabled را بااستفاده از میانای برنامه‌سازی کاربردی به‌روزرسانی دارایی‌های سازمان روی false تنظیم کنید.

برای مثال:

curl -u email:password -X POST -H "Content-type:application/xml" http://api.enterprise.apigee.com/v1/organizations/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isHTTPStatusTooManyRequestEnabled">true</Property>
        . . .
    </Properties>
</Organization>"

طرح‌واره‌ها

هر نوع خط‌مشی با یک طرحواره XML (.xsd) تعریف می‌شود. برای مرجع، طرحواره‌های خط‌مشی در GitHub دردسترس است.

موضوعات مرتبط

• خط‌مشی سهمیه: خط‌مشی سهمیه، برای محدود کردن ترافیک در مشتریان فردی
• محدود کردن نرخ برای نمای کلی محدود کردن نرخ
• مقایسه خط‌مشی‌های سهمیه و «توقف ناگهانی»
• نمونه‌های کاری از پراکسی‌های API