プラグインを使用する

Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントに移動します。 情報

Edge Microgateway v. 3.2.x

オーディエンス

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

Edge Microgateway プラグインとは

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

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

Edge Microgateway には、インストール時点でいくつかのプラグインが付属しています。たとえば、次のようなものがあります。

既存のプラグインの場所

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

4. プラグインを構成します。一部のプラグインには、構成ファイルで構成できるオプションのパラメータがあります。たとえば、次のスタンザを追加して、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

5. ファイルを保存します。
6. 編集した構成ファイルに応じて、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

spike arrest プラグインの使用

spike arrest プラグインは、トラフィックの急増から Microgateway を保護します。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 の実行ウィンドウがリセットされる頻度。有効な値は second または minute です。
• allow: timeUnit 中に許可されるリクエストの最大数。複数の Edge Micro プロセスを実行している場合もご覧ください。
• bufferSize: （省略可、デフォルト = 0）bufferSize > 0 の場合、spike arrest でこの数のリクエストがバッファに保存されます。次の実行「ウィンドウ」が発生するとすぐに、バッファされたリクエストが最初に処理されます。バッファの追加もご覧ください。

spike arrest の仕組み

spike arrest は、トラフィックを特定のリクエスト数に制限する方法としてではなく、トラフィックの急増から一般的に保護する方法と考えてください。API とバックエンドは一定量のトラフィックを処理でき、spike arrest ポリシーは必要な通常の量にトラフィックを抑えるのに役立ちます。

ランタイムの spike arrest の動作は、入力した文字どおりの分単位または秒単位の値から予期するものとは異なります。

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

spikearrest:
   timeUnit: minute
   allow: 30

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

実際の結果急増に似た動作を防止するため、spike arrest では、次のように設定をより小さな間隔に分割することで、許可されるトラフィックを平滑化にしていきます。

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 件目のリクエストも失敗します。

上限を超えた場合

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

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

バッファの追加

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

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

許可されるリクエスト数は、実行中の Edge Micro ワーカー プロセスの数によって異なります。spike arrest により、ワーカー プロセスあたりに許可されるリクエスト数が計算されます。デフォルトでは、Edge Micro プロセスの数は、Edge Micro がインストールされているマシン上の CPU の数に等しくなります。ただし、start コマンドで --processes オプションを使用することで、Edge Micro の起動時にワーカー プロセスの数を構成できます。たとえば、一定期間に 100 件のリクエストが発生した場合に spike arrest をトリガーし、オプション --processes 4 を指定して Edge Microgateway を起動する場合は、spike arrest 構成で allow: 25 を設定します。つまり目安として、allow 構成パラメータの値を「希望する spike arrest 数 / プロセス数」に設定します。

quota プラグインの使用

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

quota プラグインの追加

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

Apigee Edge でのプロダクト構成

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

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

3. [保存] をクリックします。
4. プロダクトがデベロッパー アプリに追加されていることを確認します。認証された 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

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

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

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

edgemicro:
...
quotas:
  failOpen: true

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

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}

割り当てのカウント方法について

デフォルトでは、割り当て間隔が「分」に設定されている場合、マイクロゲートウェイは 5 秒ごとに割り当てカウンタを Apigee Edge と同期します。間隔が「分」より大きいレベル（「週」や「月」など）に設定されている場合、デフォルトの更新期間は 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 か月あたり 1,000,000 件のリクエストです。

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

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」の組み合わせである割り当て識別子を作成します。

割り当てに Redis バッキング ストアを使用する

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

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

quotas:
  useRedis: true

quota プラグインのテスト

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

{"error": "exceeded quota"}

spike arrest と quota の違い

現在取り組んでいるジョブに適したツールを選択することが重要です。1 時間、1 日、1 週間または 1 か月にクライアント アプリが API に送信できるリクエスト メッセージの数は、割り当てポリシーによって構成します。割り当てポリシーでは、受信リクエストを集計する分散カウンタを維持することで、クライアント アプリの使用上限が適用されます。

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

API トラフィックの急増を防ぐには、spike arrest を使用します。通常、spike arrest は、考えられる DDoS などの悪意のある攻撃を阻止するために使用されます。