FlowCallout 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

使用 FlowCallout 政策可从 API 代理或其他共享流调用共享流。

在共享流中，您将创建一系列步骤，您可以在多个位置的运行时重复使用这些步骤。这些步骤以政策的形式实现，就像在 API 代理中一样。FlowCallout 政策可让您从 API 代理和其他共享流中调用共享流。 其工作原理与传统编程语言的函数调用相似。

• 例如，假设您已经构建一个具有安全功能（如 API 密钥验证、OAuth 令牌验证和正则表达式保护）的共享流。此共享流表示用于检查入站请求的方式的惯例。使用 FlowCallout 政策，您可以从多个 API 代理调用该共享流。
• 您可以通过在共享流中实现 FlowCallout 政策，来从另一个共享流中调用一个共享流。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

注意：如需详细了解共享流，请参阅可重复使用的共享流。您还可以从 API 代理代码外部调用共享流，从而对部署在环境中的所有 API 代理强制执行请求预处理或响应后处理。如需了解详情，请参阅使用流钩子附加共享流。

示例

在共享流中验证 API 密钥

在此示例中，共享流用于执行与安全相关的常见任务。此处，共享流会验证 API 密钥。API 代理和其他共享流可以使用 FlowCallout 政策调用此共享流。

以下共享流定义包括 Verify-API-Key 政策，该政策在从 API 代理中的 FlowCallout 政策调用共享流时执行。

<?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 共享流包含一个 SharedStringFunctions JavaScript 政策，该政策会在从 FlowCallout 政策调用共享流时执行。

   <?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 个字符。 （可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。	不适用	必填
continueOnError	设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。 设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅： 故障规则仅在错误状态下触发（关于 continueOnError） 处理当前流中的故障	false	可选
enabled	设置为 true 可强制执行政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。	true	可选
async	此特性已弃用。	false	已弃用

<DisplayName> 元素

除了用于 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	范围：在共享流执行期间 类型：字符串 权限：读取 共享流名称特性的值。
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

相关主题

• 创建共享流：可重复使用的共享流
• 在多个代理上执行共享流：使用流钩子附加共享流