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>

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.

Default Value n/a
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used
Type String
Parent Element <PolicyElement>
Child Elements None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

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

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

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

エラー リファレンス

このセクションでは、このポリシーがトリガーとなってエラーが発生したときに返される障害コードとエラー メッセージ、そして Edge によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成する上で重要な情報です。詳細については、ポリシーエラーについて知っておくべきこと障害の処理をご覧ください。

ランタイム エラー

ポリシーの実行時に、以下のエラーが発生することがあります。

障害コード HTTP ステータス 原因 修正
policies.ratelimit.FailedToResolveSpikeArrestRate 500 このエラーは、<Rate> 要素に含まれるレート設定を格納する変数への参照を、Spike Arrest ポリシー内で指定されている値に解決できない場合に発生します。この要素は必須であり、{int}pm または {int}ps の形式でのスパイク停止率の指定に使用されます。
policies.ratelimit.InvalidMessageWeight 500 このエラーは、フロー変数によって <MessageWeight> 要素に指定された値が無効である(整数以外の値)場合に発生します。
policies.ratelimit.SpikeArrestViolation 500 レート制限を超えています。

デプロイエラー

このポリシーを含むプロキシをデプロイすると、次のエラーが発生することがあります。

エラー名 原因 修正
InvalidAllowedRate Spike Arrest ポリシーの <Rate> 要素で指定されたスパイク停止率が整数でない場合、またはレートに接尾辞 ps または pm がない場合、その API プロキシのデプロイが失敗します。

障害変数

以下の変数は、ランタイム エラーが発生したときに設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数 説明
fault.name="fault_name" fault_name は、上記のランタイム エラー表に記載されている障害の名前です。障害コードの最後の部分が障害名になります。 fault.name Matches "SpikeArrestViolation"
ratelimit.policy_name.failed policy_name は、障害をスローしたポリシーにユーザーが指定した名前です。 ratelimit.SA-SpikeArrestPolicy.failed = true

エラー レスポンスの例

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

障害ルールの例

    <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 から入手できます。

関連トピック