ポリシーとプラグイン - API Gateway - Alibaba Cloud ドキュメントセンター

AI ゲートウェイでは、API レベルでポリシーの追加とプラグインの設定を行い、API のセキュリティ、パフォーマンス、保守性を向上させることができます。

重要

ポリシー構成の変更はすぐに有効になります。API を再公開する必要はありません。

操作手順

AI ゲートウェイコンソールの [インスタンス] ページに移動します。上部のナビゲーションバーで、ターゲットインスタンスが配置されているリージョンを選択し、ターゲットの [インスタンス ID] をクリックします。
左側のナビゲーションウィンドウで [モデル API] をクリックし、ターゲットの [API 名] をクリックして [API 詳細] ページに移動します。
Policies and Plug-ins タブをクリックします。More policies and plugins セクションで、ポリシーまたはプラグインを設定する場所として Inbound Processing/Outbound Processing を選択し、次に Enable Policy/Plug-in をクリックします。
Enable Policy/Plug-in パネルで、ポリシーまたはプラグインを選択して構成します。詳細については、「ポリシー構成」および「プラグイン構成」をご参照ください。

ポリシー構成

同時実行制御

同時実行制御は、同時リクエスト数を制限することでバックエンドサービスを保護します。ゲートウェイは処理中のリクエストをカウントし、このカウントが指定されたしきい値に達すると、後続のトラフィックを即座にブロックして、バックエンドサービスの過負荷を防ぎ、可用性を確保します。

操作手順

Add Policy タブで、Concurrency Control カードをクリックします。Add Policy パネルで、次のパラメーターを設定します。

パラメーター			説明
Enable or Not			有効にすると、同時実行制御ルールが有効になります。
Overall Concurrency Threshold			Overall Concurrency Threshold を設定します。
Web Fallback Behavior	Return Specific Content	HTTP Status Code	HTTP Status Code を設定します。デフォルトは 429 です。
		Type of Returned Content	Type of Returned Content が Regular Text か [JSON] かを指定します。
		HTTP Text	しきい値を超えた場合に返されるレスポンスボディのコンテンツです。
	Return Specific Content	Redirect URL	Redirect URL を入力します。

トラフィックシェーピング

トラフィックシェーピングは、API の秒間クエリ数 (QPS) をモニターします。QPS が指定されたしきい値に達すると、ゲートウェイは即座にトラフィックをブロックします。これにより、急激なトラフィックスパイクによるバックエンドサービスの過負荷を防ぎ、高可用性を確保します。

操作手順

Add Policy タブで、[トラフィックシェーピング] カードをクリックします。Add Policy パネルで、次のパラメーターを設定します。

パラメーター			説明
Enable or Not			有効にすると、トラフィックシェーピングルールが有効になります。
Overall QPS Threshold			Overall QPS Threshold を設定します。
Web Fallback Behavior	Return Specific Content	HTTP Status Code	HTTP Status Code を設定します。デフォルト値は 429 です。
		Type of Returned Content	Type of Returned ContentがRegular Textか[JSON]かを指定します。
		HTTP Text	しきい値を超えた場合に返されるレスポンスボディのコンテンツです。
	Redirect to Specified Page	Redirect URL	Redirect URL を入力します。

サーキットブレーカーポリシー

サーキットブレーカーポリシーは、バックエンドサービスの応答時間またはエラー率をモニターすることで、サービスを保護します。指定されたしきい値を超えると、ゲートウェイは「サーキットをトリップ」させ、一定期間サービスへのリクエスト送信を停止します。このアクションにより、カスケード障害を防ぎ、高可用性を確保します。期間が経過すると、ゲートウェイは慎重にリソースへのリクエスト送信を再開します。

操作手順

Add Policy タブで、[サーキットブレーカー] カードをクリックします。Add Policy パネルで、次のパラメーターを設定します。

