您正在查看 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 - 根據變數值實作簡易的條件政策強制執行。