このページは Cloud Translation API によって翻訳されました。

プラグインの使用

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

Edge Microgateway バージョン 2.4.x

対象

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

Edge Microgateway プラグインとは何ですか？

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

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

Edge Microgateway には、インストール時にいくつかの既存のプラグインが用意されています。これには以下が含まれます。

Plugin（プラグイン）	デフォルトで有効	説明
アナリティクス	○	Edge Microgateway から Apigee Edge に分析データを送信します。
oauth	○	Edge Microgateway に OAuth トークンと API キーの検証を追加します。Edge Microgateway の設定と構成をご覧ください。
割り当て	×	Edge Microgateway へのリクエストに割り当てを適用します。Apigee Edge を使用して割り当ての保存と管理を行います。割り当てプラグインの使用をご覧ください。
スパイクアレスト	×	トラフィックの急増や DoS 攻撃から保護。Spike Arrest プラグインの使用をご覧ください。
ヘッダー（大文字）	×	デベロッパーがカスタムプラグインを作成するためのガイドとして提供されている、コメント付きのサンプルプロキシ。Edge Microgateway サンプルプラグインをご覧ください。
accumulate-request	×	リクエストデータを 1 つのオブジェクトに蓄積してから、プラグインチェーンの次のハンドラにデータを渡します。単一の累積されたリクエストコンテンツオブジェクトで動作する必要がある変換プラグインを作成する場合に便利です。
accumulate-response	×	レスポンスデータを 1 つのオブジェクトに蓄積してから、プラグインチェーンの次のハンドラにデータを渡します。単一の累積されたレスポンスコンテンツオブジェクトで動作する必要がある変換プラグインを作成する場合に便利です。
大文字変換	×	リクエストデータまたはレスポンスデータを変換します。このプラグインは、変換プラグインのベストプラクティスの実装を表します。このサンプルプラグインは簡単な変換を行います（リクエストやレスポンスのデータを大文字に変換します）。ただし、XML から JSON など、他の種類の変換にも簡単に適応できます。
json2xml	×	Accept ヘッダーまたは content-type ヘッダーに基づいて、リクエストデータまたはレスポンスデータを変換します。詳しくは、GitHub のプラグインに関するドキュメントをご覧ください。
割り当て-メモリ	×	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 プラグインについて説明します。

Spike Arrest について

Spike Arrest はトラフィックの急増から保護します。Edge Microgateway インスタンスによって処理されるリクエストの数をスロットリングします。詳細については、Spike Arrest の機能をご覧ください。Spike Arrest と割り当ての違いもご覧ください。

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 中に許可されるリクエストの最大数。
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 alert はこのエラーメッセージと HTTP 503 ステータスを返します。

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

バッファの追加

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

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

このセクションでは、Quota プラグインについて説明します。

割り当てプラグインについて

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

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

任意のプラグインの基本的な手順については、プラグインの追加と構成をご覧ください。

Apigee Edge のプロダクト構成

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

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

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

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

割り当てプラグインには、追加の構成オプションはありません。

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

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

{"error": "exceeded quota"}

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

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

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

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