SpikeArrest ポリシー

Edge UI からの Spike Arrest アイコン

Spike Arrest ポリシーは、<Rate> 要素を使用してトラフィックの急増から保護します。この要素は、API プロキシで処理され、バックエンドに送信されるリクエスト数を調整します。これにより、パフォーマンスの低下やダウンタイムの発生を防ぎます。

<SpikeArrest> 要素

Spike Arrest ポリシーを定義します。

デフォルト値 下記の [デフォルト ポリシー] タブをご覧ください。
要否 省略可
複合オブジェクト
親要素 なし
子要素 <Identifier>
<MessageWeight>
<Rate>(必須)
<UseEffectiveCount>

構文

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

デフォルト ポリシー

次の例は、Edge UI でフローに Spike Arrest ポリシーを追加したときのデフォルト設定を示しています。

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

<UseEffectiveCount> 要素はデフォルト ポリシーでは定義されていません。これを使用するには、手動で追加する必要があります。

この要素には、すべてのポリシーに共通の次の属性があります。

属性 デフォルト 要否 説明
name なし 必須

ポリシーの内部名です。name 属性の値には、文字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。255 文字を超える値を指定することはできません。

必要に応じて <DisplayName> 要素を使用して、管理 UI プロキシ エディタのポリシーに別の自然言語名でラベルを付けます。

continueOnError false 省略可 ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される動作です。ポリシーが失敗してもフロー実行を続行するには、true に設定します。
enabled true 省略可 ポリシーを適用するには「true」に設定します。ポリシーを「turn off」するには、「false」に設定します。false に設定すると、ポリシーがフローに接続されている場合でも適用されません。
async   false 非推奨 この属性は非推奨となりました。

次の例はそれぞれ、Spike Arrest ポリシーの使用方法を示しています。

例 1

次の例では、レートを 1 秒あたり 5 に設定します。

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

このポリシーでは、200 ミリ秒につき 1 件のリクエスト(1000÷5)が許可されるように、レートが平滑化されます。

例 2

次の例では、レートが 1 分につき 12 に設定されます。

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
</SpikeArrest>

この例のポリシーでは、5 ごとに 1 件のリクエスト(60÷12)が許可されるように、レートが平滑化されます。

例 3

次の例では、1 分あたりのリクエスト数が 12 件に制限されます(5 秒ごとに 1 件のリクエストが許可されます。つまり 60÷12)。

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

また、<MessageWeight> 要素には、特定のアプリやクライアントのメッセージの重みを調整するカスタム値(weight ヘッダー)を指定できます。これにより、<Identifier> 要素で識別されるエンティティのスロットリングをさらに制御できます。

例 4

次の例では、request.header.runtime_rate フロー変数として渡されるリクエストを介して設定されたランタイム値を探すように Spike Arrest に指示します。

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

フロー変数の値は、int pm または int ps の形式にする必要があります。

この例を試すには、次のようなリクエストを行います。

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

子要素のリファレンス

このセクションでは、<SpikeArrest> の子要素について説明します。

<DisplayName>

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

デフォルト値 該当なし
要否 省略可。<DisplayName> 要素を省略した場合、ポリシーの name 属性の値が使用されます
文字列
親要素 <PolicyElement>
子要素 なし

<DisplayName> 要素の構文は次のとおりです。

構文

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

    <AssignMessage>
      <DisplayName>My Validation Policy</DisplayName>
    </AssignMessage>
    

<DisplayName> 要素に属性や子要素はありません。

<Identifier>

Spike Arrest ポリシーをクライアントに基づいて適用できるように、リクエストをグループ化する方法を選択できます。たとえば、デベロッパー ID ごとにリクエストをグループ化できます。この場合、プロキシへのすべてのリクエストではなく、各デベロッパーのリクエストが各自の Spike Arrest レートにカウントされます。

<MessageWeight> 要素と組み合わせて使用すると、リクエストのスロットリングをより細かく制御できます。

<Identifier> 要素を空のままにすると、その API プロキシに対するすべてのリクエストに 1 つのレート制限が適用されます。

デフォルト値 なし
要否 省略可
文字列
親要素 <SpikeArrest>
子要素 なし

構文

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

例 1

次の例では、デベロッパー ID ごとに Spike Arrest ポリシーが適用されます。

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

次の表に、<Identifier> 要素の属性を示します。

属性 説明 デフォルト 要否
ref Spike Arrest グループの受信リクエストごとに変数を識別します。任意のフロー変数を使用して、VerifyAPIKey ポリシーで使用できる一意のクライアントを示すことが可能です。また、JavaScript ポリシーまたは AssignMessage ポリシーを使用して、カスタム変数を設定することもできます。 なし 必須

