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> 要素

管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<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

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

フローフックの名前。

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Edge によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきこと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス 原因 解決方法
flow.SharedFlowNotFound 500 共有フローが存在しません。あるいは、共有フローは存在していますが、デプロイされていません。

デプロイエラー

なし

関連トピック