流程呼叫政策

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

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

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

  • 舉例來說,假設您建構了一個包含安全性功能 (例如 API 金鑰驗證、OAuth 權杖驗證和規則運算式防護) 的共用流程,這個共用流程代表您檢查傳入要求的慣例。使用流程呼叫政策,您可以從多個 API Proxy 叫用共用的流程。
  • 您可以從共用流程中實作資料流呼叫政策,藉此呼叫另一個共用流程。

範例

在共用流程中驗證 API 金鑰

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

以下共用流程定義包含 Verify-API-Key 政策,該政策會在 API Proxy 中的 FlowCTA 政策呼叫共用流程時執行。

<?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 中使用的流程呼叫政策會呼叫先前的共用流程,以驗證 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>

將參數傳遞至共用流程

這個範例說明如何將參數從資料流呼叫政策傳送至共用流程。這裡,向共用流程呼叫流程呼叫政策,目的是執行常見的字串處理函式。共用流程包含可將輸入內容串連輸入內容的 JavaScript,或是兩者並用小寫。資料流呼叫政策會定義參數,用於指定字串輸入和輸出內容,以及輸入內容的處理方式。

  1. String-Handler 流程呼叫政策會呼叫共用流程,傳遞參數來指定儲存共用流程輸出內容的變數、要使用的共用流程作業,以及要使用的輸入內容 (此處為字串常值,但也可以是流程變數)。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 政策,此政策會在透過資料流呼叫政策呼叫共用流程時執行。

    <?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 政策執行。這個指令碼會從 Flow callout 政策 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 async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <SharedFlowBundle>thereferencedsharedflowbundle</SharedFlowBundle>
</FlowCallout>

<Flow callout> 屬性

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

下表說明所有政策父項元素的通用屬性:

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和半形句號。這個值不得超過 255 個半形字元。

您也可以選擇使用 <DisplayName> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

如要強制執行政策,請設為 true

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

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

存在必要性 選用
類型 字串

<SharedFlowBundle> 元素

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

<SharedFlowBundle/>

在最簡單的範例中,您可以命名呼叫為此元素的值的共用流程名稱。也就是說,這個元素的值必須與共用流程的 name 屬性值相同。

<SharedFlowBundle>Shared-Flow-Name</SharedFlowBundle>
 
預設 不適用
外觀狀態

這是必填欄位。

類型 不適用

屬性

無。

<Parameter> 元素

指定要做為變數傳遞給此政策呼叫共用流程的參數和值 (或值來源)。

使用參數時,您可以指定一個值 (或包含值的變數),應傳送至政策呼叫的共用流程。從概念來看,這個做法與在函式呼叫中指定參數類似。與函式參數一樣,Flow callout 參數值可能會因共用流程呼叫的結構定義而異。

只有在共用流程執行期間才會顯示流程呼叫參數。

語法

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

<!- 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 流程呼叫政策會傳遞參數,指定儲存共用流程輸出內容的位置和要使用的輸入內容。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>
預設 不適用
外觀狀態

這是必填欄位。

類型 不適用

屬性

屬性 說明 預設 存在必要性 類型
名稱 要透過這個參數建立的執行階段變數名稱。 無。 這是必填欄位。 字串
參考資料

這個變數含有要在執行階段使用的值。如要指定要使用的常值,請省略這個屬性。

無。 選用。 字串
在透過這個參數建立的執行階段變數中使用的值。如要指定應為值來源的變數名稱,請省略這個屬性。 無。 選用。 字串

<Parameters> 元素

指定一組 <Parameter> 元素,該元素會做為變數傳遞給此政策呼叫的共用流程。

語法

<Parameters>
  <Parameter name="parameter-name" value='parameter-value' />
</Parameters>
預設 不適用
外觀狀態

選用。

類型 不適用

屬性

無。

結構定義

流程變數

流程變數可根據 HTTP 標頭、訊息內容或流程環境,在執行階段啟用政策和流程的動態行為。如要進一步瞭解流程變數,請參閱變數參考資料

變數 說明

apigee.edge.sharedflow.name

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

共用流程名稱屬性的值。

apigee.edge.flowhook.name

範圍:在連結至流程掛鉤的共用流程執行期間。
類型:字串
權限:讀取

資料流掛鉤的名稱。

錯誤參考資料

本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。如果您開發的錯誤規則來處理錯誤,請務必瞭解這些資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

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

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

部署錯誤

不適用

相關主題