この要素については、Apigee コミュニティの投稿 http://community.apigee.com/questions/2807/how-does-the-edge-quota-policy-work-when-no-identi.html にも説明があります。

<MessageWeight>

メッセージに定義したウェイトを指定します。Spike Arrest のレートを計算するときに、メッセージ ウェイトにより単一リクエストの影響が変更されます。メッセージ ウェイトは、HTTP ヘッダー、クエリ パラメータ、フォーム パラメータ、メッセージ本文のコンテンツなど、任意のフロー関数にできます。また、JavaScript ポリシーまたは AssignMessage ポリシーを使用して、カスタム変数を使用することもできます。

<Identifier> と組み合わせて使用し、特定のクライアントやアプリによるリクエストをさらに絞り込みます。

たとえば、Spike Arrest <Rate>10pm で、重みが 2 のリクエストをアプリが送信した場合、各リクエストは 2 とカウントされるため、そのクライアントからの送信が許可されるメッセージは 1 分あたり 5 件までです。

デフォルト値 なし
要否 省略可
整数
親要素 <SpikeArrest>
子要素 なし

構文

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

例 1

次の例では、1 分あたりのリクエスト数が 12 件に制限されます(5 秒ごとに 1 件のリクエストが許可されます。つまり 60÷12)。

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

この例では、<MessageWeight> は特定のクライアントのメッセージ ウェイトを調整するカスタム値(リクエストの weight ヘッダー)を受け入れます。これにより、<Identifier> 要素で識別されるエンティティのスロットリングをさらに制御できます。

次の表に、<MessageWeight> 要素の属性を示します。

属性 説明 要否 デフォルト
ref 特定のクライアントのメッセージ ウェイトが含まれるフロー変数を特定します。これは、HTTP クエリ パラメータ、ヘッダー、メッセージ本文のコンテンツなど、任意のフロー関数にできます。詳細は、フロー変数のリファレンスをご覧ください。また、JavaScript ポリシーまたは AssignMessage ポリシーを使用して、カスタム変数を設定することもできます。 必須 なし

<Rate>

1 分間隔または 1 秒間隔で許可するリクエスト数を指定することによって、トラフィックの急増(またはバースト)を制限するレートを指定します。また、この要素を <Identifier><MessageWeight> と組み合わせて使用すると、クライアントからの値を受け入れることにより、ランタイムにおけるトラフィックの絞り込みがスムーズになります。

デフォルト値 なし
要否 必須
整数
親要素 <SpikeArrest>
子要素 なし

構文

次のいずれかの方法でレートを指定できます。

  • <Rate> 要素の本体に指定する静的レート
  • クライアントが渡すことが可能な変数値。ref 属性を使用してフロー変数の名前を特定する
<SpikeArrest
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
  <Rate ref="flow_variable">rate[pm|ps]</Rate>
</SpikeArrest>

有効なレート値(変数値で定義されるか、要素の本文で定義される)は、次の形式に従う必要があります。

  • intps(1 秒あたりのリクエスト数、ミリ秒単位の間隔に平滑化)
  • intpm(1 分あたりのリクエスト数、秒単位の間隔に平滑化)

int は 0 以外の正の整数でなければなりません。

例 1

次の例では、レートを 1 秒あたり 5 件のリクエストに設定します。

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

このポリシーでは、200 ミリ秒につき 1 件のリクエスト(1000÷5)が許可されるように、レートが平滑化されます。

例 2

次の例では、レートが 1 分につき 12 件のリクエストに設定されます。

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
</SpikeArrest>

この例のポリシーでは、5 秒ごとに 1 件のリクエスト(60÷12)が許可されるように、レートが平滑化されます。

次の表に、<Rate> 要素の属性を示します。

属性 説明 要否 デフォルト
ref レートを指定するフロー変数が特定されます。HTTP クエリ パラメータ、ヘッダー、メッセージ本文のコンテンツなどの任意のフロー関数、KVM などの値に特定されます。詳しくは、フロー変数リファレンスをご覧ください。

また、JavaScript ポリシーまたは AssignMessage ポリシーを使用して、カスタム変数を使用することもできます。

ref とこの要素の本文の両方を定義する場合は、ref の値が適用され、フロー変数がリクエストで設定されている場合にその値が優先されます。リクエストで ref に変数が設定されていない場合は、その逆になります)。

例:


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

