API Gateway:パラメータと条件式の使用

1. 概要

API Gatewayプラグインを使用すると、リクエスト、レスポンス、またはシステムコンテキストからパラメーター値を取得し、カスタムの条件式を使用してパラメーター値を判断できます。 このトピックでは、parametersを定義する方法と条件式を記述する方法について説明します。

2. パラメータ定義

2.1 定義方法

条件式を使用する前に、この条件式に必要なすべてのパラメーターをparametersフィールドに明示的に定義する必要があります。 例：

---
parameters:
  method: "Method"
  appId: "System:CaAppId"
  action: "Query:action"
  userId: "Token:UserId"

parametersフィールドに指定されたパラメーターは、STRING型のキーと値のペアです。

• keyは、条件式で使用する変数の名前を示します。 名前は一意である必要があり、[a-zA-Z_][a-zA-Z0-9]+ のルールに準拠している必要があります。

• valueはパラメーターの場所を示します。 {location} または {location }:{ name} 形式で指定します。

  • locationは、パラメーターの場所を示します。 詳細については、次の表を参照してください。

  • nameは、パラメーターの名前を示します。 この名前は、特定の場所でパラメータを見つけるために使用されます。 たとえば、Query:q1は、クエリ文字列でq1という名前のパラメーターの最初の値を示します。

2.2 パラメーターの場所

条件式を使用する前に、この条件式で必要なパラメーターを定義する必要があります。 次の表に、API Gatewayのプラグインが使用できる特定の場所のパラメーターを示します。

パラメータの場所の使用に関する注意

• パラメーターベースのアクセス制御プラグイン、スロットリングプラグイン、およびは、リクエストを受信したときに機能します。 これらのプラグインでは、リクエスト内のメソッド、パス、ヘッダー、クエリ、フォーム、パラメータ、システム、トークン、およびXFFの場所のパラメータが適用されます。

• エラーマッピングプラグインは、応答を受信すると機能します。 これらのプラグインでは、StatusCode、ErrorCode、Header、BodyJsonField、System、Tokenの各場所のパラメーターが適用されます。

• [メソッド] 、[パス] 、[ステータスコード] 、[エラーコード] 、および [XFF] の場所に必要なのは場所のみです。 これらの場所では名前は必要ありません。

• リクエストフェーズでプラグインの [ヘッダー] の場所でパラメーターを使用すると、クライアントからのリクエストに含まれるヘッダーが読み取られます。 応答フェーズでこれらのパラメーターを使用すると、バックエンド応答のヘッダーが読み取られます。

• [パラメーター] の場所にあるパラメーターは、リクエストフェーズのプラグインでのみ使用できます。 API定義で同じ名前のパラメーターを検索するには、バックエンドパラメーターの代わりにフロントエンドパラメーターを使用します。 同じ名前のパラメーターが存在しない場合、null値が返されます。

• ホストの場所にあるパラメーターは、ワイルドカードドメイン名のパラメーターを取得した場合にのみ使用できます。 詳細については、「カスタムドメイン名をバインドしてAPI呼び出しを許可する」をご参照ください。 完全なドメイン名のシステムパラメーターを取得するには、system: CaDomainを使用します。

• 完全なリクエストパスがpathから返されます。 [パス] の場所でパラメーターが必要な場合は、[パラメーター] の場所で対応するパラメーターを使用します。

• BodyJsonFieldロケーションのパラメーターは、エラーコードマッピングプラグインでのみ使用できます。 J SONPathモードのバックエンド応答のJSON形式の本文でパラメーターを取得します。 詳細については、「2.4」をご参照ください。 JSONPathの使用法ノート。

• 認証にJWT認証プラグインが使用されている場合は、Token:{CliamName} を使用して、tokenの {CliamName} で指定されたパラメーターの値を取得します。 詳細については、「」をご参照ください。

2.3 JSONPathの使用法ノート

JSONPath式を使用して、BodyJsonFieldの場所でエラーコードマッピングプラグインのみのパラメーターを取得できます。 パラメーターは、バックエンド応答で返されるJSON形式の本文にあります。 JSONPath式の詳細については、「JSONPath」をご参照ください。

• 例: code:"BodyJsonField:$.result_code" を使用して、次の本文のresult_codeパラメーターの値を取得します。 ボディの解析結果はcode: okです。

{ "result_code": "ok", "message": ... }

2.4 システムパラメーター

3. 条件式

