SpikeArrest ポリシー

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示します。

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

このポリシーは、標準ポリシーであり、任意の環境タイプにデプロイできます。ポリシータイプと各環境タイプで使用可能かどうかは、ポリシータイプをご覧ください。

SpikeArrest と Quota の違い

Quota ポリシーでは、1 時間、1 日、1 週間または 1 か月にクライアント アプリが API に送信できるリクエスト メッセージの数を構成します。Quota ポリシーは、クライアント アプリに使用制限を適用するために、受信リクエストを集計する分散型カウンタを保持します。

Quota は、運用上のトラフィックを管理するためではなく、デベロッパーやパートナーとの業務契約または SLA を遵守するために使用します。API トラフィックの急増を防ぐには SpikeArrest を使用します。Quota ポリシーと SpikeArrest ポリシーの比較をご覧ください。

動画

この動画では、このポリシーのユースケースについて説明しています。

必要な理由

Quota ポリシーとの比較

<SpikeArrest> 要素

SpikeArrest ポリシーを定義します。

デフォルト値	下の「デフォルト ポリシー」タブをご覧ください。
必須かどうか	省略可
型	複合オブジェクト
親要素	なし
子要素	<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>

デフォルト ポリシー

次の例は、UI のフローに 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>false</UseEffectiveCount>
</SpikeArrest>

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

Attribute	Default	Required?	Description
name	N/A	Required	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError	false	Optional	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
enabled	true	Optional	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async	false	Deprecated	This attribute is deprecated.

例

次の例は、SpikeArrest ポリシーの使用方法を示しています。

例 1

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

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

このサンプル ポリシーでは、1 秒あたり最大 5 件のリクエストが許可されます。平準化により、200 ミリ秒（1000÷5）ごとに最大 1 件のリクエストが許可されます。

例 2

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

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

このサンプル ポリシーでは、5 秒（60÷12）ごとに 1 件のリクエストの割合で、1 分あたり最大 12 件のリクエストが許可されます。5 秒間隔で複数のリクエストがある場合で、リクエスト数が 1 分あたり 12 回の制限を超えていなければ、リクエストが許可されます（平滑化なし）。

例 3

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

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

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

例 4

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

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

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

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

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

ヒント: API プロダクトでカスタム変数を使用して SpikeArrest レートを設定する方法については、API プロダクトを使用して Spike Arrest の制限を設定する方法をご覧ください。

子要素のリファレンス

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

<DisplayName>

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

<DisplayName> 要素はすべてのポリシーに共通です。

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

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

構文

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

例

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

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

<Identifier>

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

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

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

デフォルト値	なし
必須かどうか	省略可
型	文字列
親要素	<SpikeArrest>
子要素	なし

構文

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

例 1

次の例では、デベロッパー ID ごとに SpikeArrest ポリシーを適用します。

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

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

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

この要素については、Apigee コミュニティの投稿でも説明されています。

<MessageWeight>

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

<Identifier> と一緒に使用して、特定のクライアントまたはアプリによってリクエストを調整します。

たとえば、SpikeArrest <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 秒（60÷12）ごとに 1 件のリクエストが許可されます。

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

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

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

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

<Rate>

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

注: 指定できる最大レート制限については、[制限] ページの [SpikeArrest] セクションをご覧ください。

デフォルト値	なし
必須かどうか	必須
型	整数
親要素	<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>
  <UseEffectiveCount>false</UseEffectiveCount>
</SpikeArrest>

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

例 2

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

<SpikeArrest name="Spike-Arrest-1">
  <Rate>12pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</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> 要素の本文でレートを設定せず、クライアントが値を渡さない場合、SpikeArrest ポリシーでエラーがスローされます。	省略可	なし

<UseEffectiveCount>

この要素を使用すると、以下で説明するように、値を true または false に設定することで、SpikeArrest アルゴリズムを選択できます。

true

