使用流程變數

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

概念上來說，流程變數是可透過政策或公用程式 (例如追蹤工具工具) 存取的物件。可讓您保留與 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 流程，這項政策會設定傳送至後端目標的標頭。如果已在 response 流程上設定，系統就會將標頭傳回用戶端應用程式。

<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 以動態方式運作。條件通常用於變更流程、步驟和轉送規則的行為。

以下條件式流程可以評估 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 Proxy 流程相關聯的內容物件。舉例來說，此程式碼會使用從流程變數 target.name 取得的值設定回應標頭。

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

使用 JavaScript 讀取及設定變數的技術與 AssignMessage 政策的工作類似 (如前文所述)。這只是另一種在 Edge 上完成相同工作的方式關鍵在於，JavaScript 政策執行的 JavaScript 可存取 API Proxy 流程中存在且位於「範圍」的所有流程變數。

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 中存取流程變數」。

瞭解流程變數範圍

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

視覺化呈現 API Proxy 的流程

如要瞭解流程變數範圍，請務必瞭解或視覺化訊息透過 API Proxy 傳送的方式。API Proxy 包含一系列訊息處理步驟，經整理為流程。Proxy 流程中的每個步驟都會評估可用的資訊，並決定後續行動。Proxy 可能會在過程中執行政策程式碼或執行條件分支。

下圖說明一系列的流程。請注意資料流是由四個主要區段組成：ProxyEndpoint request、TargetEndpoint request、TargetEndpoint response 和 ProxyEndpoint response。

開始探索本主題其他部分的流量變數時，請特別留意這個流程結構。

變數範圍與 Proxy 流程的關係

只要能像前文所述，視覺化呈現訊息透過 Proxy 傳送的方式，就可以開始瞭解變數範圍。根據範圍，我們是指某個變數首次執行個體化時，Proxy 流程生命週期中的時間點。

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

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

變數範圍 系統會在這裡填入這些變數
Proxy 要求 ProxyEndpoint 要求區隔
目標要求 TargetEndpoint 要求區隔
目標回覆 TargetEndpoint 回應區隔
Proxy 回應 ProxyEndpoint 回應區段
隨時保持運作 Proxy 收到要求後立即執行。這些變數可在整個 Proxy 流程的生命週期中使用。

例如，有一個名為 client.ip 的內建 Edge 變數。這個變數的範圍為「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 程式碼中參照流程變數。詳情請參閱：

流程變數的資料類型

流程變數的每個屬性都有明確定義的資料類型，例如 String、Long、Integer、Boolean 或 Collection。如需資料類型，請參閱流程變數參考資料。如需依據政策建立的變數，請參閱特定政策參考資料主題，瞭解資料類型資訊。

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

在政策中使用流程變數

許多政策會在正常執行過程中建立流程變數。政策參考資料記錄了這些政策專屬的變數。

使用 Proxy 和政策時，請務必參閱政策參考資料，瞭解已建立的變數以及用途。例如，配額政策會建立一組變數，其中包含配額次數、限制、到期時間等相關資訊。

有些政策變數適合用於偵錯。舉例來說，您可以使用「追蹤工具」工具，查看 Proxy 流程中特定執行個體設定的變數。

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

在以下範例中，「擷取變數」會剖析回應訊息，並儲存從回應中擷取的特定資料。這項政策會建立兩個自訂變數 (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 程式碼中使用流程變數

您可以直接透過在 API Proxy 環境執行的 JavaScript 程式碼中存取及設定變數。透過 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 物件建立，因此適用於所有流程區隔 (基本上與建立全域變數類似)。

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

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

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

注意事項

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

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

相關程式碼範例

API Proxy 範例位於 GitHub，方便您下載及使用。如需下載並安裝範例的相關資訊，請參閱「使用範例 API Proxy」。如需 API Proxy 範例的說明及其用途，請參閱範例清單。

使用變數和變數處理功能的範例 Proxy 包括：

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

相關主題

  • 在 API Proxy 中自動填入的所有變數都列於流程變數參考資料中。這份參考資料也會列出每個變數的類型和範圍。
  • 如要瞭解特定政策填入的變數，請參閱政策的參考主題。例如，請參閱配額政策參考資料中的流程變數一節。