プラグインを使用する

Edge Microgateway v. 2.5.x

対象

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

Edge Microgateway プラグインとは

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

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

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

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

既存のプラグインの場所

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

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

プラグインの追加と構成

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

Edge Microgateway を停止します。
Edge Microgateway 構成ファイルを開きます。オプションの詳細については、構成の変更をご覧ください。
次のように、構成ファイルの 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

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

ファイルを保存します。
編集した構成ファイルに応じて、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 件であれば、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 件目のリクエストも失敗します。

制限を超えた場合

リクエスト数が、指定した時間間隔内の制限を超えると、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 の数に等しくなります。ただし、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 呼び出しに割り当てが適用されます。

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

[Save] をクリックします。
プロダクトがデベロッパーアプリに追加されていることを確認します。認証された 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 プラグインには追加の構成オプションはありません。

quota プラグインのテスト

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

    {"error": "exceeded quota"}

spike arrest と quota の違い

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

割り当てポリシーは、運用上のトラフィックを管理するためではなく、デベロッパーやパートナーとの業務契約または SLA を適用するために使用します。たとえば、無料サービスのトラフィックを制限し、有料のお客様にフルアクセスを許可するために使用されています。

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