流程呼叫政策

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

查看 Apigee Edge 說明文件。

使用 FlowCallout 政策，從 API Proxy 或另一個共用流程呼叫共用流程。

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

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

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

注意：如要進一步瞭解共用流程，請參閱「可重複使用的共用流程」。您也可以從 API Proxy 程式碼外部呼叫共用流程，針對部署在環境中的所有 API Proxy，強制執行要求前置處理或回應後置處理。詳情請參閱「使用流程掛鉤附加共用的流程」。

範例

在共用流程中驗證 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>

API Proxy 中使用的下列 FlowCallout 政策會呼叫上述共用流程，以驗證 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 政策會定義參數，指定字串輸入、輸出內容，以及如何處理輸入內容。

1. 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>

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

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

3. 在共用流程中，下列 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>

4. 下列 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);

5. 執行作業會從 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 屬性值。
存在必要性	選用
類型	字串

<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>
<!- An 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>

預設	不適用
存在必要性	選用
類型	不適用

屬性

無

結構定義

範例：如需最新結構定義，請參閱 GitHub 存放區範例。

流程變數

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

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

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則來處理錯誤，就必須瞭解這項資訊。如需更多資訊，請參閱「 政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

提示：需要協助解決錯誤嗎？ 按一下「修正」欄中的 ，即可查看詳細的疑難排解資訊。

使用 API 監控功能，調查錯誤代碼並加快診斷問題的速度。

錯誤代碼	HTTP 狀態	原因	修正
flow.SharedFlowNotFound	500	共用流程不存在，或是共用流程存在但未部署。

部署錯誤

不適用

相關主題

• 建立共用流程： 可重複使用的共用流程
• 在多個 Proxy 中執行共用流程： 使用流程掛鉤附加共用流程