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">

The following table describes attributes that are common to all policy parent elements:

Attribute	Description	Default	Presence
name	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
continueOnError	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow	false	Optional
enabled	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.	true	Optional
async	This attribute is deprecated.	false	Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Default	N/A If you omit this element, the value of the policy's name attribute is used.
Presence	Optional
Type	String

<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	スコープ: フローフックに接続された共有フローの実行中。 型: 文字列 権限: 読み取り フローフックの名前。

エラー リファレンス

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

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Use API Monitoring to investigate fault codes and diagnose issues faster.

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

関連トピック

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