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

フロー変数の値は intpm または intps の形式にする必要があります。

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

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 のリクエストを送信する場合、このアプリから 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 Boolean 読み取り専用 ポリシーが失敗したかどうかを表します(true または false)。

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

エラー リファレンス

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

ランタイム エラー

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

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

デプロイエラー

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

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

障害変数

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

変数 説明
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>
    

レート制限値を超える現在の HTTP ステータス コードは 429 です。ステータス コードを別の値に変更するには、組織にプロパティを設定する必要があります。Cloud をご利用のお客様は、Apigee のサポートにお問い合わせください。

スキーマ

各ポリシータイプは XML スキーマ(.xsd)によって定義されます。GitHub に参照用のポリシー スキーマが用意されています。

関連トピック