プラグインを使用する

現在、Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントをご確認ください。 情報

Edge Microgateway バージョン 3.3.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 プラグインは、トラフィックの急増から保護します。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 の場合、Spike Arrest はこの数のリクエストをバッファに保存します。次の実行「ウィンドウ」が発生すると、バッファリングされたリクエストが最初に処理されます。バッファの追加もご覧ください。

Spike Arrest の仕組み

Spike Arrest は、トラフィックを特定のリクエスト数に制限する方法ではなく、トラフィックの急増から一般的に保護する方法と考えてください。API とバックエンドは一定量のトラフィックを処理できます。Spike Arrest ポリシーにより、必要な一般的な量にトラフィックが分散されます。

ランタイムの Spike Arrest の動作は、入力する文字どおりの 1 分あたりの値または秒あたりの値から予想されるものとは異なります。

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

spikearrest:
   timeUnit: minute
   allow: 30

テストでは、1 分以内に 30 件のリクエストを送信すれば、1 秒で 30 件のリクエストを送信できると考えるかもしれません。ただし、これはポリシーによる設定の適用とは異なります。考えてみると、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 構成パラメータを「目的のスパイク阻止数 / プロセス数」の値に設定することが目安です。

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

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

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

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

Apigee Edge のプロダクト構成

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

1. Apigee Edge 組織アカウントにログインします。
2. Edge UI で、割り当てを適用する microgateway 対応プロキシに関連付けられているプロダクトを開きます。
   1. UI で、[Publish] メニューから [Products] を選択します。
   2. 割り当てを適用する API を含むプロダクトを開きます。
   3. [編集] をクリックします。
   4. [割り当て] フィールドで、割り当て間隔を指定します。たとえば、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

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

割り当てプラグインを構成するには、次の例に示すように、構成ファイルに 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
...

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

edgemicro:
...
quotas:
  isHTTPStatusTooManyRequestEnabled: 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"
}

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

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

Apigee Edge で定義されている API プロダクトでは、割り当て間隔を指定することに注意してください。割り当て間隔では、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 か月あたりのリクエスト 10 万件の割り当てがあります。

これらの割り当て設定を念頭に置いて、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 回のリクエストまたは 1 分経過後のいずれか早い方のタイミングで、Edge に同期されます。

microgateway インスタンスが Edge と同期するたびに、Microgateway の割り当て数は取得された割り当て数に設定されます。

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

割り当てプラグインのテスト

割り当てを超過すると、HTTP 403 ステータスと次のメッセージが返されます。

{"error": "exceeded quota"}

Spike Arrest と割り当ての違いは何ですか？

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

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

Spike Arrest を使用して、API トラフィックの急増から保護します。通常、Spike Arrest は、DDoS などの悪意のある攻撃を阻止するために使用されます。