すべてのプロダクト
Search

このプロダクト

    API Gateway:プラグインデータセット

    ドキュメントセンター

    API Gateway:プラグインデータセット

    最終更新日:Jun 23, 2026

    API Gateway のプラグインは、豊富な機能と柔軟なメタデータ管理を提供しますが、テキストベースの構成は大規模なシナリオでは制限となる場合があります。プラグインデータセットは、構成データをプラグインロジックから分離し、データを個別のオブジェクトとして管理できるようにすることで、ユーザビリティとスケーラビリティを大幅に向上させます。

    1. テキストベースのプラグインの制限

    API Gateway のプラグインには、以下の特徴があります。

    • テキストベースの構成

    • 構成に対するサイズ制限

    これらの制限により、一部のプラグインは特定のシナリオでの使用が困難になります。例えば、以下のコードは、IP アドレスベースのアクセス制御プラグインの典型的な構成を示しています。

    ---
type: ALLOW 
items: 
- blocks:
  - 61.3.XX.XX/24
  - 192.168.34.XX/32
  - 192.168.158.XX/32
  appId: 219810
- blocks:
  - 79.11.XX.XX
  - 85.13.XX.XX
  - 72.152.XX.XX

    この構成は、少数の CIDR ブロックを持つ小規模なアプリケーションには適しています。しかし、数十から数百の CIDR ブロックを持つ大規模なアプリケーションでは、このアプローチには 2 つの大きな欠点があります。

    • 管理がエラーを起こしやすいです。単一の CIDR ブロックを変更するには、プラグイン構成全体を更新する必要があります。

    • 多数の CIDR ブロックがあると、構成がプラグインのサイズ制限を超える可能性があります。

    これらの課題は、テキストベースの構成モデルに起因するものです。プラグインデータセットは、これら両方の問題を解決します。

    2. プラグインデータセットによる構成の分離

    プラグインデータセットは、構成データをプラグイン自体から分離します。データは別のデータセットオブジェクトに保存され、プラグイン内から参照されます。データセットへの変更は、それを参照するすべてのプラグインに対してリアルタイムで反映されます。

    プラグイン構成ページの **[スクリプト構成]** エリアで、**[構成テンプレートの選択]** ドロップダウンリストから **[ホワイトリストモード構成]** を選択します。エディターには、`type: ALLOW` や `items` (CIDR ブロック用の `blocks` と `appId` を含む) などのフィールドを含む、YAML 形式の IP アドレスホワイトリスト構成が表示されます。その下の **[データセット]** エリアには、データエントリがテーブル形式で表示されます。列には、値、説明、有効期限、作成日時、更新日時、操作が含まれます。**[データエントリの作成]** をクリックして新しいエントリを追加したり、既存のエントリを **[編集]** または **[削除]** したりできます。

    プラグインデータセットを使用すると、IP アドレスベースのアクセス制御プラグインの構成は、以下のように簡素化できます。

    ---
type: ALLOW 
items: 
- blocksDatasetId: 87b65008e92541938537b1a4a236eda5
  appId: 219810
