プラグインを使用する

Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントをご覧ください。

Edge Microgateway v 3.3.x

視聴者

このトピックは、Microgateway とともにインストールされた既存のプラグインを使用する Edge Microgateway オペレータを対象としています。また、急増停止と割り当てプラグインについて詳しく説明します（どちらもインストールに含まれています）。新しいプラグインを開発するデベロッパーは、カスタム プラグインを開発するをご覧ください。

Edge Microgateway プラグインとは

プラグインは、Edge Microgateway に機能を追加する Node.js モジュールです。プラグイン モジュールは一貫したパターンに従い、Edge Microgateway が認識している場所に保存されるため、Microgateway がこれらを自動的に検出して読み込むことができます。Edge Microgateway には、既存のプラグインがいくつか含まれています。カスタム プラグインを開発するで説明されているように、カスタム プラグインを作成することもできます。

Edge Microgateway にバンドルされている既存のプラグイン

Edge Microgateway には、インストール時にいくつかのプラグインが用意されています。 よく使用されるプラグインを次の表に示します。

Plugin（プラグイン） デフォルトで有効 説明
アナリティクス ○ Edge Microgateway から Apigee Edge に分析データを送信します。
oauth ○ OAuth Microgateway と API キーの検証を Edge Microgateway に追加しました。Edge Microgateway の設定と構成をご覧ください。
割り当て × Edge Microgateway へのリクエストに割り当てを適用します。Apigee Edge を使用して割り当てを保存し、管理します。割り当てプラグインの使用をご覧ください。
スパイクレスト × トラフィックの急増や DoS 攻撃から保護します。spike arrest プラグインの使用をご覧ください。
header-uppercase × デベロッパーがカスタム プラグインを記述するためのガイドとして、コメントされたサンプル プロキシです。 Edge Microgateway サンプル プラグインをご覧ください。
累積リクエスト × リクエスト データを単一のオブジェクトに蓄積してから、プラグイン チェーンの次のハンドラにデータを渡します。単一の累積されたリクエスト コンテンツ オブジェクトを操作する必要がある変換プラグインを作成する場合に便利です。
accumulate-response × レスポンス データを単一のオブジェクトに蓄積してから、プラグイン チェーンの次のハンドラにデータを渡します。単一の累積されたレスポンス コンテンツ オブジェクトを操作する必要がある変換プラグインを作成する場合に便利です。
transform-uppercase × リクエスト データまたはレスポンス データを変換する。このプラグインは、変換プラグインのベスト プラクティス実装を表しています。このサンプル プラグインは簡単な変換を実行しますが（リクエストまたはレスポンスのデータを大文字に変換します）、XML から JSON などの他の種類の変換を実行するように簡単に調整できます。
json2xml × 承認またはコンテンツ タイプのヘッダーに基づいて、リクエスト データまたはレスポンス データを変換します。詳しくは、GitHub のプラグインに関するドキュメントをご覧ください。
quota-memory × Edge Microgateway へのリクエストに割り当てを適用します。割り当てをローカルメモリに保存、管理します。
ヘルスチェック × Edge Microgateway プロセスに関する情報（メモリ使用量、CPU 使用率など）を返します。プラグインを使用するには、Edge Microgateway インスタンスで URL /healthcheck を呼び出します。このプラグインは、独自のヘルスチェック プラグインを実装するために使用できるサンプルです。

既存のプラグインの場所

Edge Microgateway にバンドルされている既存のプラグインはここにあります。ここで、[prefix] は npm プレフィックス ディレクトリです。このディレクトリが見つからない場合は、 Edge Microgateway がインストールされている場所をご覧ください。

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins

プラグインの追加と構成

次のパターンに従って、プラグインの追加と構成を行います。

  1. Edge Microgateway を停止します。
  2. Edge Microgateway 構成ファイルを開きます。オプションの詳細については、 構成の変更をご覧ください。
  3. 次のように、構成ファイルの plugins:sequence 要素にプラグインを追加します。プラグインは、このリストに表示されている順序で実行されます。
edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
     level: info
     dir: /var/tmp
     stats_log_interval: 60
  plugins:
     dir: ../plugins
     sequence:   
     - oauth
     - plugin-name
  1. プラグインを構成します。一部のプラグインには、構成ファイルで構成できるオプションのパラメータがあります。たとえば、次のスタンザを追加して、spir arrest プラグインを構成できます。詳細については、Spike Arrest プラグインの使用をご覧ください。 
    edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
  1. ファイルを保存します。
  2. 編集した構成ファイルに応じて、Edge Microgateway を再起動または再読み込みします。

