使用流程變數

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

查看 Apigee Edge 說明文件。

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

快速入門： 如需所有流程變數及其屬性的完整清單，請參閱流程變數參考資料。

影片

注意：這部影片是使用舊版 Apigee UI 錄製，但概念仍然適用。

如要瞭解流程變數簡介，請觀看以下影片：

什麼是流程變數？

流程變數存在於 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 的要求標頭。如果加入要求流程，這項政策會設定傳遞至後端目標的標頭。如果是在回應流程中設定，標頭會傳回給用戶端應用程式。

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

以下是條件流程，可在 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 Proxy 流程相關聯的要求、回應和內容物件，而程式碼會在該流程中執行。舉例來說，這段程式碼會設定回應標頭，並使用從 Flow 變數 target.name 取得的值。

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

使用 JavaScript 讀取及設定變數的這項技術，與您可透過指派訊息政策執行的作業類似 (如先前所示)。這只是在 Apigee 上完成相同類型工作的另一種方式。請務必記住，JavaScript 政策執行的 JavaScript 可存取 API Proxy 流程中存在的所有流程變數，且這些變數都在範圍內。

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

如要瞭解流程變數範圍，請務必瞭解或以視覺化方式呈現訊息在 API Proxy 中的流動方式。API Proxy 包含一系列訊息處理步驟，這些步驟會以流程的形式整理。在 Proxy 流程的每個步驟中，Proxy 都會評估可用的資訊，然後決定下一步該怎麼做。在此過程中，Proxy 可能會執行政策程式碼或執行條件式分支。

下圖說明瞭這個流程順序。請注意，流程是由四個主要區段組成：ProxyEndpoint 要求、TargetEndpoint 要求、TargetEndpoint 回應和 ProxyEndpoint 回應。

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

延伸閱讀：如要進一步瞭解 Proxy 流程結構，請參閱「設定流程」。

變數範圍與 Proxy 流程的關聯

如先前所述，只要能將訊息流經 Proxy 的方式視覺化，您就能開始瞭解變數範圍。所謂的範圍，是指變數首次例項化的時間點，也就是 Proxy 流程生命週期中的某個時間點。

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

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

注意：在指定範圍內填入流程變數後，該變數在整個 Proxy 流程生命週期內都可使用。如果嘗試存取尚未在範圍內的變數，系統會傳回錯誤或 NULL 值。

變數範圍	這些變數的填入位置
Proxy 要求	ProxyEndpoint 要求區隔
目標要求	TargetEndpoint 要求區隔
目標回覆	TargetEndpoint 回應區隔
Proxy 回應	ProxyEndpoint 回應區段
隨時都能使用	Proxy 收到要求時。這些變數可在整個 Proxy 流程生命週期中使用。

舉例來說，Apigee 內建變數稱為 client.ip。這個變數具有Proxy 要求範圍。系統會自動填入呼叫 Proxy 的用戶端 IP 位址。當要求首次觸及 ProxyEndpoint 時，系統會填入這個值，並在整個 Proxy 流程生命週期中保持可用。

注意：所有內建 Apigee 變數的範圍都列在流程變數參考資料中。

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

注意：您可以設定部分政策，在存取未定義的變數時擲回錯誤或傳回 NULL。詳情請參閱各項政策的參考頁面。

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

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

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

參照流程變數

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

最佳做法：建立自訂流程變數時，Google 建議您使用點記號命名慣例。使用半形句號整理自訂變數的階層，會很有幫助。

舉例來說，approval.code 和 approval.status 可能都參照流程中的核准功能。

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 程式碼中參照流程變數。如需詳細資訊，請參閱：

• 在 JavaScript 程式碼中使用流程變數
• JavaScript 政策

流程變數的資料類型

流程變數的每個屬性都有明確定義的資料類型，例如字串、Long、整數、布林值或集合。如要查看資料類型清單，請參閱流程變數參考資料。如要瞭解政策建立的變數，請參閱特定政策參考主題，取得資料類型資訊。

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

在政策中使用流程變數

許多政策會在正常執行期間建立流程變數。「政策參考資料」文件列出所有政策專屬變數。

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

部分政策變數可用於偵錯。舉例來說，您可以使用 偵錯工具，查看在 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 程式碼中使用流程變數

您可以在 API Proxy 的環境中執行的 JavaScript 程式碼中，直接存取及設定變數。透過 Apigee JavaScript 物件模型，在 Apigee 上執行的 JavaScript 可直接存取 Proxy 流程變數。

注意：您可以使用 JavaScript 政策，從 Proxy 呼叫 JavaScript。

如要在 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 物件建立，因此適用於所有流程區隔 (基本上，這就像是建立全域變數)。

注意：「流程變數參照」會指出哪些變數可寫入，哪些變數為唯讀。詳情請參閱 JavaScript 物件模型。

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

注意事項

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

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

提示：您會看到許多以某種方式使用變數的範例。尋找使用 ExtractVariables 政策的政策，這類政策通常用於處理 Proxy 流程中的變數。

相關主題

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