使用流程變數

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

流程變數是指您可以在政策或公用程式 (例如偵錯工具) 中存取的物件。可讓您維護與 Apigee 處理的 API 交易相關聯的狀態。

什麼是流程變數？

資料流變數會出現在 API Proxy 資料流的內容中，並以命名變數追蹤軟體程式中的狀態，以便追蹤 API 交易中的狀態。流程變數會儲存下列資訊：

  • 來自要求應用程式的 IP 位址、標頭、網址路徑和酬載
  • 系統資訊，例如 Apigee 收到要求的日期和時間
  • 政策執行時衍生的資料。舉例來說，在驗證 OAuth 權杖的政策執行後，Apigee 會建立流程變數，用於儲存要求應用程式名稱等資訊。
  • 目標系統的回應資訊

部分變數已內建於 Apigee 中，並會在收到 API 要求時自動填入。這些值可在整個 API 交易中使用。您也可以使用「AssignMessage」政策等政策，或在 JavaScript 和 Java 程式碼中，建立自訂變數。

如您所見，變數具有範圍，且可存取的位置取決於在 API Proxy 流程中建立變數的時間。一般來說，建立變數後，後續在 API 交易流程中執行的所有政策和程式碼都能使用該變數。

如何使用流程變數？

流程變數可用於政策和條件式流程：

  • 政策可從工作流程變數擷取狀態，並使用這些變數執行工作。

    舉例來說，VerifyJWT 政策可從流程變數擷取要驗證的權杖，然後對其執行驗證。舉另一個例子來說，JavaScript 政策可以擷取流程變數，並對這些變數內含的資料進行編碼。

  • 條件式流程可參照流程變數，透過 Apigee 引導 API 的流程，類似於程式設計中 switch 陳述式的運作方式。

    舉例來說，只有在設定特定流程變數時，系統才會執行用來傳回錯誤的政策。

我們來看看變數在這些情境中的使用方式。

政策中的流程變數

部分政策會將流程變數做為輸入內容。

舉例來說，下列 AssignMessage 政策會取得流程變數 client.ip 的值，並將其放入名為 My-Client-IP 的要求標頭中。如果加入「request」流程中，這項政策會設定要傳遞至後端目標的標頭。如果在回應流程中設定，標頭會傳回至用戶端應用程式。

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

舉例來說，當配額政策執行時，系統會在多個流程變數中填入與政策相關的值。其中一個變數稱為 ratelimit.my-quota-policy.used.count (my-quota-policy 是您感興趣的配額政策名稱)。

您之後可以執行條件式流程，指出「如果目前配額數量低於上限的 50%，且時間介於上午 9 點至下午 5 點，則強制執行其他配額」。這個條件可能會依據目前配額計數的值，以及名為 system.time 的流程變數 (這是內建 Apigee 變數之一) 而定。

條件式流程中的流程變數

條件式流程會評估流程變數，並讓 Proxy 以動態方式運作。條件通常用於變更流程、步驟和路徑規則的行為。

以下是評估代理程式流程步驟中變數 request.verb 值的條件式流程。在這種情況下，如果要求動詞為 POST，系統會執行 VerifyAPIKey 政策。這是 API Proxy 設定中常見的模式。

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

您可能會好奇，request.verb、client.ip 和 system.time 這類變數來自何處？何時會例項化並填入值？如要瞭解變數的建立和使用時機，請參閱「以視覺化方式呈現 API Proxy 的流程」。

使用 JavaScript 政策呼叫的 JavaScript 程式碼中的流量變數

您可以使用 JavaScript 政策，在 API Proxy 流程的內容中執行 JavaScript 程式碼。這項政策執行的 JavaScript 會使用 Apigee 的 JavaScript 物件模型，讓自訂程式碼可以存取與執行程式碼的 API 代理程式流程相關聯的請求、回應和內容物件。舉例來說，這段程式碼會使用從資料流變數 target.name 取得的值，設定回應標頭。

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));