プラグイン固有の構成

このディレクトリにプラグイン固有の構成を作成することで、構成ファイルで指定されたプラグイン パラメータをオーバーライドできます。

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins/config

ここで、[prefix] は npm 接頭辞ディレクトリです。このディレクトリが見つからない場合は、 Edge Microgateway がインストールされている場所をご覧ください。

plugins/<plugin_name>/config/default.yaml。たとえば、このブロックを plugins/spikearrest/config/default.yaml に配置すると、他の構成設定をオーバーライドします。

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

spir arrest プラグインの使用

Spike Arrest プラグインは、トラフィックの急増から保護します。Edge Microgateway インスタンスによって処理されるリクエスト数のスロットリングを行います。

Spike Arrest プラグインの追加

プラグインの追加と構成をご覧ください。

Spike Arrest の構成例

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
   bufferSize: 5

Spike Arrest の構成オプション

  • timeUnit: Spike Arrest の実行ウィンドウがリセットされる頻度。有効な値は秒または分です。
  • allow: timeUnit 中に許可されるリクエストの最大数。複数の Edge Micro プロセスを実行している場合もご覧ください。
  • bufferSize: （省略可、デフォルト = 0）bufferSize > 0 の場合、spire arrest はこの数をバッファに保存します。次の実行「ウィンドウ」が発生するとすぐに、バッファ内のリクエストが最初に処理されます。バッファの追加もご覧ください。

スパイク停止の仕組み

スパイク阻止は、トラフィックを特定のリクエスト数に制限する方法ではなく、一般にトラフィックの急増から保護する方法と考えてください。API とバックエンドは一定量のトラフィックを処理でき、急増停止ポリシーにより、必要な量にトラフィックをスムーズに移動できます。

ランタイムの Spar Arrest の動作は、入力した 1 分または 1 秒あたりのリテラル値で想定される動作とは異なります。

たとえば、1 分あたり 30 リクエストのレートを指定した場合、次のようになります。

spikearrest:
   timeUnit: minute
   allow: 30

テストでは、1 分以内に 30 件のリクエストが 1 秒で送信できたと思われるかもしれません。ただし、これはポリシーの設定による措置ではありません。考えてみると、ある環境では、1 秒間に 30 件のリクエストが小さな急増と見なされる可能性があります。

実際の結果スパイク動作を回避するには、次のように、設定を短い間隔に分割し、許可されたトラフィックを平滑化します。

1 分あたりの料金

1 分あたりのレートは、リクエストできる間隔（秒単位）に平滑化されます。たとえば、1 分あたり 30 件のリクエストは、次のように平滑化されます。

60 秒（1 分）÷ 30 = 2 秒間隔、または 2 秒ごとに約 1 件のリクエストが許可されます。2 秒以内に 2 回目のリクエストが失敗すると、また、1 分以内の 31 回目のリクエストは失敗します。

1 秒あたりのレート

1 秒あたりのレートは、ミリ秒間隔で許可されるリクエストに対して平滑化されます。たとえば、1 秒あたり 10 リクエストの場合、次のように平滑化されます。

1, 000 ミリ秒（1 秒）÷ 10 = 100 ミリ秒間隔、または 100 ミリ秒ごとに約 1 つのリクエストが許可される。100 ミリ秒以内の 2 つ目のリクエストは失敗します。また、1 秒以内に行われる 11 回目のリクエストも失敗します。

上限を超えた場合

リクエストの数が指定した期間内で上限を超えると、spike arrest が次のエラー メッセージと HTTP 503 ステータスを返します。

{"error": "spike arrest policy violated"}

バッファの追加

ポリシーにバッファを追加することもできます。バッファを 10 に設定したとします。Spike Arrest 制限を超過しても、API はすぐにエラーを返さないことがわかります。代わりに、リクエストは指定された数までバッファリングされ、次の適切な実行時間枠が利用可能になるとすぐにバッファリングされたリクエストが処理されます。デフォルトの bufferSize は 0 です。

複数の Edge Micro プロセスを実行している場合

許可されるリクエスト数は、実行中の Edge Micro ワーカー プロセスの数によって異なります。Spike Arrest では、ワーカー プロセスあたりの許容リクエスト数を示します。デフォルトでは、Edge Micro プロセスの数は、Edge Micro がインストールされているマシンの CPU 数と等しくなります。Edge Micro を起動する際に、start コマンドの --processes オプションを使用してワーカー プロセスの数を構成できます。たとえば、特定の期間に 100 件のリクエストで Spar Arrest をトリガーし、オプション --processes 4 を使用して Edge Microgateway を起動する場合は、Spike Arrest 構成に allow: 25 を設定します。要約すると、経験則としては、allow 構成パラメータを「目的のスパイク停止数 / プロセス数」の値に設定する必要があります。

