4.2. 3scale 標準ポリシーからのポリシーチェーン
API プロダクトごとにポリシーチェーンを指定することができます。ポリシーチェーンは以下を行います。
- APIcast がリクエストに適用するポリシーを指定する。
- ポリシーの設定情報を提供する。
- APIcast がポリシーを適用する順番を決定する。
チェーン内でポリシーを正しい順番で設定するには、APIcast がポリシーを API 利用者のリクエストに適用する方法を理解することが重要です。
4.2.1. APIcast NGINX フェーズが 3scale ポリシーを処理する仕組み
3scale API ゲートウェイ(APIcast)は、NGINX プロキシー Web サーバーを使用してポリシーを適用します。APIcast が API 利用者からリクエストを受け取ると、APIcast は要求を一連の NGINX フェーズの順番どおりに処理します。それぞれの NGINX フェーズでは、APIcast は以下のポリシーを適用して元のリクエストを変更することができます。
- アップストリーム API ポリシーチェーンのポリシー。ポリシーチェーンは、順番が設定されたポリシーのリストです。デフォルトでは、アップストリーム API のポリシーチェーンには 3scale APIcast ポリシーが含まれます。API プロバイダーは、3scale プロダクトのポリシーチェーンにポリシーを追加することができます。APIcast は、アップストリーム API ポリシーチェーンのポリシーを、そのアップストリーム API に送信された API 利用者のリクエストだけに適用します。
- グローバル 3scale ポリシーチェーンのポリシー。API プロバイダーは、3scale の環境変数を設定して、グローバルポリシーチェーンを更新することができます。APIcast は、グローバルポリシーチェーンのポリシーをすべての API 利用者のリクエストに適用します。
同じポリシーがアップストリーム API のポリシーチェーンおよびグローバルポリシーチェーンにある場合は、アップストリーム API のポリシーチェーンのポリシー設定が優先されます。
APIcast がすべての NGINX フェーズの必要な処理を行った後に、APIcast はリクエストの結果をアップストリーム API に送信します。そのため、処理によって API 利用者のリクエストを変更できるため、希望の動作を実現するには、NGINX フェーズがポリシーを処理する順序を理解することが重要です。
NGINX フェーズの順序と説明
APIcast が API 利用者からリクエストを受け取ると、APIcast はアップストリーム API のポリシーチェーンおよびグローバルポリシーチェーンのポリシーを適用してリクエストを処理します。各 3scale ポリシーは 1 つ以上の関数を定義します。APIcast は、一連の NGINX フェーズの順番どおりにポリシーの関数を実行します。各フェーズでは、NGINX は適用されるポリシーで定義され、そのフェーズでの実行を指定する関数を実行します。以下の表は、ポリシー関数を実行する NGINX のフェーズのリストを示しています。この表に記載されていない追加の NGINX フェーズは、ポリシーチェーン内のポリシーの順序によって影響を受けない処理を実行します。
| NGINX フェーズのリスト | このフェーズでの処理の説明 |
|---|---|
|
| 要求のターゲット URI を変更する関数を実行します。 |
|
| し、リクエストを行うためのクライアントの承認を検証する関数を実行します。 |
|
|
アップストリーム API に送信されるリクエストのコンテンツを生成します。 |
|
| 負荷分散関数を実行します。 |
|
| リクエストヘッダーを処理する関数を実行します。 |
|
| リクエストボディーを処理する関数を実行します。 |
|
| NGINX がヘッダーとボディーで関数を実行した後にリクエストを処理する関数を実行します。 |
|
| リクエストに関するログ情報を生成します。 |
|
| Prometheus エンドポイントから受信されるデータで機能します。 |
ポリシーの順序によって影響を受けない処理を実行する NGINX フェーズの例：
-
APIcast が起動すると、NGINX は
initフェーズに関連付けられたタスクを実行します。 -
APIcast ワーカーが起動すると、NGINX は
init_workerフェーズに関連付けられたタスクを実行します。 -
APIcast が HTTPS 接続を終了すると、NGINX は
ssl_certificateフェーズに関連付けられたタスクを実行します。
NGINX がポリシー関数を実行する順序
API プロバイダーは、1 つ以上のポリシーを 3scale プロダクトに追加してポリシーチェーンを形成できます。各フェーズでは、NGINX はそのフェーズでの実行を指定するポリシー関数のみを処理します。各ポリシー関数は、1 つの NGINX フェーズでの処理中に APIcast がそのデフォルトの動作をどのように変更するかを指定します。たとえば、header_filter フェーズでは、NGINX は header_filter を指定し、リクエストヘッダーで操作する関数を処理します。各フェーズでは、NGINX は、ポリシーチェーンにある順序で該当する関数を処理します。
ポリシーは、context オブジェクトを使用してデータを共有できます。ポリシーは、各フェーズで context オブジェクトを読み取ったり、変更したりできます。
NGINX がポリシー関数を実行する順序は、以下の要素によって異なります。
- ポリシーチェーンでのポリシーの位置
- 特定のポリシー関数を処理する NGINX フェーズ
必要な動作を得るには、ポリシーチェーンの順序を正しく指定する必要があります。ポリシー適用の結果は、ポリシーチェーン内の位置により異なる可能性があるためです。以下の図は、NGINX がポリシーを適用する順序の例を示しています。
上の図では、ポリシー A がポリシーチェーンの最初のものです。しかし、NGINX は、まずポリシー B の関数を処理します。その関数が NGINX の最初のフェーズである rewrite フェーズに関連するためです。
ここで、以下の関数を持つポリシー A およびポリシー B が含まれるプロダクトのポリシーチェーンについて検討します。
ポリシー A は以下を指定します。
-
accessフェーズで実行する NGINX の関数A1 -
header_filterフェーズで実行する NGINX の関数A2
-
ポリシー B は以下を指定します。
-
rewriteフェーズで実行する NGINX の関数B1 -
header_filterフェーズで実行する NGINX の関数B2
-
以下の図は、NGINX がプロダクトのポリシー関数を実行する順序を示しています。
APIcast がこのプロダクトにより公開されるアップストリーム API へのアクセスリクエストを受け取ると、APIcast はプロダクトのポリシーチェーンを確認し、以下の表で説明するように関数を実行します。
| NGINX フェーズのリスト | NGINX が各フェーズで実行する機能 |
|---|---|
|
|
ポリシー B が |
|
|
ポリシー A が |
|
|
ポリシー A とポリシー B のいずれも、 |
|
|
ポリシー A とポリシー B のいずれも、 |
|
|
ポリシーチェーンはポリシー A を指定し、次にポリシー B を指定します。したがって、このフェーズは、ポリシー A が |
|
| ポリシー A とポリシー B のいずれも、このフェーズで実行する関数を指定しません。 |
|
| ポリシー A とポリシー B のいずれも、このフェーズで実行する関数を指定しません。 |
|
| ポリシー A とポリシー B のいずれも、このフェーズで実行する関数を指定しません。 |
この例では、ポリシー A がポリシーチェーンの最初のものですが、ポリシー B の関数が NGINX が実行する最初の関数です。これは、ポリシー B が NGINX が (他のフェーズよりも前にある) rewrite フェーズで処理する関数 B1 を指定するためです。
別の例として、以下のポリシーチェーンについて考えてみましょう。
- URL Rewriting
- 3scale APIcast（すべてのプロダクトに割り当てられたデフォルトポリシー）
URL Rewriting ポリシーは、リクエストのターゲットパスを変更します。APIcast は rewrite フェーズで URL Rewriting 関数を実行します。3scale APIcast ポリシーは、APIcast が rewrite フェーズで実行する関数に加えて、APIcast が他の 3 つのフェーズで実行する関数を定義します。URL Rewriting ポリシーが最初になると、3scale APIcast ポリシーにより、書き換えられたパスにマッピングルールが適用されます。3scale APIcast ポリシーが最初にあり、URL Rewriting ポリシーが 2 番目の場合には、3scale APIcast ポリシーにより、元のパスにマッピングルールが適用されます。