この例では、クライアントが「custom_rate」ヘッダーを渡さない場合、すべてのクライアントに対して API プロキシのレートが、1 分あたり 1 リクエストになります。クライアントが「custom_rate」ヘッダーを渡す場合、「custom_rate」ヘッダーなしのリクエストが送信されるまで、プロキシのすべてのクライアントに対してレートの制限が 1 秒あたり 10 リクエストになります。

<Identifier> を使用してリクエストをグループ化し、さまざまなタイプのクライアントに対してカスタムレートを適用できます。

ref の値は設定するものの、<Rate> 要素の本文でレートを設定せず、クライアントが値を渡さない場合、Spike Arrest ポリシーでエラーがスローされます。

省略可 なし

<UseEffectiveCount>

自動スケーリング グループを使用している場合に、Message Processor(MP)間で Spike Arrest のカウントを配布します。

構文

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

例 1

次の例では、<UseEffectiveCount> を true に設定しています。

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

<UseEffectiveCount> 要素は省略可能です。Spike Arrest ポリシーから要素が省略されている場合、デフォルト値は false です。

デフォルト値 False
要否 省略可
ブール値
親要素 <SpikeArrest>
子要素 なし

次の表に、<UseEffectiveCount> 要素の属性を示します。

属性 説明 デフォルト 要否
ref <UseEffectiveCount> の値が含まれる変数を特定します。これは、HTTP クエリ パラメータ、ヘッダー、メッセージ本文のコンテンツなど、任意のフロー関数にできます。詳細は、フロー変数のリファレンスをご覧ください。また、JavaScript ポリシーまたは AssignMessage ポリシーを使用して、カスタム変数を設定することもできます。 なし 省略可

<UseEffectiveCount> の影響は、以下の値に応じて異なります。

  • true: MP の急増レート制限は、<Rate> を MP の現在の数で除算した数です。合計の制限値は <Rate> の値になります。MP の数が急激に増加または減少した場合、個々の急増レート制限が増加または減少しますが、合計の制限値に変化はありません。
  • false(または、これがデフォルト値の場合は省略される): 各 MP の急増レート制限は、単にその <Rate> の値です。合計の制限値は、すべての MP のレートの合計になります。MP の数が増加または減少した場合、個々の急増レート制限に変化はありませんが、合計の制限値は増加または減少します。

次の表に、MP ごとに有効なレート制限と <UseEffectiveCount> の関係を示します。

<UseEffectiveCount> の値
false false false true true true
MP の数 8 4 2 8 4 2
<Rate> の値 10 10 10 40 40 40
1 つの MP あたりの有効なレート 10 10 10 5 10 20
合計の制限値 80 40 20 40* 40* 40*
* <Rate> と同じ。

この例では、MP の数が 4 から 2 に減少し、<UseEffectiveCount>false である場合、MP ごとの有効なレートに変化はありません(10 のままです)。<UseEffectiveCount>true である場合、MP の数が 4 から 2 に減少すると、MP ごとに有効なレートが 10 から 20 に変わります。

フロー変数

Spike Arrest ポリシーが実行されると、次のフロー変数が設定されます。

変数 権限 説明
ratelimit.policy_name.failed ブール値 読み取り専用 ポリシーが失敗したかどうかを表します(true または false)。

詳細は、フロー変数のリファレンスをご覧ください。

エラー リファレンス

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.

Fault code HTTP status Cause Fix
policies.ratelimit.FailedToResolveSpikeArrestRate 500 This error occurs if the reference to the variable containing the rate setting within the <Rate> element cannot be resolved to a value within the Spike Arrest policy. This element is mandatory and used to specify the spike arrest rate in the form of intpm or intps.
policies.ratelimit.InvalidMessageWeight 500 This error occurs if the value specified for the <MessageWeight> element through a flow variable is invalid (a non-integer value).
policies.ratelimit.SpikeArrestViolation 429

The rate limit was exceeded.

Deployment errors

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

Error name Cause Fix
InvalidAllowedRate If the spike arrest rate specified in the <Rate> element of the Spike Arrest Policy is not an integer or if the rate does not have ps or pm as a suffix, then the deployment of the API proxy fails.

Fault variables

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

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "SpikeArrestViolation"
ratelimit.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. ratelimit.SA-SpikeArrestPolicy.failed = true

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>

Quota または Spike Arrest ポリシーで設定されたレート制限を超えた場合の現在の HTTP ステータス コードは 429(リクエスト数が多すぎます)です。HTTP ステータス コードを 500(内部サーバーエラー)に変更するには、組織プロパティ更新 API を使用して 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 から入手できます。

関連トピック