Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

4.2. 3scale API Management 標準ポリシーからのポリシーチェーン

API プロダクトごとにポリシーチェーンを指定することができます。ポリシーチェーンは以下を行います。

  • APIcast がリクエストに適用するポリシーを指定する。
  • ポリシーの設定情報を提供する。
  • APIcast がポリシーを適用する順番を決定する。

チェーン内でポリシーを正しい順番で設定するには、APIcast がポリシーを API 利用者のリクエストに適用する方法を理解することが重要です。

4.2.1. APIcast NGINX フェーズが 3scale API Management ポリシーを処理する仕組み
リンクのコピー

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 フェーズは、ポリシーチェーン内のポリシーの順序によって影響を受けない処理を実行します。

Expand
NGINX フェーズのリストこのフェーズでの処理の説明

rewrite

要求のターゲット URI を変更する関数を実行します。

access

リクエストを行うためのクライアントの承認を検証する関数を実行します。

content

アップストリーム API に送信されるリクエストのコンテンツを生成します。

NGINX は、content フェーズ内の 1 つのポリシーのみを適用します。ポリシーチェーン内の複数のポリシーがリクエストのコンテンツで動作する場合、NGINX はチェーン内で最も早いポリシーのみを適用します。組み込みの 3scale APIcast ポリシーは常にポリシーチェーンにあり、content フェーズで NGINX の処理が必要になるため、これを理解することが重要です。

たとえば、3scale APIcast ポリシーと Upstream ポリシーの両方が、リクエストを更新してアップストリーム API のパスを指定します。NGINX は、これらの関数を content フェーズで処理します。3scale APIcast ポリシーが Upstream ポリシーの前にある場合、NGINX はアップストリーム API の設定を使用して、そのパスを修正したリクエストに追加します。Upstream ポリシーが 3scale APIcast ポリシーの前にある場合には、NGINX は Upstream ポリシーの式を評価します。一致がある場合、NGINX は修正したリクエストで適宜アップストリーム API のパスを変更します。

balancer

負荷分散関数を実行します。

header_filter

リクエストヘッダーを処理する関数を実行します。

body_filter

リクエストボディーを処理する関数を実行します。

post_action

NGINX がヘッダーとボディーで関数を実行した後にリクエストを処理する関数を実行します。

log

リクエストに関するログ情報を生成します。

metrics

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 がポリシーを適用する順序の例を示しています。

APIcast NGINX 実行フェーズおよび 3scale ポリシーチェーン
View larger image
APIcast NGINX 実行フェーズおよび 3scale ポリシーチェーン

上の図では、ポリシー 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 NGINX 実行フェーズおよびサンプル 3scale ポリシーチェーン
View larger image
APIcast NGINX 実行フェーズおよびサンプル 3scale ポリシーチェーン

APIcast がこのプロダクトにより公開されるアップストリーム API へのアクセスリクエストを受け取ると、APIcast はプロダクトのポリシーチェーンを確認し、以下の表で説明するように関数を実行します。

Expand
NGINX フェーズのリストNGINX が各フェーズで実行する機能

rewrite

ポリシー B が rewrite フェーズに指定する関数 B1 を実行します。

access

ポリシー A が access フェーズに指定する関数 A1 を実行します。

content

ポリシー A とポリシー B のいずれも、content フェーズで実行する関数を指定しません。

balancer

ポリシー A とポリシー B のいずれも、balancer フェーズで実行する関数を指定しません。

header_filter

ポリシーチェーンはポリシー A を指定し、次にポリシー B を指定します。したがって、このフェーズは、ポリシー A が header_filter フェーズに指定する関数 A2 を実行し、続いてポリシー B が header_filter フェーズに指定する関数 B2 を実行します。

body_filter

ポリシー A とポリシー B のいずれも、このフェーズで実行する関数を指定しません。

post_action

ポリシー A とポリシー B のいずれも、このフェーズで実行する関数を指定しません。

log

ポリシー A とポリシー B のいずれも、このフェーズで実行する関数を指定しません。

この例では、ポリシー A がポリシーチェーンの最初のものですが、ポリシー B の関数が NGINX が実行する最初の関数です。これは、ポリシー B が NGINX が (他のフェーズよりも前にある) rewrite フェーズで処理する関数 B1 を指定するためです。

別の例として、以下のポリシーチェーンを考えてみましょう。

  1. URL Rewriting
  2. 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 ポリシーにより、元のパスにマッピングルールが適用されます。

4.2.2. 3scale API Management 管理ポータルでのポリシーチェーンの変更
リンクのコピー

APIcast ゲートウェイ設定の一部として、3scale 管理ポータルでプロダクトのポリシーチェーンを変更します。

手順

  1. 3scale にログインします。
  2. ポリシーチェーンを設定する API プロダクトに移動します。
  3. [your_product_name] > Integration > Policies の順に移動し、Add policy をクリックします。
  4. Policy Chain セクションで、矢印アイコンを使用してポリシーチェーン内のポリシーの順番を変更します。
  5. Update Policy Chain をクリックし、ポリシーチェーンを保存します。

次のステップ

管理ポータルの左側のナビゲーションパネルに、APIcast にプロモートしていない 設定 変更があることを示す警告が表示されるようになりました。ポリシーチェーンの更新をステージング APIcast にプロモートし、必要に応じて更新をテストします。必要な動作を確認したら、更新を実稼働 APIcast にプロモートします。APICAST_CONFIGURATION_CACHE 環境変数をゼロより大きい数 (デフォルト) に設定すると、APIcast が更新された設定を使用するまでにその秒数かかります。