パラメーター			説明
Enable or Not			有効にすると、サーキットブレーカールールが有効になります。
Statistical Window Duration			リクエスト統計を収集するためのタイムウィンドウの期間。有効値は 1 秒から 120 分です。
Minimum Number of Requests			サーキットブレーカーのルールを評価するために必要な、統計ウィンドウ内の最小リクエスト数。リクエスト数がこの値を下回る場合、しきい値を超えてもサーキットはトリップしません。
Threshold Type			しきい値として、Slow Call Ratio (%) または Exception Ratio (%) のどちらを使用するかを選択します。 Slow Call Ratio (%) を選択した場合、Slow Call RT (応答時間) も指定する必要があります。リクエストの応答時間がこの値を超えると、そのリクエストは低速呼び出しとしてカウントされます。ルールが有効な場合、統計ウィンドウ内のリクエスト数が [最小リクエスト数] を超え、かつ低速呼び出しの比率がしきい値を超えると、サーキットがトリップします。トリップした場合、後続のすべてのリクエストは、設定された持続時間にわたって直ちに失敗します。この期間が過ぎると、サーキットは半開状態になり、単一のプロービングリクエストを許可します。このリクエストが成功した場合 (応答時間が [低速呼び出し RT] 未満の場合)、サーキットは閉じ、通常の操作が再開されます。失敗した場合、サーキットは再びトリップします。 Exception Ratio (%) を選択した場合、サーキットをトリップさせるエラー率を指定する必要があります。サーキットは、統計ウィンドウ内でリクエスト数が最小値を超え、かつエラー率が定義されたしきい値を超えた場合にトリップします。トリップした場合、設定された持続時間、後続のリクエストはただちに失敗します。
Slow Call RT			許容される Slow Call RT (最大応答時間) を設定します。
Circuit Breaking Ratio Threshold			サーキットをトリップさせる低速呼び出し率。有効値：0～100 (0%～100% を表します)。
サーキットブレーカー期間 (秒)			トリップ後にサーキットが開いたままになる期間 (秒単位)。この期間中、リソースへのすべてのリクエストは即座に失敗します。
Web Fallback Behavior	Return Specific Content	HTTP Status Code	HTTP Status Code を設定します。デフォルトは 429 です。
		Type of Returned Content	Type of Returned Content が Regular Text か [JSON] かを指定します。
		HTTP Text	しきい値を超えた場合に返されるレスポンスボディのコンテンツです。
	Redirect to Specified Page	Redirect URL	Redirect URL を入力します。

IP ブロックリスト/許可リストポリシー

IP ブロックリスト/許可リストポリシーは、許可する IP アドレス (許可リスト) または拒否する IP アドレス (ブロックリスト) を事前に設定し、それに基づいてクライアントのサービスへのアクセスを制御します。

操作手順

Add Policy タブで、[IP ブロックリスト/許可リスト] カードをクリックします。Add Policy パネルで、次のパラメーターを設定します。

パラメーター	説明
Enable	有効にすると、IP ブロックリスト/許可リストポリシーが有効になります。
Name	ポリシーの一意の名前。これは、特に複数のポリシーを管理する際に識別しやすくするのに役立ちます。
Remarks	識別と管理に役立つポリシーの説明。
Type	アクセスの制御タイプを指定します。 Whitelist：指定された IP アドレスからのみアクセスを許可します。他のすべての IP アドレスからのアクセスは、デフォルトで拒否されます。 Blacklist: 指定された IP アドレスからのアクセスをブロックします。他のすべての IP アドレスからのアクセスは、デフォルトで許可されます。
IP Address/CIDR Block	このポリシーが適用される IP アドレスまたは CIDR ブロックのリスト。複数のエントリがサポートされています。例：`192.168.1.1/24`。

タイムアウトポリシー

AI ゲートウェイでは、API レベルのタイムアウトを設定でき、ゲートウェイがバックエンドサービスからの応答を待つ最大時間を定義します。この期間内に応答がない場合、ゲートウェイは HTTP 504 Gateway Timeout ステータスコードをクライアントに返します。

操作手順

Add Policy タブで、Timeout カードをクリックします。Add Policy パネルで、次のパラメーターを設定します。

説明

タイムアウトポリシーを設定して有効にした後、タイムアウトルールがサービスで期待どおりに機能することを確認してください。

パラメーター

説明

Enable

タイムアウトポリシーを有効にするかどうかを指定します。

有効化：API タイムアウトポリシーが有効になります。
無効化：API タイムアウトポリシーが無効になります。

Timeout Period

API のタイムアウト期間を秒単位で指定します。

説明

このパラメーターを 0 に設定するか、タイムアウトポリシーを無効にすると、ゲートウェイは無期限に応答を待ちます。

リトライポリシー

AI ゲートウェイは、API レベルで失敗したリクエストを自動的にリトライできます。接続の失敗、バックエンドサービスが利用できない、または特定の HTTP ステータスコードなど、特定条件によってリトライがトリガーされるように設定できます。

API リトライ条件

バックエンドサービスが 5xx エラーを返すと、AI ゲートウェイは設定されたリトライ回数に基づいて失敗したリクエストを自動的にリトライします。

HTTP のリトライ条件：
- 5xx：バックエンドサービスが 5xx 応答を返すか、接続が失われたり、リセットされたり、読み取りタイムアウトが発生した場合、AI ゲートウェイはリクエストのリトライを試みます。
  
  説明
  5xx 条件には、connect-failure および refused-stream 条件が含まれます。
- reset：接続が失われたり、リセットされたり、読み取りタイムアウトが発生した場合、AI ゲートウェイはリクエストのリトライを試みます。
- connect-failure：バックエンドサービスへの接続を確立できない場合、AI ゲートウェイは失敗したリクエストのリトライを試みます。
- refused-stream：バックエンドサービスがストリームを REFUSED_STREAM エラーコードでリセットした場合、AI ゲートウェイはリクエストのリトライを試みます。
- retriable-status-codes：バックエンドサービスの応答の HTTP ステータスコードが、指定されたリトライステータスコードのいずれかと一致する場合、AI ゲートウェイはリクエストのリトライを試みます。
  
  説明
  リトライ条件で retriable-status-codes を指定した場合にのみ、リトライステータスコードを使用できます。