割り当てプラグインの使用

割り当てでは、1 時間、1 日、1 週間、または 1 か月の間にアプリが API に送信できるリクエスト メッセージの数を指定します。アプリが割り当て上限に達すると、それ以降の API 呼び出しは拒否されます。スパイク停止と割り当ての違いもご覧ください。

割り当てプラグインの追加

プラグインの追加と構成をご覧ください。

Apigee Edge でのプロダクト構成

API プロダクトを構成する Apigee Edge UI で割り当てを構成します。割り当てで制限する Microgateway 対応プロキシが含まれているプロダクトを確認する必要があります。このプロダクトをデベロッパー アプリに追加する必要があります。デベロッパー アプリのキーを使用して認証される API 呼び出しを行うと、それらの API 呼び出しに割り当てが適用されます。

  1. Apigee Edge 組織アカウントにログインします。
  2. Edge UI で、割り当てを適用する Microgateway 対応プロキシに関連付けられたプロダクトを開きます。
    1. UI で、[公開] メニューから [商品] を選択します。
    2. 割り当てを適用する API が含まれているプロダクトを開きます。
    3. [編集] をクリックします。
    4. [割り当て] フィールドで、割り当て間隔を指定します。たとえば、1 分あたり 100 件のリクエストなど。2 時間ごとに 50,000 件のリクエスト。

  1. [保存] をクリックします。
  2. プロダクトがデベロッパー アプリに追加されていることを確認してください。認証された API 呼び出しを行うには、このアプリのキーが必要です。

割り当ての構成例

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota

割り当ての構成オプション

割り当てプラグインを構成するには、次の例に示すように quotas 要素を構成ファイルに追加します。

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota
quotas:
    bufferSize:
      hour: 20000
      minute: 500
      month: 1
      default: 10000
    useDebugMpId: true
    failOpen: true
    isHTTPStatusTooManyRequestEnabled: true
...
オプション 説明
bufferSize

（整数）bufferSize 構成を使用すると、Edge Microgateway が割り当て数を Apigee Edge と同期する頻度を調整できます。bufferSize を理解するには、次の構成例をご覧ください。

quotas:
 bufferSize:
  minute: 500
  default: 10000
 useDebugMpId: true
 failOpen: true

デフォルトでは、割り当て間隔が「分」に設定されている場合、Microgateway は割り当てカウンタを Apigee Edge と 5 秒ごとに同期します。上記の構成では、API プロダクトで割り当て間隔が「minute」に設定されている場合、500 リクエストごと、または 5 秒後（どちらか早いほう）に現在の割り当てカウントを取得するよう Edge Edge が Edge と同期します。詳細については、割り当てのカウント方法をご覧ください。

使用できる時間単位には、minute、hour、day、week、month、default があります。
isHTTPStatusTooManyRequestEnabled

割り当ての違反がある場合、ステータス 403 ではなく HTTP 429 レスポンス ステータスを返すように割り当てプラグインを構成します。

デフォルト: falseデフォルトでは、またはフラグが false に設定されている場合、割り当てを超過すると HTTP ステータス 403 が返されます。

このフラグを true に設定すると、割り当てを超過すると、HTTP ステータス 429 が返されます。

デフォルトの HTTP リターン ステータスを 429 に変更するには、次の構成を使用します。 

edgemicro:
...
quotas:
  isHTTPStatusTooManyRequestEnabled: true
...
failOpen この機能を有効にすると、割り当て処理エラーが発生した場合、または Edge に対する「割り当て適用」リクエストがリモート割り当てカウンタの更新に失敗した場合、リモート 割り当てが次に成功するまで、割り当てはローカル数に基づいて処理されます。どちらの場合も、リクエスト オブジェクトに quota-failed-open フラグが設定されます。

割り当ての「フェイル オープン」機能を有効にするには、次の構成を設定します。

edgemicro:
...
quotas:
  failOpen: true
...
useDebugMpId 割り当てレスポンスで MP（Message Processor）のロギングを有効にするには、このフラグを true に設定します。

この機能を使用するには、次の構成を行う必要があります。 

edgemicro:
...
quotas:
  useDebugMpId: true
...

