使用流程變數

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。info

從概念上來說，流程變數是您可以在政策或公用程式 (例如 Trace 工具) 中存取的物件。讓您可以保留與 Apigee Edge 處理的 API 交易相關聯的狀態。

什麼是流程變數？

流程變數會在 API Proxy 流程環境內存在，且會用具名變數在軟體程式中追蹤狀態的方式追蹤 API 交易中的狀態。流程變數會儲存下列資訊：

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

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

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

如何使用流程變數？

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

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

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

  • 條件式流程可以參照流程變數，藉此透過 Edge 引導 API 流程，類似切換陳述式在程式設計中的運作方式。

    舉例來說，只有在設定特定流程變數時，系統才會執行返回錯誤的政策。最後，您可以在 Node.js 目標應用程式中取得及設定流程變數。

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

政策中的流程變數

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

舉例來說，下列 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 的流程變數 (這是 Edge 內建的其中一個變數) 而定。

條件式流程中的流程變數

條件式流程會評估流程變數，並讓 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 等變數來自何處？何時會例項化並填入值？如要瞭解變數的建立時間和可用時間，請參閱「瞭解流程變數的範圍」。

使用 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 政策 (如上所述) 執行的工作類似。這只是在 Edge 上執行相同類型作業的另一種方式。請記住，由 JavaScript 政策執行的 JavaScript 可存取 API 代理程式資料流中所有存在且位於範圍內的資料流變數。

Node.js 程式碼中的流程變數

只要要求 apigee-access 模組，您就可以在部署至 Edge 的 Node.js 程式碼中設定及存取資料流變數。

以下是簡單的範例，其中 custom.foo 變數設為 Bar 值。設定完成後，這項新變數就會在 Node.js 程式碼執行後，提供給 Proxy 流程中的任何政策或其他程式碼。

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

如要進一步瞭解如何使用 apigee-access 處理變數，請參閱「在 Node.js 中存取流程變數」。

瞭解流程變數範圍

變數 scope 與 API Proxy 呼叫的流程或整體「生命週期」相關。

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

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

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

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

變數範圍與 Proxy 流程的關係

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

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

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

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

舉例來說，Edge 內建一個名為 client.ip 的變數。這個變數具有「Proxy 要求」範圍。系統會自動填入呼叫 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 回應上，因為回應變數的範圍為「目標回應」。

參照流程變數

Apigee Edge 中的所有內建變數都遵循點標示命名慣例。這項慣例可讓您更輕鬆地判斷變數的用途。例如 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、整數、布林值或集合。您可以在流程變數參考資料中找到列出的資料類型。如果變數是由政策建立，請參閱特定政策參考主題，瞭解資料類型資訊。

您手動建立的變數會假設建立時指定的類型，並取決於允許的值類型。舉例來說，在 Node.js 程式碼中建立的變數只能是 Number、String、Boolean、null 或 undefined。

在政策中使用流程變數

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

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

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

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

在以下範例中，「Extract Variables」會剖析回應訊息，並儲存從回應中擷取的特定資料。這項政策會建立 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 Proxy 的執行環境中執行。透過 Apigee JavaScript 物件模型，在 Edge 上執行 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 物件建立，因此可供所有流程區隔使用 (基本上就像建立全域變數一樣)。

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

在 Node.js 應用程式中存取流程變數

您可以從部署至 Edge 的 Node.js 程式碼中取得、設定及刪除流程變數。您只需在程式碼中「要求」apigee-access 模組即可。詳情請參閱在 Node.js 中存取流程變數。

重要事項

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

  • 某些「現成」變數會由 Proxy 本身自動例項化及填入。相關資訊請參閱流程變數參考資料。
  • 您可以建立可在 Proxy 流程中使用的自訂變數。您可以使用 AssignMessage 政策和 JavaScript 政策等政策，以及在 Node.js 程式碼中建立變數。
  • 變數有範圍。舉例來說，當第一個 Proxy 收到應用程式的要求時，系統會自動填入部分變數。其他變數則會填入 Proxy 的回應流程區段。在回應片段執行前，這些回應變數仍未定義。
  • 政策執行時，可以建立並填入政策專屬變數。每項政策的說明文件都會列出所有相關的政策專屬變數。
  • 條件式流程通常會評估一或多個變數。如要建立條件式動態表單，您必須瞭解變數。
  • 許多政策會使用變數做為輸入或輸出內容。也許某個政策建立的變數會在日後由其他政策使用。
  • 您可以使用純 JavaScript (以及我們的 JavaScript 物件模型) 或在 Edge 上執行程式的 JavaCallout 政策，在 Node.js 中取得及設定許多流程變數。

相關程式碼範例

API Proxy 範例位於 GitHub 上，方便下載及使用。如要進一步瞭解如何下載及使用範例，請參閱「使用 API 範例 Proxy」一文。如需 API 代理程式範例的說明，請參閱範例清單。

以下是使用變數和變數處理的範例代理程式：

  • 變數：示範如何根據傳輸和 JSON 和 XML 訊息內容，擷取及設定變數。
  • policy-mashup-cookbook：完整應用程式，可使用政策組合來呼叫兩個公開 API、結合結果，並為用戶端應用程式產生豐富的回應。如要進一步瞭解這個範例，請參閱「使用政策組合」。
  • conditional-policy - 根據變數值實作簡單的條件政策強制執行。

相關主題

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