条件式を使用して、プラグインなどのシナリオの条件に基づいてパラメーター値を判断できます。

3.1 構文

• 条件式はSQL文に似ています。 例: $A > 100および '$B = 'B' 。

• 式の形式は {Parameter} {Operator} {Parameter} です。 上記の例では、$a> 100に変数または定数を指定できます。

• 変数は $で始まり、コンテキストで定義されたパラメーターを参照します。 たとえば、q1:"Query:q1" はparametersで定義されています。 式で変数 $q1を使用できます。 この変数の値は、リクエスト内のq1クエリパラメーターの値です。

• 定数には、文字列、数値、またはブール値を指定できます。 例えば、定数は、「Hello」、「foo」、100、− 1、0,1、またはtrueとすることができる。 詳細については、「3.2値タイプと判断ルール」をご参照ください。

• 次の演算子がサポートされています。

• =および ==: に等しい。

• <>と!=: not equal to。

• > 、>= 、< 、および <=: 比較。

• のようにと! のように: 特定の文字列が指定されたパターンと一致するかどうかを確認します。 パーセント記号 % は、判断でワイルドカードとして使用されます。 例: $Query like 'Prefix % '

• in_cidrと! in_cidr: IPアドレスがCIDRブロックにあるかどうかを確認します。 例: $ClientIp in_cidr '47.89.XX. XX/24 '

• nullを使用して、パラメーターが空かどうかを確認できます。 例:$A == nullまたは$A! =null.

• デフォルトでは、and、or、およびxorを使用して、異なる式を右から左の順序で組み合わせることができます。

• (および) を使用して条件式の優先度を指定できます。

• を使用できます。You can use! (と)囲まれた式に対して論理否定操作を実行するには、 たとえば、の結果は!(1=1)はfalse.

• 次の組み込み関数は、特別なシナリオでの判断に使用されます。

  • Random(): 浮動小数点数型のパラメータを生成します。 パラメータ値の範囲は0から1です。 このパラメーターは、blue-greenリリースなど、ランダムな入力が必要なシナリオで使用されます。

  • Timestamp(): UNIX timestampを返します。 UNIXタイムスタンプは、1970年1月1日木曜日00:00:00から経過したミリ秒数です。

  • TimeOfDay(): GMTの現在の日の00:00から経過したミリ秒数を返します。

3.2 値のタイプと判断ルール