4.2.3. JSON 設定ファイルでの 3scale API Management ポリシーチェーンの作成
リンクのコピー

APIcast のネイティブデプロイメントを使用している場合には、JSON 設定ファイルを作成して、外部でポリシーチェーンを制御することができます。

ポリシーチェーン JSON 設定ファイルには、以下の情報で構成される JSON 配列が含まれます。

  • services オブジェクト (id の値 (ポリシーチェーンが適用されるサービスを指定する数字) が含まれる)。
  • proxy オブジェクト (policy_chain オブジェクトおよび下位オブジェクトが含まれる)。
  • policy_chain オブジェクト (ポリシーチェーンを定義する値が含まれる)。
  • 個々の policy オブジェクト (ポリシーを識別しポリシーの動作を設定するのに必要な name および configuration データの両方を指定する)

カスタムポリシー sample_policy_1 および標準の API イントロスペクションポリシー token_introspection で設定されるポリシーチェーンの例を、以下に示します。 

{
  "services":[
    {
      "id":1,
      "proxy":{
        "policy_chain":[
          {
            "name":"sample_policy_1", "version": "1.0",
            "configuration":{
              "sample_config_param_1":["value_1"],
              "sample_config_param_2":["value_2"]
            }
          },
          {
            "name": "token_introspection", "version": "builtin",
            "configuration": {
              introspection_url:["https://tokenauthorityexample.com"],
              client_id:["exampleName"],
              client_secret:["secretexamplekey123"]
          },
          {
             "name": "apicast", "version": "builtin",
          }
        ]
      }
    }
  ]
}
Copy to Clipboard Toggle word wrap

すべてのポリシーチェーンには、内蔵のポリシー apicast を含める必要があります。apicast ポリシーをポリシーチェーンのどこに設定したかによって、ポリシーの動作が変わります。

4.2.4. 3scale API Management 標準ポリシー関数を実行する NGINX フェーズ
リンクのコピー

以下の表は、メインの NGINX フェーズおよび NGINX がそのフェーズで実行する関数を定義する標準ポリシーのリストを示しています。この表には、NGINX が処理する順序でフェーズが記載されています。

ポリシーチェーンには、NGINX が特定のフェーズで処理するポリシーを複数含めることができます。このような場合には、チェーン内のポリシーの順序が、API リクエストを処理して希望の結果を取得するための正しい順序になるようにしてください。この表では、ポリシーをアルファベット順でリスト表示します。

Expand
NGINX フェーズのリストこのフェーズで処理される関数を定義する標準ポリシー

rewrite

3scale APIcast
3scale Referrer
Anonymous Access
Echo
Header Modification
NGINX Filter
SOAP
Upstream
URL Rewriting
URL Rewriting with Captures
Websocket

access

3scale APIcast
3scale Batcher
Camel Proxy
Content Caching
Edge Limiting
IP Check
JWT Claim Check
RH-SSO/Keycloak Role Check
Maintenance Mode
OAuth 2.0 Mutual TLS Client Authentication
OAuth 2.0 Token Introspection
Rate Limit Headers
Response/Request Content Limits
Routing
TLS Client Certificate Validation
Upstream

content

3scale APIcast
Liquid Context Debug
Rate Limit Headers
Routing
Upstream

balancer

Upstream Mutual TLS

header_filter

CORS Request Handling
Header Modification
Response/Request Content Limits
HTTP Response Code Overwrite

body_filter

Response/Request Content Limits

post_action

3scale APIcast
Custom metrics

log

Edge Limiting
Logging

4.2.5. 3scale API Management 標準ポリシーおよびそれらのポリシーを処理する NGINX フェーズ
リンクのコピー

以下の表は、標準ポリシーと、そのポリシーの関数を実行する NGINX フェーズまたはフェーズのリストを示しています。この表を使用してポリシーチェーンでポリシーを正しい順序で設定し、アップストリーム API の正しいリクエストを生成します。

Expand
標準ポリシーポリシー関数を実行する NGINX フェーズ

3scale APIcast

init
rewrite
access
content
post_action
APIcast は、3scale APIcast ポリシーをすべてのリクエストに適用します。

Anonymous Access

rewrite

3scale Auth Caching

ポリシーチェーンでは、このポリシーの位置は問題ではありません。

3scale Batcher

access

3scale Referrer

rewrite

Camel Service

access

Conditional ポリシー

ポリシーチェーンでは、このポリシーの位置は問題ではありません。

Content Caching

access

CORS Request Handling

header_filter

Custom metrics

post_action

Echo

rewrite

Edge Limiting

access
log

Header Modification

rewrite
header_filter

HTTP Response Code Overwrite

header_filter

IP Check

access

JWT Claim Check

access

Liquid Context Debug

content

Logging

log

Maintenance Mode

access

NGINX Filter

rewrite

OAuth 2.0 Mutual TLS Client Authentication

access

OAuth 2.0 Token Introspection

access

Proxy Service

ポリシーチェーンでは、このポリシーの位置は問題ではありません。

Rate Limit Headers

access +content

Response/Request Content Limits

access
header_filter
body_filter

Retry

ポリシーチェーンでは、このポリシーの位置は問題ではありません。

RH-SSO/Keycloak Role Check

access

Routing

access
content

SOAP

rewrite

TLS Client Certificate Validation

access

TLS Termination

ssl_certificate

Upstream

rewrite
access
content

Upstream Connection

ポリシーチェーンでは、このポリシーの位置は問題ではありません。

Upstream Mutual TLS

balancer

URL Rewriting

rewrite

URL Rewriting with Captures

rewrite

Websocket

rewrite

トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2025 Red Hat