條件參考資料

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

條件可讓 API Proxy 在執行階段動態運作。條件會定義變數的運算，並由 Apigee 處理管道評估。條件陳述式為布林值，一律會評估為 true 或 false。

條件總覽

本節說明如何以及在何處使用 Apigee 的條件陳述式。此外，以下各節說明語法：

條件陳述式的結構

條件陳述式的基本結構如下：

<Condition>variable.name operator "value"</Condition>

例如：

<Condition>request.verb = "GET"</Condition>

您可以使用 AND 結合條件，一次強制執行多個條件。舉例來說，只有在要求 URI 符合 /statuses 且要求 HTTP 動詞為 GET 時，下列條件才會評估為 true：

<Condition>(proxy.pathsuffix MatchesPath "/statuses") and (request.verb = "GET")</Condition>

可使用條件陳述式的目標

您可以使用條件控管下列項目的行為：

政策執行

您可以使用條件陳述式控管政策的強制執行。常見用途是根據 HTTP 標頭或訊息內容，有條件地轉換回應訊息。

以下範例會根據 Accept 標頭，有條件地將 XML 轉換為 JSON：

<Step>
  <Condition>request.header.accept = "application/json"</Condition>
  <Name>XMLToJSON</Name>
</Step>

流程執行作業

您可以使用條件式陳述式，在 ProxyEndpoints 和 TargetEndpoints 中控制具名流程的執行作業。請注意，只有具名流程可以有條件地執行。ProxyEndpoints 和 TargetEndpoints 上的前置流程和後置流程 (要求和回應) 會針對每筆交易執行，因此提供無條件的安全功能。

舉例來說，如要根據要求訊息的 HTTP 動詞執行條件式要求流程，並根據代表錯誤的 (可能) HTTP 狀態碼執行條件式回應流程：

<Flow name="GetRequests">
  <Condition>request.verb = "GET"</Condition>
  <Request>
    <Step>
      <Condition>request.path MatchesPath "/statuses/**"</Condition>
      <Name>StatusesRequestPolicy</Name>
    </Step>
  </Request>
  <Response>
    <Step>
      <Condition>(response.status.code = 503) or (response.status.code = 400)</Condition>
      <Name>MaintenancePolicy</Name>
    </Step>
  </Response>
</Flow>

選取目標端點路徑

使用條件陳述式，您可以控制 Proxy 端點設定所叫用的目標端點。路徑規則會將要求轉送至特定目標端點。如果有多個目標端點可用，系統會評估路徑規則的條件，如果條件為 true，要求就會轉送至具名的目標端點。

舉例來說，如要根據 Content-Type 將郵件有條件地轉送至指定目標端點，請按照下列步驟操作：

<RouteRule name="default">
 <!--this routing executes if the header indicates that this is an XML call. If true, the call is routed to the endpoint XMLTargetEndpoint-->
  <Condition>request.header.Content-Type = "text/xml"</Condition>
  <TargetEndpoint>XmlTargetEndpoint</TargetEndpoint>
</RouteRule>

詳情請參閱「流程變數和條件」。

路徑運算式

路徑運算式用於比對 URI 路徑，其中 * 代表單一路徑元素，** 則代表多個 URI 層級。大括號 {name} 也可用來比對單一路徑元素，讓讀者一目瞭然。變數 name 僅用於清楚說明，不會在流程變數中填入相符的值。

例如：