gRPC のリトライ条件：
- cancelled：バックエンド gRPC サービスからのレスポンスヘッダーの gRPC ステータスコードが cancelled の場合、AI ゲートウェイはリクエストのリトライを試みます。
- deadline-exceeded：バックエンド gRPC サービスからのレスポンスヘッダーの gRPC ステータスコードが deadline-exceeded の場合、AI ゲートウェイはリクエストのリトライを試みます。
- internal：バックエンド gRPC サービスからのレスポンスヘッダーの gRPC ステータスコードが internal の場合、AI ゲートウェイはリクエストのリトライを試みます。
- resource-exhausted：バックエンド gRPC サービスからのレスポンスヘッダーの gRPC ステータスコードが resource-exhausted の場合、AI ゲートウェイはリクエストのリトライを試みます。
- unavailable：バックエンド gRPC サービスからのレスポンスヘッダーの gRPC ステータスコードが unavailable の場合、AI ゲートウェイはリクエストのリトライを試みます。

操作手順

Add Policy タブで、Retry カードをクリックします。Add Policy パネルで、次のパラメーターを設定します。

説明

リトライポリシーを設定して有効にした後、リトライルールがサービスで期待どおりに機能することを確認してください。

パラメーター	説明
Enable	リトライポリシーを有効にするかどうかを指定します。有効化：API リトライポリシーが有効になります。無効：API リトライポリシーは無効になります。このポリシーが無効の場合、ゲートウェイはデフォルトの内部リトライ構成にフォールバックします。リトライ回数は 2 で、リトライ条件は `connect-failure`、`refused-stream`、`unavailable`、`cancelled`、`non_idempotent`、および `retriable-status-codes` です。
Retry Times	失敗したリクエストの最大リトライ回数です。有効値は 0 ～ 10 です。2 以下の値が推奨されます。このパラメーターを 0 に設定した場合、失敗したリクエストは再試行されません。
Retry Condition	リトライをトリガーする 1 つ以上の条件を選択します。
Retry Status Code	リトライをトリガーする特定の HTTP ステータスコード。複数のコードを指定できます。重要 Retry Status Code は、Retry Condition で `retriable-status-codes` を選択した場合にのみ設定できます。

ヘッダー変更ポリシー

ヘッダー変更機能を使用すると、リクエストヘッダーをバックエンドサービスに送信する前、およびレスポンスヘッダーをクライアントに返す前に変更できます。

操作手順

Add Policy タブで、Edit Header カードをクリックします。Add Policy パネルで、次のパラメーターを設定します。

パラメーター	説明
Enable	ヘッダー変更ポリシーを有効にするかどうかを指定します。有効化：有効にすると、ゲートウェイは設定どおりにリクエストヘッダーとレスポンスヘッダーを変更します。無効化：無効にすると、ゲートウェイはリクエストヘッダーまたはレスポンスヘッダーを変更しません。
Header Type	変更するヘッダータイプを選択します。 Request：リクエストヘッダーを変更します。 Response: レスポンスヘッダーを修正します。
Operation Type	実行する操作を選択します。 Add: リクエストまたは応答にヘッダーを追加します。注意ヘッダーがすでに存在する場合、新しい値は既存の値にカンマ (,) で区切られて追加されます。 Modify：指定されたリクエストまたは応答のヘッダーを変更します。注意指定されたヘッダーが存在しない場合は、指定されたキーと値で追加されます。指定されたヘッダーが存在する場合は、その値が上書きされます。 Delete: 指定されたヘッダーをリクエストまたは応答から削除します。
ヘッダーキー	リクエストまたはレスポンスヘッダーの名前を入力します。
ヘッダー値	リクエストまたはレスポンスヘッダーの値を入力します。

プラグイン構成

Add Plug-in タブをクリックします。
Quick Navigation セクションで、タイプ別、または名前で検索して目的のプラグインを探し、プラグインカードをクリックします：
- プラグインがインストールされていない場合、表示されるダイアログボックスでInstall and Configureをクリックします。次に、プラグインのルールを設定して有効にします。
- プラグインがすでにインストールされている場合は、表示されるダイアログボックスでプラグインのルールを設定して有効にします。
OK をクリックします。 API 添付ファイルリストにリダイレクトされ、添付ファイルのステータスを表示できます。

添付リストの [インバウンド処理] セクションには、jwt-auth (無効) と key-auth (有効) が表示されます。[アウトバウンド処理] セクションには、key-auth (有効) と jwt-auth (無効) が表示されます。バックエンドサービスのアドレスは test.static です。リクエストは、フロントエンド API からインバウンド処理を経てバックエンドサービスに流れ、その後アウトバウンド処理を通過します。