useDebugMpId が設定されている場合、Edge からの割り当てレスポンスに MP ID が含まれ、Edge Microgateway によって記録されます。次に例を示します。 

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}
useRedis true に設定すると、プラグインは、割り当てバッキング ストアに Redis を使用します。詳細については、Redis バッキング ストアを使用した割り当てをご覧ください。

割り当てのカウント方法を理解する

デフォルトでは、割り当て間隔が「分」に設定されている場合、Microgateway は割り当てカウンタを Apigee Edge と 5 秒ごとに同期します。間隔を「分」より高いレベル（「週」や「月」など）に設定した場合、デフォルトの更新期間は 1 分です。

Apigee Edge で定義されている API プロダクトには、割り当て間隔を指定することに注意してください。割り当て間隔は、1 分、1 時間、1 日、1 週間、または 1 か月に許可されるリクエストの数を指定します。たとえば、プロダクト A に 1 分あたり 100 リクエストの割り当て間隔があり、プロダクト B には 1 時間あたり 10,000 リクエストの割り当て間隔があります。

Edge Microgateway quota プラグインの YAML 構成では、割り当て間隔は設定されません。代わりに、ローカルの Edge Microgateway インスタンスが割り当てを Apigee Edge と同期する頻度を調整できます。

たとえば、次の割り当て間隔が Apigee Edge で定義されている次の 3 つの API プロダクトがあるとします。

  • プロダクト A には 1 分あたり 100 個のリクエストの割り当てがある
  • プロダクト B には、1 時間あたり 5,000 件のリクエストの割り当てがある
  • プロダクト C のリクエストの割り当ては 1 か月あたり 1000,000 件

これらの割り当てを念頭に置いて、Edge Microgateway quota プラグインをどのように構成する必要がありますか。Edge Microgateway は、API プロダクトで定義された割り当て間隔よりも短い同期間隔で構成することをおすすめします。次に例を示します。

quotas:
    bufferSize:
      hour: 2000
      minute: 50
      month: 1
      default: 10000

この構成では、前述の API プロダクトで次の同期間隔を定義します。

  • 商品 A は「分」間隔に設定されています。Edge Microgateway は、50 件ごとのリクエストまたは 5 秒のうち、いずれか早いほうのタイミングで Edge に同期されます。
  • 商品 B は「時間」に対して設定されます。Edge Microgateway は、2, 000 件のリクエストごと、または 1 分後のどちらか早い方のタイミングで Edge に同期されます。
  • 商品 C は「月」間隔に設定されています。Edge Microgateway は、リクエストが行われるたびに、または 1 分後のどちらか早い方のタイミングで Edge に同期されます。

マイクロゲートウェイ インスタンスが Edge と同期されるたびに、マイクロゲートウェイの割り当て数が取得した割り当て数に設定されます。

bufferSize 設定を使用すると、割り当てカウンタを Edge と同期する方法を調整できます。トラフィックが多い状況では、bufferSize 設定で、デフォルトの時間ベースの同期がトリガーされる前に、バッファ カウンタを同期できます。

割り当てスコープについて

割り当て数のスコープは、組織内の環境です。このスコープを実現するため、Edge Microgateway は、「org + env + appName + productName」を組み合わせた割り当て ID を作成します。

Redis バッキング ストアを使用した割り当て

割り当てに Redis バッキング ストアを使用するには、Synchronizer 機能と同じ構成を使用します。割り当てストレージに Redis を使用するために必要な基本的な構成は次のとおりです。

edgemicro:
  redisHost: localhost
  redisPort: 6379
  redisDb: 2
  redisPassword: codemaster

quotas:
  useRedis: true
edgemicro.redis* パラメータの詳細については、Synchronizer の使用をご覧ください。

Quota プラグインのテスト

割り当てを超えると、HTTP 403 ステータスが次のメッセージとともにクライアントに返されます。

{"error": "exceeded quota"}

スパイク停止と割り当ての違いは何ですか？

目下の業務に適したツールを選択することが重要です。Quota ポリシーは、1 時間、1 日、1 週間または 1 か月の間にクライアント アプリが API に送信できるリクエスト メッセージの数を構成します。割り当てポリシーは、受信リクエストを集計する分散カウンタを維持することにより、クライアント アプリに消費上限を適用します。

デベロッパーやパートナーとビジネス契約または SLA を適用するには、運用上のトラフィック管理ではなく割り当てポリシーを使用します。たとえば、無料サービスのトラフィックを制限する一方で、有料のお客様には完全アクセス権を付与するために割り当てを使用できます。

Spike Arrest を使用して、API トラフィックの急増を防ぎます。通常、Spar Arrest は DDoS やその他の悪意のある攻撃を回避するために使用されます。