使用 JavaScript 讀取及設定變數的這項技巧，與您可以透過AssignMessage 政策 (如上所述) 執行的工作類似。這只是在 Apigee 上執行相同類型作業的另一種方式。請記住，由 JavaScript 政策執行的 JavaScript 可存取 API 代理程式資料流中存在且位於範圍內的所有資料流變數。

以視覺化方式呈現 API Proxy 的流程

如要瞭解流程變數範圍，請務必瞭解或以視覺化方式呈現訊息透過 API Proxy 流動的情況。API Proxy 包含一系列訊息處理步驟，並以流程的形式進行排序。在 Proxy 流程中的每個步驟中，Proxy 會評估可用的資訊，並決定下一步要採取哪些行動。在此過程中，Proxy 可能會執行政策程式碼或條件式分支。

下圖說明瞭這個流程的順序。請注意，流程由四個主要部分組成：ProxyEndpoint request、TargetEndpoint request、TargetEndpoint response 和 ProxyEndpoint response。

HTTP 用戶端要求會透過 API Proxy 傳送至 HTTP 服務，然後回應會透過 API Proxy 傳回給用戶端。

請記住這個流程結構，我們將在本主題的其餘部分開始探討流程變數。

變數範圍與 Proxy 流程的關聯

如前文所述，只要您能以視覺化方式瞭解訊息如何透過 Proxy 流動，就能開始瞭解變數的作用範圍。所謂的「範圍」是指代理程式流程生命週期中，變數首次例項化的時間點。

舉例來說，如果您將政策附加至 ProxyEndpoint 要求區段，該政策就無法存取任何設為 TargetEndpoint 要求區段的變數。這是因為流程的 TargetEndpoint 要求區段尚未執行，因此 API Proxy 無法在該範圍內填入變數。

下表列出完整的變數範圍，並指出這些變數在 Proxy 流程中可供使用的時間。

變數範圍 這些變數的填入位置
Proxy 要求 ProxyEndpoint 要求區段
指定目標要求 TargetEndpoint 要求區段
目標回應 TargetEndpoint 回應區段
Proxy 回應 ProxyEndpoint 回應區段
隨時可用 代理程式收到要求後，這些變數可在整個 Proxy 流程生命週期中使用。

舉例來說，有一個名為 client.ip 的內建 Apigee 變數。這個變數具有proxy request 範圍。系統會自動填入呼叫 Proxy 的用戶端 IP 位址。當要求首次命中 ProxyEndpoint 時，系統會填入這項資訊，並在整個 Proxy 流程生命週期中持續提供。

還有另一個內建變數 target.url。這個變數的範圍是目標要求。系統會在 TargetEndpoint 要求區段中填入這項資訊，並將要求網址傳送至後端目標。如果您嘗試在 ProxyEndpoint 要求片段中存取 target.url，就會收到 NULL 值。如果您嘗試在變數範圍內設定這個變數，Proxy 就不會執行任何動作，也不會產生錯誤或設定變數。

以下是簡單的範例，說明如何思考變數作用範圍。假設您想複製要求物件 (標頭、參數、主體) 的完整內容，並將其指派給回應酬載，以便傳回至呼叫應用程式。您可以使用 AssignMessage 政策執行此項工作。政策代碼如下所示：

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

這項政策只會複製 request 物件，並將其指派給 response 物件。不過，這項政策應置於 Proxy 流程中的哪個位置？答案是必須放在 TargetEndpoint 回應上，因為回應變數的範圍是 target response。

參照流程變數

Apigee 中的所有內建變數都遵循點標示命名慣例。這項慣例可讓您更輕鬆地判斷變數的用途。例如 system.time.hour 和 request.content。

Apigee 會保留各種前置字串，以便適當地整理相關變數。這些前置字串包括：

  • request
  • response
  • system
  • target

如要在政策中參照變數，請將其括在大括號內。舉例來說，下列 AssignMessage 政策會採用變數 client.ip 的值，並將其放入名為 Client-IP 的要求標頭中。

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

在條件式流程中，不必使用大括號。以下範例條件會評估變數 request.header.accept：

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

您也可以在 JavaScript 和 Java 程式碼中參照流程變數。如需詳細資訊，請參閱：

