流程呼叫政策

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

查看 Apigee Edge 說明文件。

使用 FlowCallout 政策，從 API Proxy 或其他共用流程呼叫共用流程。

在共用流程中，您可以建立一系列步驟，並在執行階段從多個位置重複使用。這些步驟會以政策的形式實作，就像在 API Proxy 中一樣。FlowCallout 政策可讓您從 API Proxy 和其他共用流程叫用共用流程。這項功能與傳統程式設計語言中的函式呼叫類似。

舉例來說，假設您已建構共用流程，其中包含 API 金鑰驗證、OAuth 權杖驗證和正規運算式保護等安全功能。這個共用流程代表您檢查傳入要求的慣例。您可以使用 FlowCallout 政策，從多個 API Proxy 叫用該共用流程。
您可以在共用流程中實作 FlowCallout 政策，從另一個共用流程呼叫共用流程。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

範例

在共用流程中驗證 API 金鑰

在這個範例中，共用流程用於執行常見的安全性相關工作。這裡的共用流程會驗證 API 金鑰。API Proxy 和其他共用流程可以使用 FlowCallout 政策呼叫這個共用流程。

下列共用流程定義包含 Verify-API-Key 政策，當共用流程從 API Proxy 中的 FlowCallout 政策呼叫時，就會執行該政策。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="default">
    <Step>
        <Name>Verify-API-Key</Name>
    </Step>
</SharedFlow>

前一個共用流程中的 VerifyAPIKey 政策會擷取並驗證鍵值。

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

下列 FlowCallout 政策用於 API Proxy 時，會呼叫上述共用流程來驗證 API 金鑰。verify-apikey-shared 共用流程套件 (此處未顯示) 會以 APIProxy 套件設定 Proxy 的方式設定共用流程。

<FlowCallout async="false" continueOnError="false" enabled="true" name="Auth-Flow-Callout">
    <DisplayName>Auth Flow Callout</DisplayName>
    <SharedFlowBundle>verify-apikey-shared</SharedFlowBundle>
</FlowCallout>

將參數傳遞至共用流程

這個範例說明如何將參數從 FlowCallout 政策傳遞至共用流程。在這裡，FlowCallout 政策會呼叫共用流程，執行常見的字串處理函式。共用流程包含 JavaScript，可串連輸入內容、將輸入內容轉換為小寫，或同時執行這兩項操作。FlowCallout 政策會定義參數，指定字串輸入、輸出內容，以及如何處理輸入內容。

String-Handler FlowCallout 政策會呼叫共用流程，並傳遞參數來指定要儲存共用流程輸出的變數、要使用的共用流程作業，以及要使用的輸入內容 (這裡是字串常值，但也可以是流程變數)。Parameter 元素會指定要建立執行階段的變數名稱和值。共用流程可以擷取這些變數，供自己的程式碼使用。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
  <DisplayName>String Handler</DisplayName>
  <Parameters>
    <Parameter name="input">Gladys Kravitz</Parameter>
    <Parameter name="operations">concatenate tolowercase</Parameter>
    <Parameter name="outputVariable">string.handler.output</Parameter>
  </Parameters>
  <SharedFlowBundle>StringHandler</SharedFlowBundle>
</FlowCallout>

下列default共用流程包含 SharedStringFunctions JavaScript 政策，會在從 FlowCallout 政策呼叫共用流程時執行。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="default">
  <Step>
    <Name>SharedStringFunctions</Name>
  </Step>
</SharedFlow>

在共用流程中，下列 SharedStringFunctions JavaScript 政策會指定 SharedStringFunctions.js JavaScript 檔案，其中包含要執行的程式碼。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="SharedStringFunctions">
  <DisplayName>SharedStringFunctions</DisplayName> <Properties/>
  <ResourceURL>jsc://SharedStringFunctions.js</ResourceURL>
</Javascript>

下列 JavaScript (SharedStringFunctions.js) 會從 SharedStringFunctions JavaScript 政策執行。這個指令碼會從 FlowCallout 政策 Parameter 元素建立的變數中擷取值。

// Input value from the calling API proxy.
var handledString = context.getVariable("input");
// Variable to use for output from this script.
var outputVariable = context.getVariable("outputVariable");
// A space-separated list of things to do to the input string.
// Convert to lower case to handle unintentional capitals in configuration.
var operation = context.getVariable("operations").toLowerCase();

// If "lowercase" was given as an operation, convert the input to lowercase.
if (operation.includes("tolowercase")) {
    handledString = handledString.toLowerCase();
}

// If "concatenate" was given as an operation, concatenate the input.
if (operation.includes("concatenate")) {
    handledString = handledString.replace(/\s+/g, '');
}
// Assign the resulting string to the output variable specified by
// the calling API proxy.
context.setVariable(outputVariable, handledString);