• 次の値型が式でサポートされています。

  • STRING: 値は、一重引用符 (') または二重引用符 (") で囲まれた文字列です。 例: "Hello" と 'Hello' 。

  • NUMBER: 値は整数または浮動小数点数です。 例: 1001、-1、0.1、および -100.0

  • BOOLEAN: 値はブール値です。 例: trueおよびfalse。

• 演算子タイプが等しい、等しくない、および比較の場合、次の判断ルールが適用されます。

  • STRING型: 文字列の順序を使用して判断します。 例：

    • '123' > '10000': 結果はtrueです。

    • 'A123' > 'A120': 結果はtrueです。

    • '' <'a': 結果はtrueです。

  • NUMBERタイプ: 判断に数値を使用します。 例：

    • 123 > 1000: 結果はfalseです。

    • 100.0 == 100: 結果はtrueです。

  • BOOLEAN型: ブール値の場合、trueはfalseより大きくなります。 例：

    • true == true: 結果はtrueです。

    • false == false: 結果はtrueです。

    • true > false: 結果はtrueです。

• 演算子の型が等しい、等しくない、およびcomparisonの場合、演算子の前後の値の型が異なる場合、次の判断ルールが適用されます。

  • STRING NUMBER: たとえば、演算子の前の値はSTRING型で、演算子の後の値はNUMBER型です。 演算子前の値タイプをNUMBERに変更できる場合は、数値を使用して判断します。 それ以外の場合は、文字列順序を使用して判断します。 例：

    • '100' == 100.0: 結果はtrueです。

    • '-100' > 0: 結果はfalseです。

  • STRING BOOLEAN: たとえば、演算子の前の値はSTRING型で、演算子の後の値はBOOLEAN型です。 演算子の前の値タイプをBOOLEANに変更でき、その値が大文字と小文字を区別しない場合は、trueとfalseを含むBOOLEAN値を使用して判断します。 それ以外の場合は、の判断結果を除きます。!=、他のすべての判断結果はfalse. 例：

    • 'True' == true: 結果はtrueです。

    • 'False' == false: 結果はtrueです。

    • 'bad' == false: 結果はfalseです。

    • 「悪い」! =false: 結果は真です。 演算子の前の値が真またはfalseの結果のみ!=は真.

    • 「悪い」! =true。 結果は真です。

    • '0' > false: 結果はfalseです。

    • '0' <= false: 結果はfalseです。

  • NUMBER BOOLEAN: 演算子の前の値がNUMBER型で、演算子の後の値がBOOLEAN型の場合、結果は常にfalseになります。

• null値は、パラメーターが空かどうかを確認するために使用されます。 演算子タイプが等しい、等しくない、および比較の場合、次の判断ルールが適用されます。

  • が$A変数が空の場合、$A == nullはtrueであり、の結果は$A! =nullはfalseです。

  • 空の文字列 ''がnullと等しくない場合、'' == nullの結果はfalseで、'' == '' の結果はtrueです。

  • comparison演算子タイプの場合、演算子の両側の値がnullの場合、結果はfalseになります。

• のようにと! のように演算子は、プレフィックス、サフィックス、および文字列の包含を一致させるために使用されます。 次の判断ルールが適用されます。

  • 式では、演算子の後の値はSTRING型の定数でなければなりません。 例: '/users/%' のような $Path

  • 文字列の接頭辞、接尾辞、または包含を一致させるために、演算子の後の値の '%' ワイルドカード文字が使用されます。 例：

    • プレフィックスマッチング:'/users/%' のような $パスと$パス! '/admin/%' のように.

    • 接尾辞マッチング:'% search' のような $q1と$q1! '%.do' のように.

    • 包含関係マッチング:'% 400%' のような $ErrorCodeと$ErrorCode! '% 200%' のように.

  • 演算子の前の値の型がNUMBERまたはBOOLEANでない場合は、型をSTRINGに変更して判断を行います。

  • 演算子の前の値がnullの場合、結果はfalseになります。

• in_cidrと! in_cidr演算子は、IPアドレスがCIDRブロックにあるかどうかを確認するために使用されます。 次の判断ルールが適用されます。

  • 演算子の後の値は、STRING型の定数で、IPv4またはIPv6 CIDRブロックである必要があります。 例：

    • $ClientIP in_cidr '10.0.0.0/8 '

    • $ClientIP! in_cidr '0:0:0:0:0:FFFF::/96'

  • 演算子の前の値の型がSTRINGの場合、その値はIPv4 CIDRブロックとして判断されます。

  • 演算子の前の値型がNUMBERまたはBOOLEANの場合、または値が空の場合、結果はfalseになります。

  • System:CaClientIpパラメーターは、クライアントのIPアドレスを指定します。 このパラメーターは判断に使用できます。

4. ユースケース

• 確率が5% 未満かどうかを確認します。

Random() < 0.05

• 要求されたAPIがテスト環境に公開されているかどうかを確認します。

parameters:
  stage: "System:CaStage"

$CaStage = 'TEST'

• カスタムパラメーターUserNameがAdminに設定され、送信元IPアドレスが47.47.XX.XX/24にあるかどうかを確認します。

parameters:
  UserName: "Token:UserName"
  ClientIp: "System:CaClientIp"

$UserName = 'Admin' and $CaClientIp in_cidr '47.47.XX.XX/24'

• 次の式の結果がtrueの場合、CaAppIdパラメーターは1001、1098、または2011に設定され、APIリクエストで使用されるプロトコルはHTTPSです。

parameters:
  CaAppId: "System:CaAppId"
  HttpSchema: "System:CaHttpSchema"

$CaHttpScheme = 'HTTPS' and ($CaAppId = 1001 or $CaAppId = 1098 or $CaAppId = 2011)`

• 次の式の結果がtrueの場合、JSON形式の本文には、レスポンス内のStatusCodeが200されたときに値がokではないresult_codeパラメーターが含まれます。

parameters:
  StatusCode: "StatusCode"
  ResultCode: "BodyJsonField:$.result_code"

$StatusCode = 200 and ($ResultCode <> null and $ResultCode <> 'ok')

5. 制限事項

• プラグインには最大16個のパラメーターを指定できます。

• 1つの条件式に最大512文字を含めることができます。

• BodyJsonFieldで指定されたリクエストまたはレスポンス本文のサイズは、16 KBを超えることはできません。 それ以外の場合、設定は有効になりません。