FlowCallout 政策

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

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

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

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

示例

在共享流中验证 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,即使在政策失败后,仍可以继续执行流。

false 可选
enabled

设置为 true 可强制执行政策。

设为 false关闭政策。即使政策仍附加到某个流,也不会强制执行该政策。

true 可选
async

此特性已弃用。

false 已弃用

<DisplayName> 元素

除了用于 name 属性之外,还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>
默认

不适用

如果省略此元素,则会使用政策的 name 属性的值。

状态 可选
类型 字符串

<SharedFlowBundle> 元素

指定要调用的共享流的名称。此元素的值应与目标 SharedFlowBundle 元素名称特性的值相同。

<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

变量包含在运行时使用的值。如需指定要使用的字面量值,请忽略此特性。

无。 可选。 字符串
在使用此参数创建的运行时变量中使用的值。如果要指定应作为值源的变量的名称,请忽略此特性。 无。 可选。 字符串

<Parameters> 元素

指定一组 <Parameter> 元素作为变量传递给此政策调用的共享流。

语法

<Parameters>
  <Parameter name="parameter-name" value='parameter-value' />
</Parameters>
默认 不适用
状态

可选。

类型 不适用

属性

无。

架构

流变量

流变量可以在运行时基于 HTTP 标头、消息内容或流上下文启用政策和流的动态行为。如需详细了解流变量,请参阅变量参考

变量 说明

apigee.edge.sharedflow.name

范围:在共享流执行期间
类型:字符串
权限:读取

共享流名称特性的值。

apigee.edge.flowhook.name

范围:在将共享流附加到流钩子期间。
类型:字符串
权限:读取

流钩子的名称。

错误参考信息

本部分介绍了在此政策触发错误时返回的错误代码和错误消息,以及 Edge 设置的故障变量。在开发故障规则以处理故障时,请务必了解此信息。如需了解详情,请参阅您需要了解的有关政策错误的信息处理故障

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态 原因 修复
flow.SharedFlowNotFound 500 共享流不存在,或者共享流存在但尚未部署。

部署错误

不适用

相关主题