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

2. パラメーターの定義

2.1 定義メソッド

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

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

parameters フィールドには、文字列型のキーと値のペアが含まれています。key と value は次のように定義されます。

• key: 条件式で使用する変数の名前。名前は一意である必要があり、[a-zA-Z_][a-zA-Z0-9]+ のフォーマットに従う必要があります。

• value: パラメーターの場所。場所は {location} または {location}:{name} のフォーマットで定義します。例：

  • location: パラメーターの場所。詳細については、次のセクションをご参照ください。

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

2.2 パラメーターの場所

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

パラメーターの場所の使用上の注意

• パラメーターベースのアクセス制御プラグイン、トラフィックシェーピングプラグイン、および バックエンドルーティングプラグインは、リクエストフェーズで実行されます。これらのプラグインは、Method、Path、Header、Query、Form、Parameter、System、Token、XFF のリクエストの場所からのパラメーターのみをサポートします。

• エラーコードマッピングプラグインは、応答フェーズで実行されます。これらのプラグインは、StatusCode、ErrorCode、Header、BodyJsonField、System、Token の応答の場所からのパラメーターのみをサポートします。

• Method、Path、StatusCode、ErrorCode、および XFF の場所については、場所のみを提供する必要があります。名前は必要ありません。

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

• Parameter の場所にあるパラメーターは、リクエストフェーズのプラグインでのみ使用されます。システムは、バックエンドパラメーター名ではなく、パラメーター名を使用して、API 定義内で同じ名前のパラメーターを検索します。パラメーターが存在しない場合、null が返されます。

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

• Path パラメーターは、完全なリクエストパスを指定します。Path にパラメーターが含まれている場合は、Parameter セクションで定義します。

• BodyJsonField の場所にあるパラメーターは、現在 エラーコードマッピングプラグインでのみサポートされています。JSONPath 式を使用して、JSON 応答本文から値を読み取ります。詳細については、「JSONPath の使用上の注意」をご参照ください。

• Token: JWT 認証プラグインが設定されている場合、Token:{ClaimName} を使用してプラグインで定義された値を読み取ることができます。詳細については、対応するプラグインのドキュメントをご参照ください。

2.3 JSONPath の使用上の注意

BodyJsonField の場所で JSONPath 式を使用して、バックエンド応答の JSON 本文から JSON フィールドを抽出できます。この機能は、エラーコードマッピングプラグインでのみサポートされています。JSONPath の詳細については、「JSONPath」ドキュメントをご参照ください。

• 例: code:"BodyJsonField:$.result_code" を使用して、次の応答本文から result_code の値を取得します。解析された結果は code: ok です。

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

2.4 システムパラメーター

3. 条件式

プラグインやその他のシナリオで条件式を使用して、柔軟な条件付き評価を実行できます。

3.1 構文

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

• 式の基本フォーマットは {parameter} {operator} {parameter} です。たとえば、$A > 100 では、パラメーターは variables または constants になります。

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

• constant は、string、number、または Boolean type にすることができます。たとえば、"Hello"、'foo'、100、-1、0.1、true などです。詳細については、「パラメーターの型と判断ルール」をご参照ください。

• 次の operators がサポートされています。

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

• <> および !=: 等しくない。

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

• like および !like: 類似性チェック。% ワイルドカードを文字列の先頭または末尾で使用して、文字列の類似性をチェックできます。例: $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 を使用して、さまざまな式を組み合わせます。デフォルトの評価順序は右から左です。

• 括弧 ( と ) を使用して、条件の優先順位を指定します。

• !( と ) を使用して、囲まれた式に対して NOT 操作を実行します。たとえば、!(1=1) の結果は false です。

• システムには、特別なシナリオでの評価のためのビルトイン関数があります。

  • Random(): 0 と 1 の間の浮動小数点数を生成します。この関数は、ブルーグリーンデプロイメントなど、ランダム性が必要なシナリオで使用されます。

  • Timestamp(): ミリ秒単位の Unix タイムスタンプを返します。

  • TimeOfDay(): GMT タイムゾーンの現在日の深夜から経過したミリ秒数を返します。

3.2 値の型と判断ルール

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

  • STRING: 文字列型。一重引用符または二重引用符を使用できます。例: "Hello"、'Hello'。

  • NUMBER: 整数または浮動小数点数型。例: 1001、-1、0.1、-100.0。

  • BOOLEAN: ブール型。例: true、false。

• equal to、not equal to、および comparison オペレーターの場合、異なる型に対する評価ルールは次のとおりです。

  • STRING: 評価に文字列の順序を使用します。例：

    • '123' > '1000' の結果は 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 です。

• equal to、not equal to、および comparison オペレーターの場合、左オペランドと右オペランドのパラメーター型が異なる場合、次の評価ルールが適用されます。

  • STRING NUMBER: 左オペランドを NUMBER 型に変換できる場合、値は数値で比較されます。それ以外の場合は、文字列として比較されます。例：

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

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

  • STRING BOOLEAN: 左オペランドを BOOLEAN 型 (大文字と小文字を区別せずに true または false に等しい) に変換できる場合、比較は BOOLEAN 型に基づきます。それ以外の場合、!= 比較を除き、他のすべての比較の結果は false になります。例：

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

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

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

    • 'bad' != false の結果は true です。true または false ではない左オペランドの場合、!= オペレーターのみが true を返します。他のすべての比較オペレーターは false を返します。

    • 'bad' != true の結果は true です。

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

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

  • NUMBER BOOLEAN: 常に false を返します。

• null 値を使用して、フィールドが空かどうかを確認できます。equal to、not equal to、および comparison オペレーターの場合、評価ルールは次のとおりです。

  • パラメーター $A が空の場合、$A == null の結果は true で、$A != null の結果は false です。

  • 空の文字列 '' は null と等しくありません。'' == null の結果は false で、'' == '' の結果は true です。

  • comparison オペレーターの場合、いずれかのオペランドが null の場合、結果は false になります。

• like および !like オペレーターを使用して、文字列のプレフィックス、サフィックス、および包含を確認できます。評価ルールは次のとおりです。

  • 式は、右オペランドとして STRING 定数のみをサポートします。例: $Path like '/users/%'。

  • '%' 文字を右オペランドの先頭または末尾で使用して、プレフィックス、サフィックス、および包含チェックをサポートできます。例：

    • プレフィックスチェック: $Path like '/users/%'、$Path !like '/admin/%'。

    • サフィックスチェック: $q1 like '%search'、$q1 !like '%.do'。

    • 包含チェック: $ErrorCode like '%400%'、$ErrorCode !like '%200%'。

  • 左オペランドが NUMBER または BOOLEAN 型でない場合、評価前に STRING フォーマットに変換されます。

  • 左オペランドが null の場合、結果は false になります。

• in_cidr および !in_cidr 式を使用して、IP アドレスが CIDR ブロック内にあるかどうかを確認できます。評価ルールは次のとおりです。

  • この式は、右オペランドとして IPv4 または IPv6 CIDR フォーマットの STRING 定数のみをサポートします。例：

    • $ClientIP in_cidr '10.0.0.0/8'

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

  • 左オペランドが STRING 型の場合、IP アドレスとして評価されます。

  • 左オペランドが NUMBER または BOOLEAN 型であるか、空の場合、結果は false になります。

  • System:CaClientIp パラメーターはクライアントの IP アドレスを返し、通常このタイプの評価に使用されます。

Random() < 0.05

parameters:
  stage: "System:CaStage"

$CaStage = 'TEST'

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

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

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

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

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

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