流程變數的資料類型

流程變數的每個屬性都有明確的資料類型，例如字串、Long、整數、布林值或集合。您可以在流程變數參考資料中找到列出的資料類型。如果變數是由政策建立，請參閱特定政策參考主題，瞭解資料類型資訊。

您手動建立的變數會假設建立時指定的類型，並取決於允許的值類型。

在政策中使用流程變數

許多政策會在正常執行時建立流程變數。政策參考資料會記錄所有這些政策專屬變數。

使用 Proxy 和政策時，請務必參閱政策參考資料，瞭解系統會建立哪些變數，以及這些變數的用途。舉例來說，配額政策會建立一組變數，其中包含配額數量和限制、到期時間等資訊。

部分政策變數非常適合用於偵錯。您可以使用 偵錯工具，查看代理程式流程中特定例項設定了哪些變數。

ExtractVariables 政策可讓您使用從訊息中擷取的資料填入自訂變數。您可以擷取查詢參數、標頭和其他資料。舉例來說，您可以使用模式剖析要求和回應訊息，從訊息中擷取特定資料。

在以下範例中，「ExtractVariables」政策會剖析回應訊息，並儲存從回應中擷取的特定資料。這項政策會建立兩個自訂變數 geocoderesponse.latitude 和 geocoderesponse.longitude，並指派值給這些變數。

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

請注意，許多政策會自動建立變數。您可以在 Proxy 流程內容中存取這些變數，這些變數會記錄在各個政策主題下的政策參考資料中。

在 JavaScript 程式碼中使用流程變數

您可以直接在 JavaScript 程式碼中存取及設定變數，這些程式碼是在 API 代理程式執行的情況下執行。透過 Apigee 的 JavaScript 物件模型，在 Apigee 上執行的 JavaScript 可直接存取 Proxy 流程變數。

如要存取 JavaScript 程式碼中的變數，請對下列任一物件呼叫 getter/setter 方法：

  • context
  • proxyRequest
  • proxyResponse
  • targetRequest
  • targetResponse

如您所見，這些物件參照會對應至 Proxy 流程模型的常見區段，如先前在「以視覺化方式呈現 API Proxy 的流程」一文中所述。

context 物件對應至全域可用的變數，例如系統變數。舉例來說，您可以對 context 物件呼叫 getVariable()，取得目前的年份：

var year = context.getVariable('system.time.year');

同樣地，您可以呼叫 setVariable() 來設定自訂變數或任何可寫入的即用型變數的值。我們在此建立名為 organization.name.myorg 的自訂變數，並為其指派值。

var org = context.setVariable('organization.name.myorg', value);

由於這個變數是使用 context 物件建立，因此可供所有流程區隔使用 (基本上，這就像建立全域變數)。

您也可以在使用 JavaCallout 政策執行的 Java 程式碼中，取得或設定 Proxy 流程變數。

注意事項

以下是流程變數的幾個重要注意事項：

  • 某些out-of-the-box變數會由 Proxy 自動例項化並填入。如需詳細資訊，請參閱流程變數參考資料。
  • 您可以建立自訂變數，用於代理流程中。您可以使用 AssignMessage 政策和 JavaScript 政策等政策建立變數。
  • 變數有範圍。舉例來說，當第一個 Proxy 收到應用程式的要求時，系統會自動填入部分變數。其他變數則會填入 Proxy 的回應流程區段。在回應片段執行前，這些回應變數仍未定義。
  • 政策執行時，可以建立並填入政策專屬變數。每項政策的說明文件都會列出所有相關的政策專屬變數。
  • 條件式流程通常會評估一或多個變數。如要建立條件式動態表單，您必須瞭解變數。
  • 許多政策都會使用變數做為輸入或輸出內容。也許某個政策建立的變數會在日後由其他政策使用。

相關主題

  • 所有在 API 代理中自動填入的變數都會列在 流程變數參考資料中。參考資料也會列出每個變數的類型和範圍。
  • 如要瞭解特定政策會填入哪些變數，請參閱該政策的參考主題。例如，請參閱配額政策參考資料中的「流程變數」。