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表示請求的QueryString中名字為q1的第一個值。

2.1. 參數的支援位置

在使用條件運算式前，我們需要先定義參與條件運算式計算的參數，目前API Gateway支援在外掛程式中直接使用如下位置的參數

取值規則的說明

• 參數存取控制外掛程式,流量控制外掛程式,後端路由外掛程式發生在要求階段，外掛程式僅支援適用範圍為請求的參數位置：Method、Path、Header、Query、Form、Parameter、System、Token、XFF。

• 錯誤碼映射外掛程式發生在應答階段，外掛程式僅支援適用範圍為應答的參數位置：StatusCode、ErrorCode、Header、BodyJsonField、System、Token。

• Method、Path、StatusCode、ErrorCode和XFF這幾個位置僅提供Location即可，不需要Name。

• Header位置的參數，當用於要求階段的外掛程式時，讀取來自用戶端請求中的Header。當用於應答階段的外掛程式時，讀取來自後端應答中的Header 。

• Parameter位置的參數，僅用於要求階段的外掛程式，尋找API定義中同名的參數，使用參數名而非後端參數名尋找，當參數不存在時返回為null。

• Host位置的參數，僅支援在泛網域名稱參數提取，參考使用自訂網域名調用API, 完整的Host請使用System:CaDomain讀取系統參數。

• Path返回為完整的請求路徑，如果需要Path位置的參數，請使用Parameter位置的參數。

• BodyJsonField位置的參數，目前僅支援在錯誤碼映射外掛程式中使用，使用JSONPath方式讀取應答JSON包體的值，參考JSONPath使用說明。

• Token當配置了JWT認證外掛程式時，使用Token:{CliamName}可以讀取在外掛程式定義的值，參考對應外掛程式的文檔。

2.3. JSONPath使用說明

用於BodyJsonField位置，目前僅用於錯誤碼映射外掛程式，用於從後端返回的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'。

• 運算式的基本為{參數} {操作符} {參數}格式，如：$A > 100參數支援變數參數或常量參數。

• 變數參數以$開頭，用於引用在上下文中定義好的參數，例如：parameters中定義了q1:"Query:q1"的參數，在運算式中可以使用變數$q1，這個變數的值為當前請求中名為q1的Query參數的值。

• 常量參數支援字串、數字、布爾類型，如"Hello",'foo',100,-1,0.1,true，請參考參數類型與判斷規則。

• 支援以下操作符：

• =, ==：等於判斷。

• <>, !=：不等於判斷。

• >, >=, <, <=：比較判斷。

• like、!like：相似判斷，在字串頭尾的%可用於判斷字串相似，如$Query like 'Prefix%'。

• in_cidr、!in_cidr：判斷IP地址的掩碼，例如：$ClientIp in_cidr '47.89.XX.XX/24'。

• 可使用null來判斷參數是否為空白，如：$A == null 或 $A != null。

• 可以使用and、or、xor來組合串連不同的運算式，預設串連順序為從右至左。

• 可以用小括弧(，)來指定條件的優先順序。

• 使用!(, )可以對括起來的運算式執行取反操作，如：!(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。

• 對於等於、不等於、比較操作符，不同類型的判斷依據為：

  • 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。

• 對於等於、不等於、比較操作符，如果左右兩側的參數類型不一致，參考以下的判斷依據：

  • 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。

  • NUMBERBOOLEAN: 永遠返回false。

• null值可用於欄位是否為空白的判斷，對於等於、不等於、比較操作符，判斷依據為：

  • 當參數$A為空白時，$A == null 結果為true，$A != null 結果為false。

  • Null 字元串''不等於null時： '' == null 結果為false，'' == ''結果為true。

  • 當用於比較操作符時，任意一測值為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位址區段掩碼的判斷，判斷依據為：

  • 運算式僅支援右值為STRING常量且符合IPv4或IPv6 CIDR格式的寫法，如：

    • $ClientIP in_cidr '10.0.0.0/8'

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

  • 當左實值型別為STRING時，會作為IPv4地址後進行判斷。

  • 當左實值型別為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')