- blocksDatasetId: 87b65008e92541938537b1a4a236eda3

    もはやプラグイン自体を修正する必要はありません。アクセス制御ポリシーを更新するには、参照されているプラグインデータセット内のデータエントリを修正します。

    プラグインデータセットは、前述の 2 つの問題を解決します。

    • データセットのサイズは柔軟であり、プラグインのサイズ制限に制約されないため、大量のデータを管理できます。

    • データセットに的を絞った変更を加えることで、プラグインの動作を変更できます。例えば、IP アドレスをホワイトリストに追加する場合、プラグイン全体を修正するのではなく、データセットに新しいデータエントリを追加します。

    現在、API Gateway は JWT 認証プラグインでプラグインデータセットをサポートしています。今後、IP アドレスベースのアクセス制御、パラメーターベースのアクセス制御、バックエンドルーティングなど、他のプラグインにもサポートが拡張される予定です。

    3. プラグインデータセットの機能

    プラグインデータセットを使用すると、プラグインの構成データを動的に変更できます。これらには以下の特徴があります。

    1. データセット内のデータエントリへの変更は、すべての専用型インスタンスで 10 秒以内に反映されます。

    2. 最大 100 個のデータセットを作成でき、各データセットには最大 200 個のデータエントリを含めることができます。より高い上限が必要な場合は、チケットを送信してクォータの引き上げをリクエストしてください。

    3. 単一のデータセットは、複数のプラグインから参照できます。データセットへの変更は、それを参照するすべてのプラグインに対して同時に反映されます。

    4. データセット内のデータエントリの値は、一意である必要があります。

    5. 各データエントリに有効期限を設定できます。エントリは有効期限が切れると自動的に無効になります。エントリを無期限に設定することもできます。

    6. プラグインデータセットは、専用型インスタンス上のグループに対してのみ有効です。グループが共有インスタンスに移行された場合、プラグインデータセットは直ちに無効になります。

    4. プラグインデータセットを使用した JWT 認証の設定

    4.1. プラグインデータセットの設定

    • データセットの作成

    データセットの名前を指定し、タイプを選択します。名前はいつでも変更できますが、タイプは選択後に変更できません。JWT 認証プラグインの場合、`JWT_BLOCKING` タイプを選択します。

    • データセットでのデータエントリの作成

    プラグインデータセットを開き、データエントリを作成します。各データエントリの値は、データセット内で一意である必要があります。各エントリに有効期限を設定でき、その期限を過ぎるとエントリは自動的に無効になります。

    値は 1～64 文字の長さで、文字、数字、ピリオド (.)、アンダースコア (_)、ハイフン (-)、スラッシュ (/)、バックスラッシュ (\) を含めることができます。有効期限については、**[短期]** (日付範囲の指定が必要) または **[長期]** を選択できます。また、最大 180 文字の説明を追加することもできます。

    • プラグインデータセット ID の取得

    プラグインデータセットを作成すると、システムによって永続的な ID が生成されます。この ID はデータセットリストページで確認できます。この ID を使用して、プラグインをデータセットにリンクします。

    4.2. JWT 認証プラグインの設定

    API Gateway の JWT 認証プラグインは、プラグインデータセットをサポートするようになりました。

    一般的なユースケースとして、有効なトークンを持っているもののブラックリストに載っているユーザーからのリクエストをブロックする場合があります。プラグインデータセットを使用すると、JWT 認証プラグインはトークンからデコードされたクレームパラメーターに基づいてリクエストを拒否できます。API Gateway は一致するリクエストを拒否し、拒否レスポンスをカスタマイズできます。以下の例は、この設定方法を示しています。`block` で始まるパラメーターに特に注意してください。

    ---
parameter: Authorization   # トークンを取得するパラメーター
parameterLocation: header  # トークンを取得する場所
claimParameters:           # クレームパラメーター変換。ゲートウェイは JWT クレームをバックエンドパラメーターにマッピングします
- claimName: aud           # クレーム名。公開または非公開にできます
  parameterName: X-Aud     # マッピングされたパラメーターの名前
  location: header         # マッピングされたパラメーターの場所。有効な値：query, header, path, formData
- claimName: userId        # クレーム名。公開または非公開にできます
  parameterName: userId    # マッピングされたパラメーターの名前
  location: query          # マッピングされたパラメーターの場所。有効な値：query, header, path, formData
blockClaimParameterName: userId  # 値がブロックリストと照合されるクレームパラメーター
blockByDataSet: 87b65008e92541938537b1a4a236eda5  # ブロックリストを含むプラグインデータセットの ID
blockStatusCode: 403       # 拒否されたリクエストに対して返されるレスポンスのステータスコード
blockResponseHeaders:      # 拒否されたリクエストに対して返されるレスポンスのヘッダー
  Content-Type: application/xml
blockResponseBody:         # 拒否されたリクエストに対して返されるレスポンスの本文
  <Reason>be blocked</Reason>
jwks:
- kid: O9fpdhrViq2zaaaBEWZITz         # 複数の JWK を設定する場合、それぞれに異なる kid を使用します
  kty: RSA
  e: AQAB
  use: sig
  alg: RS256
  n: qSVxcknOm0uCq5v....

    5. まとめ

    プラグインデータセットは、プラグインの構成をテキストベースのモデルから構造化データモデルに移行させます。これにより、部分的なホットアップデートが可能になり、データ量の上限が桁違いに引き上げられます。大規模なユースケース向けに、API Gateway は数百万のエントリを持つプラグインデータセットをサポートし、プラグインの新しい利用方法を切り拓きます。

    現在、API Gateway は JWT 認証プラグインでのみプラグインデータセットをサポートしています。今後、IP アドレスベースのアクセス制御、パラメーターベースのアクセス制御、バックエンドルーティングなど、他のプラグインにもサポートが拡張される予定です。