模式 相符的 URI 路徑範例
/*/a/ /x/a/或/y/a/
/*/a/* /x/a/b 或 /y/a/foo
/*/a/** /x/a/b/c/d
/*/a/{reader}/feed/ /x/a/b/feed/或/y/a/foo/feed/
/a/**/feed/** /a/b/feed/rss/1234

% 會被視為逸出字元。模式 %{user%} 與 {user} 相符，但與 user 不相符。

變數

您可以在條件陳述式中使用內建流程變數和自訂變數。 如需詳細資訊，請參閱：

運算子

使用運算子時，請遵守下列限制：

  • 運算子不能做為變數名稱。
  • 運算子前後必須有空格字元。
  • 如要在變數中加入運算子，變數名稱必須以單引號括住。 例如 'request.header.help!me'。
  • 系統不支援算術運算子 (+ * - / %)。
  • 運算子會使用 Java 優先順序。
  • Apigee 採用 java.util.regex 中實作的規則運算式。

下表列出支援的運算子。您可以在運算式中使用符號或字詞：

符號 Word 說明
! Not、not 一元運算子 (採用單一輸入)
= Equals、Is 等於 (區分大小寫)
!= NotEquals、IsNot 不等於 (區分大小寫)
:= EqualsCaseInsensitive 等於 (不區分大小寫)
>或&gt; GreaterThan 大於。如果您在 Apigee UI 中定義條件時使用「>」，系統會將其轉換為「&gt;」。
>=或&gt;= GreaterThanOrEquals 大於或等於。如果您在 Apigee 使用者介面中定義條件時使用 >=，系統會將其轉換為 &gt;=。
&lt; LesserThan 小於。Apigee 使用者介面不支援 < 常值。
&lt;= LesserThanOrEquals 小於或等於。Apigee 使用者介面不支援常值 <=。
&& And、and 且
|| Or Or 運算子不會區分大小寫。舉例來說，OR、Or 和 or 都是有效的。
() 將運算式分組。( 會開啟運算式，) 則會關閉運算式。
~~ JavaRegex

符合 javax.util.regex 相容的規則運算式。比對時需區分大小寫。如需範例，請參閱「 模式比對」。
~ Matches、Like 使用 * 萬用字元比對 glob 樣式的模式。比對時需區分大小寫。如需範例，請參閱「 模式比對」。
~/ MatchesPath、LikePath 比對路徑運算式。比對時會區分大小寫。如需範例，請參閱「 模式比對」。
=| StartsWith 比對字串開頭的字元。比對會區分大小寫。

運算元

Apigee 會先將運算元調整為通用資料型別，再進行比較。舉例來說，如果回應狀態碼為 404，則運算式 response.status.code = "400" 和 response.status.code = 400 等效。

如果是數值運算元，除非值以下列方式終止，否則資料類型會解讀為整數：

  • f 或 F (例如 float、3.142f, 91.1F)
  • d 或 D (例如 double、3.142d, 100.123D)
  • l 或 L (例如 long、12321421312L)

在這些情況下，系統會執行下表所示的調整 (其中 RHS 是指方程式的右側，LHS 則是左側)：

RHS LHS 布林值 整數 長 浮點值 雙精度值 字串 可比較 物件
布林值 布林值 整數 長 浮點值 雙精度值 字串 -
整數 整數 整數 長 浮點值 雙精度值 字串 可比較 -
長 長 長 長 浮點值 雙精度值 字串 可比較 -
浮點值 浮點值 浮點值 浮點值 浮點值 雙精度值 字串 可比較 -
雙精度值 雙精度值 雙精度值 雙精度值 雙精度值 雙精度值 字串 可比較 -
字串 字串 字串 字串 字串 字串 字串 可比較 -
可比較 可比較 可比較 可比較 可比較 可比較 可比較 可比較 -
物件 - - - - - - - -

空值運算元

下表顯示當運算元左側 (LHS) 和/或右側 (RHS) 的值為空值時，條件是否會評估為 true 或 false：

運算子 左側為空值 RHS 空值 LHS 和 RHS 皆為空值
=、==、:= false false true
=| false false false
!= true true false
>或&gt; true false false
>=或&gt;= false true true
&lt; true false false
&lt;= true false true
~ false 不適用 false
~~ false 不適用 false
!~ true false false
~/ false 不適用 false

文字

除了字串和數值常值，您還可以在條件陳述式中使用下列常值：

  • null
  • true
  • false

例如：

  • request.header.host is null
  • flow.cachehit is true

範例

<RouteRule name="default">
     <Condition>request.header.content-type = "text/xml"</Condition>
     <TargetEndpoint>XmlTargetEndpoint</TargetEndpoint>
</RouteRule>
 
<Step>
    <Condition>response.status.code = 503</Condition>
    <Name>MaintenancePolicy</Name>
</Step>
 
<Flow name="GetRequests">
    <Condition>response.verb="GET"</Condition>
    <Request>
        <Step>
            <Condition>request.path ~ "/statuses/**"</Condition>
            <Name>StatusesRequestPolicy</Name>
        </Step>
    </Request>
    <Response>
        <Step>
            <Condition>(response.status.code = 503) or (response.status.code = 400)</Condition>
            <Name>MaintenancePolicy</Name>
        </Step>
    </Response>
</Flow>