執行作業會從 JavaScript 政策返回共用流程，然後返回原始 API Proxy 中的 FlowCallout 政策。

元素參考資料

您可以在這項政策中設定下列元素和屬性：

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <SharedFlowBundle>thereferencedsharedflowbundle</SharedFlowBundle>
</FlowCallout>

<FlowCallout> 屬性

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">

下表說明所有政策父項元素的共同屬性：

屬性	說明	預設	存在必要性
`name`	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。您可以選擇使用 `<DisplayName>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。	不適用	必填
`continueOnError`	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
`enabled`	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
`async`	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>

預設

預設	不適用如果省略這個元素，系統會使用政策的 `name` 屬性值。
存在必要性	選用
類型	字串

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。

存在必要性選用

類型字串

<SharedFlowBundle> 元素

指定要呼叫的共用流程名稱。這個元素的值應與目標 <SharedFlowBundle> 元素的名稱屬性值相同。

<SharedFlowBundle/>

在最簡單的範例中，您會將要呼叫的共用流程名稱做為這個元素的值。也就是說，這個元素的值必須與共用流程的 name 屬性值相同。

<SharedFlowBundle>Shared-Flow-Name</SharedFlowBundle>

預設	不適用
狀態	必填
類型	不適用

屬性

無

<Parameter> 元素

指定要傳遞為變數的參數和值 (或值來源)，傳遞至這項政策呼叫的共用流程。

使用參數時，您可以指定應傳遞至政策所呼叫共用流程的值 (或含有值的變數)。這在概念上與在函式呼叫中指定參數類似。與函式參數相同，FlowCallout 參數的值會因共用流程呼叫的背景資訊而異。

FlowCallout 參數只會在共用流程執行期間顯示。

語法

您可以使用這個元素搭配下列任一語法形式。請注意，如果您使用常值，指定的值格式取決於使用該值的程式碼。

<!-- A literal value in an attribute. -->
<Parameter name="parameter-name" value='parameter-value' />
<!-- A reference to a variable in an attribute. -->
<Parameter name="parameter-name" ref='source-variable-name' />
<!-- A literal value in the element content. -->
<Parameter name="parameter-name">parameter-value</Parameter>
<!-- A reference to an attribute in the element content. -->
<Parameter name="parameter-name">{source-variable-name}</Parameter>

範例

這項 String-Handler FlowCallout 政策會傳遞參數，指定共用流程輸出的儲存位置和要使用的輸入內容。Parameter 元素會指定要建立執行階段的變數名稱和值。共用流程可以擷取這些變數，供自己的程式碼使用。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
  <DisplayName>String Handler</DisplayName>
  <Parameters>
    <Parameter name="input">Gladys Kravitz</Parameter>
    <Parameter name="outputVariable">string.handler.output</Parameter>
  </Parameters>
  <SharedFlowBundle>StringHandler</SharedFlowBundle>
</FlowCallout>

預設	不適用
狀態	必填
類型	不適用

屬性

屬性	說明	預設	狀態	類型
`name`	要使用這個參數建立的執行階段變數名稱。	無	必填	字串
`ref`	包含要在執行階段使用的值的變數。如要指定要使用的常值，請省略這個屬性。	無	選用	字串
`value`	要在使用這個參數建立的執行階段變數中使用的值。如要指定應做為值來源的變數名稱，請省略這個屬性。	無	選用	字串

<Parameters> 元素

指定要當做變數傳遞至這項政策所呼叫共用流程的 <Parameter> 元素集。

語法

<Parameters>
  <Parameter name="parameter-name" value='parameter-value' />
</Parameters>

預設	不適用
狀態	選用
類型	不適用

屬性

無

結構定義

流程變數

流程變數可讓政策和流程在執行階段根據 HTTP 標頭、訊息內容或流程情境，動態調整行為。如要進一步瞭解流程變數，請參閱「變數參考資料」。

變數說明

變數	說明
`apigee.edge.sharedflow.name`	範圍：共用流程執行期間類型：字串權限：讀取共用流程名稱屬性的值。
`apigee.edge.flowhook.name`	範圍：執行附加至流程掛鉤的共用流程時。類型：字串權限：讀取流程掛鉤的名稱。

apigee.edge.sharedflow.name

範圍：共用流程執行期間
類型：字串
權限：讀取

共用流程名稱屬性的值。

apigee.edge.flowhook.name

範圍：執行附加至流程掛鉤的共用流程時。
類型：字串
權限：讀取

流程掛鉤的名稱。

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause	Fix
`flow.SharedFlowNotFound`	`500`	Either the shared flow does not exist, or the shared flow exists but is not deployed.

Deployment errors

N/A