FlowCallout ポリシー

FlowCallout ポリシーを使用して、API プロキシまたは別の共有フローから共有フローを呼び出すことができます。

共有フローでは、実行時に複数の場所から再利用できる一連のステップを作成します。これらのステップは、API プロキシ内でポリシーとして実装されます。FlowCallout ポリシーを使用すると、API プロキシや他の共有フローから共有フローを呼び出すことができます。これは、従来のプログラミング言語の関数呼び出しのように機能します。

  • たとえば、API キー検証、OAuth トークン検証、正規表現保護などのセキュリティ機能を使用して共有フローを構築したとします。この共有フローは、受信リクエストをチェックするための規約を表しています。FlowCallout ポリシーを使用すると、複数の API プロキシから該当する共有フローを呼び出すことができます。
  • 共有フロー内から FlowCallout ポリシーを実装することにより、別の共有フローを呼び出すことができます。

サンプル

共有フローの API キーを確認する

この例では、共通のセキュリティ関連タスクを実行するために共有フローが使用されています。ここで共有フローは API キーを検証します。API プロキシや他の共有フローは、この共有フローに呼び出しを行うために、FlowCallout ポリシーを使用できます。

次の共有フロー定義には、API プロキシの FlowCallout ポリシーから共有フローが呼び出されたときに実行される Verify-API-Key ポリシーが含まれています。

<?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 プロキシで使用される次の FlowCallout ポリシーは、上記の共有フローを呼び出して API キーを検証します。verify-apikey-shared 共有フローバンドル(ここでは省略)は、APIProxy バンドルでプロキシを構成する方法で共有フローを構成します。

<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 共有フローには、FlowCallout ポリシーから共有フローが呼び出されたときに実行される 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 ポリシーから実行されます。このスクリプトでは、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 プロキシの 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 文字を超える値を指定することはできません。

必要に応じて、管理 UI プロキシ エディタで <DisplayName> 要素を使用してポリシーに別のわかりやすい名前でラベルを付けます。

なし 必須
continueOnError

ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される動作です。

ポリシーが失敗してもフロー実行を続行するには、true に設定します。

false 省略可
enabled

ポリシーを適用するには true に設定します。

ポリシーを無効にするには false に設定します。その場合、ポリシーはフローに接続されていているとしても適用されません。

true 省略可
async

この属性は非推奨となりました。

false 非推奨

<DisplayName> 要素

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

<DisplayName>Policy Display Name</DisplayName>
デフォルト:

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます

要否: 省略可
型: 文字列

<SharedFlowBundle> 要素

呼び出す共有フローの名前を指定します。この要素の値は、対象の SharedFlowBundle 要素の name 属性の値と同じである必要があります。

<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>
デフォルト なし
要否

省略可。

なし

属性

なし。

スキーマ

フロー変数

フロー変数を使用すると、ポリシーとフローの実行中に HTTP ヘッダー、メッセージ コンテンツ、またはフロー コンテキストに基づいた動的な振る舞いを持たせることが可能です。フロー変数の詳細については、変数リファレンスをご覧ください。

変数 説明

apigee.edge.sharedflow.name

スコープ: 共有フローの実行中
: 文字列
権限: 読み取り

共有フローの name 属性の値。

apigee.edge.flowhook.name

スコープ: フローフックに接続された共有フローの実行中。
: 文字列
権限: 読み取り

フローフックの名前。

エラー リファレンス

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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

関連トピック