FlowCallout ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントはこちらをご覧ください。

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

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

• たとえば、API キー検証、OAuth トークンの検証、正規表現保護などのセキュリティ機能のある共有フローを構築したとします。この共有フローは、インバウンド リクエストの確認方法を示しています。FlowCallout ポリシーを使用すると、複数の API プロキシからその共有フローを呼び出すことができます。
• 共有フロー内から FlowCallout ポリシーを実装することで、別のフローから特定の共有フローを呼び出せます。

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

注: 共有フローの詳細については、再利用可能な共有フローをご覧ください。また、外部の API プロキシコードから共有フローを呼び出して、環境にデプロイされているすべての API プロキシにリクエストの前処理やレスポンスの後処理を実行させることも可能です。詳細については、フローフックを使用した共有フローの接続をご覧ください。

サンプル

共有フローの 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 に設定します。関連項目: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について） 現在のフローにおける障害処理	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>

デフォルト	該当なし
要否	省略可
型	なし

属性

なし。

スキーマ

サンプル: 最新のスキーマについては、GitHub リポジトリのサンプルをご覧ください。

フロー変数

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

変数	説明
apigee.edge.sharedflow.name	スコープ: 共有フローの実行中 型: 文字列 権限: 読み取り 共有フローの name 属性の値。
apigee.edge.flowhook.name	スコープ: フローフックに接続された共有フローの実行中。 型: 文字列 権限: 読み取り フローフックの名前。

エラー リファレンス

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

ランタイム エラー

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

ヒント: エラーの解決にサポートが必要な場合は、「修正」列の をクリックして、詳しいトラブルシューティング情報をご覧ください。

API Monitoring を使用して障害コードについて調査し、問題をより迅速に診断してください。

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

デプロイエラー

なし

関連トピック

• 共有フローの作成: 再利用可能な共有フロー
• 複数のプロキシ間での共有フローの実行: フローフックを使用した共有フローの接続