true に設定すると、SpikeArrest がリージョンに分散されます。つまり、リクエスト数はリージョン内の Message Processor（MP）間で同期されます。また、「スライディング ウィンドウ」のレート制限アルゴリズムも使用されます。このアルゴリズムは、一貫したレート制限動作を実現しますが、バックエンドに送信できる受信リクエスト数を「平準化」しません。短期間に大量のリクエストが送信される場合、<Rate> 要素で設定された構成済みレート制限を超えない限り、リクエストは許可されます。次に例を示します。

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

false（デフォルト）

false（デフォルト）に設定すると、SpikeArrest ポリシーでは「トークン バケット」アルゴリズムが使用されます。このアルゴリズムは、指定したレート制限を短い間隔に分割することで、トラフィックの急増を緩和しますこのアプローチの欠点は、短い間隔で受信された正当なリクエストが拒否される可能性があることです。

たとえば、レートに 30 pm（1 分あたり 30 件のリクエスト）を入力したとします。テストでは、1 分以内の範囲であれば、30 件のリクエストを 1 秒間で送信してもよいと思われるかもしれません。しかし、これはポリシーにより適用される設定とは異なります。1 秒の間に 30 件のリクエストというのは、環境によっては小規模な急増と見なされることがあります。

• 1 分あたりのレートは、秒間隔で許可される完全なリクエスト数に平滑化されます。
  

  たとえば、30pm は次のように平滑化されます。
  60 秒（1 分）÷ 30pm = 2 秒間隔、または 2 秒ごとに 1 回のリクエストが許可されます。2 秒以内の 2 つ目のリクエストは失敗します。また、1 分以内の 31 件目のリクエストも失敗します。

• 1 秒あたりのレートは、ミリ秒間隔で許可される完全なリクエスト数に平滑化されます。

  たとえば、10ps は次のように平滑化されます。
  1000 ミリ秒（1 秒）÷ 10ps = 100 ミリ秒間隔、または 100 ミリ秒ごとに 1 回のリクエスト。100 ミリ秒以内の 2 つ目のリクエストは失敗します。また、1 秒以内の 11 件目のリクエストも失敗します。

注: レートの平滑化では、リクエスト数は常に 1 以上の整数になります。平滑化では、部分的なリクエストは計算されません。

デフォルト値	いいえ
必須かどうか	省略可
型	ブール値
親要素	<SpikeArrest>
子要素	なし

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

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

フロー変数

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

変数	型	権限	説明
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 Apigee 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.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

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 SpikeArrest 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 is exceeded.

Deployment errors

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

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidAllowedRate	If the spike arrest rate specified in the <Rate> element of the SpikeArrest 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:

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "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 ポリシーまたは SpikeArrest ポリシーで設定されたレート制限を超えると、現在の HTTP ステータス コードは 429（リクエストが多すぎます）になります。HTTP ステータス コードを 500（内部サーバーエラー）に変更するには、Update organization properties API を使用して features.isHTTPStatusTooManyRequestEnabled プロパティを false に設定します。

注意: プロパティを更新するときは、既存のプロパティが変更されていない場合でも、すべて API に渡す必要があります。Update organization properties API の呼び出しペイロードでプロパティを省略すると、それらのプロパティは削除されます。環境の現在のプロパティのリストを取得するには、Get Organization API を使用します。

プロパティを設定しようとしても、更新されたプロパティ値がレスポンス ペイロードで返されない場合は、sysadmin ロールを持つユーザーがプロパティを設定する必要があります。sysadmin ロールを必要とするプロパティ値を変更する場合は、Apigee サポートにお問い合わせください。

例:

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

スキーマ

各ポリシータイプは XML スキーマ（.xsd）によって定義されます。参照用のポリシー スキーマは GitHub から入手できます。

関連トピック

• Quota ポリシー: 個々のクライアントのトラフィックを制限する Quota ポリシー
• レート制限: レート制限の概要
• Quota ポリシーと SpikeArrest ポリシーの比較