使用流控制 API 代理

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

流是构成 API 代理的基础组件通过流，您可以配置 API 代理执行政策和代码的顺序，从而对 API 的行为进行编程。

流是 API 请求处理路径上的顺序阶段。添加代理逻辑（例如用于验证 API 密钥）时，将逻辑添加为通过流指定的序列中的一个步骤。定义条件以指定逻辑是否执行以及何时执行时，将条件添加到流中。

下面的流配置示例定义了一个流，在其中，如果传入请求路径以 / 结尾且请求的 HTTP 动词为 GET，则 VerifyAPIKey 政策会执行。

<Flow name="Get Food Carts">
    <Description>Get Food Carts</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

流的 <Name> 元素中的 Verify-API-Key 值用于包括在代理的其他地方中通过 XML 配置的政策，如下所示：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <Properties/>
    <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

设计流程执行序列

您可以构建流，以便让逻辑沿着处理路径按正确的顺序执行。

注意：如需查看有关创建流的简单教程，请参阅构建第一个 API 代理。如需了解如何配置流的具体信息，请参阅配置流。

在决定要添加逻辑的位置时，首先需要选择是将它添加到代理端点还是目标端点。API 代理会将其代码拆分为与代理客户端（代理端点）交互的代码和与代理的后端目标（目标端点，如有）交互的可选代码。

两个端点都包含流，如下所述：

端点类型	说明	支持的流
ProxyEndpoint	包含离客户端最近的 API 代理流。提供逻辑位置以先处理来自客户端的请求，最后处理对客户端的响应。	PreFlow、条件流、PostFlow、PostClientFlow
TargetEndpoint	包含离后端资源最近的 API 代理流。提供逻辑位置以准备针对后端资源的请求，然后处理来自后端资源的响应。	PreFlow、条件流、PostFlow

您使用 XML 配置流，以指定应发生的情况和顺序。下图显示了如何在代理端点和目标端点中依序排定流的顺序：

代理端点和目标端点分别包含可以按以下顺序排列的流：

位置	流类型	说明
1	PreFlow	如果您需要确保某些代码在执行其他任何操作前执行，则非常有用。 如果 PreFlow 位于目标端点中，它会在代理端点的 PostFlow 之后执行。
2	条件流	条件逻辑的位置。在 PreFlow 之后且在 PostFlow 之前执行。 每个细分只执行一个条件流 - 条件计算结果为 true 的第一个流。这意味着，您可以作为下列每项的一部分执行一个条件流： ProxyEndpoint 的请求流水线 TargetEndpoint 的请求流水线 ProxyEndpoint 的响应流水线 TargetEndpoint 的响应流水线
3	PostFlow	该位置适合记录数据、发送通知以说明在处理请求时发生的某些事情等。在条件流和 PreFlow 后执行。 如果 PostFlow 位于代理端点中，并且存在目标端点，则代理端点 PostFlow 会在目标端点 PreFlow 之前执行。
4	PostClientFlow（仅限代理流）	响应返回到客户端后，用于记录消息的流。

先使用 PreFlow 执行代码

如果您需要确保某些代码在执行其他任何操作之前执行，则 PreFlow 非常有用。

在代理端点中，PreFlow 非常适合用来对客户端进行身份验证以及限制来自客户端的流量的代码。在目标端点中（在其中开始准备将请求发送到后端目标），PreFlow 非常适合作为准备发送请求的首要步骤。

例如，您一般不希望为已经超出配额的客户端提供服务。为了支持这些要求，您需要将安全和配额政策放入 PreFlow 细分中。这样一来，您无需担心在后续条件流中条件无法计算的问题。此流中的政策将始终先执行，然后再进行其他任何处理。

在下面的示例中，SpikeArrest 和 Quota 政策会先执行，然后再处理传递给条件流。

<PreFlow name="MyPreFlow">
    <Request>
        <Step>
            <Name>Spike-Arrest</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
</PreFlow>

使用条件流让代码有条件地执行

在 PreFlow 和 PostFlow 之间，您可以设置有条件地执行的流。这样一来，您将配置多个逻辑序列，但只有一个逻辑根据代理状态执行。如果您可以执行 PreFlow 或 PostFlow 中的所有逻辑并且不需要条件（换句话说，仅支持通过端点的一个路径），则条件流为可选。

每个流都指定了用于测试不同状态值的条件。这样可以根据条件有效地对执行进行分支。例如，您可能希望仅当请求的应用在移动设备上运行时，才将 XML 转换为 JSON。

注意：在条件流中，条件会在请求和响应中进行计算。请求和响应不能有单独的条件。仅执行一个条件流 - 条件为 true 的第一个流。

在这里，仅当请求是 GET 请求且 URI 模式为 /issue/**（/issue/ 以及 URI 中最后一个正斜线后的所有内容）时，才会强制执行配额约束。

<Flow name="MyFlow">
    <Description/>
    <Request>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>

您可以使用流变量来指定条件。如需详细了解如何在条件中使用变量，请参阅包含流变量的条件。

如需了条件中使用模式匹配的示例，请参阅模式匹配。

在核心逻辑之后使用 PostFlow 执行代码

PostFlow 非常适合在端点的核心逻辑之后且在端点处理完成之前执行操作。PostFlow 将在条件流和 PreFlow 之后执行。

PostFlow 非常适合记录某些数据、发送已发送事情的通知以及转换响应消息格式等。

在以下示例中，名为 SetResponseHeaders 的 AssignMessage 政策会在 Apigee 将响应发送回客户端之前设置响应消息的标题。

<PostFlow>
    <Response>
        <Step>
            <Name>SetResponseHeaders</Name>
        </Step>
    </Response>
 </PostFlow>

在客户端收到代理的响应后使用 PostClientFlow 立即执行代码

PostClientFlow 只能包含以下政策。PostClientFlow 中不能使用其他政策：

• FlowCallout 政策^*
• MessageLogging 政策
• ServiceCallout 政策

^* FlowCallout 政策只能调用其自身符合 PostClientFlow 标准条件的共享流程（即仅包含兼容的政策）。

如果您包含了一个政策，PostClientFlow 将是在将响应发送到客户端后最后一个执行的流。

PostClientFlow 适用于最终日志记录。此外，您还可以记录响应消息的开始和结束时间戳。

下面是附加了 MessageLogging 政策的 PostClientFlow 示例。

  <ProxyEndpoint name="endpoint1">
    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...
  </ProxyEndpoint>

如需了解详情，请参阅 API 代理配置参考文档。

将逻辑添加到流

将逻辑添加到流时，您可以通过将政策添加到代理的流来实现这一点。正如流按顺序执行（PreFlow 然后是 Flow，然后是 PostFlow，如本主题中所述）一样，流中的内容按顺序执行。

注意：如需详细了解政策（包括如何通过控制台和在代码中添加政策），请参阅政策是什么？如需详细了解如何将政策附加到流，请参阅条件流。

下面的示例流配置引用三个政策（在它们自己的 XML 文件中的其他位置配置）。Verify-API-Key 引用的政策在 Assign-Message 引用的政策之前执行；这两个政策都后跟 Quota 表示的政策。

<Flow name="Get Food Cart Menus">
  <Description>Get Food Cart Menus</Description>
  <Request>
    <Step>
      <Name>Verify-API-Key</Name>
    </Step>
    <Step>
      <Name>Assign-Message</Name>
    </Step>
    <Step>
      <Name>Quota</Name>
    </Step>
  </Request>
  <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

注意：在上述代码中，路径条件 (proxy.pathsuffix MatchesPath "/") 始终为 true，因为 "/" 始终匹配。因此，您可以将其从条件元素中移除，然后仅使用谓词条件：

    <Condition>request.verb = "GET"</Condition>

调试流

调试工具提供了一种图形方式来查看 API 代理中逻辑如何在请求后执行。该工具展示了请求和响应之间的处理过程。并未具体说明 PreFlow、条件流和 PostFlow 之间的分隔。

如需详细了解如何调试代理，请参阅使用调试工具。

处理流中的错误

您可以从 API 代理中的不同位置（包括从流中）引发错误。

下面的示例显示了从目标端点中的 PreFlow 返回的响应节 - 换言之，它是在收到后端目标的响应时立即执行的代码。在该示例中，如果来自目标的响应不是 200（成功），则会引发错误。

<PreFlow name="PreFlow">
    <Response>
        <Step>
            <Name>RaiseFault</Name>
            <Condition>(response.status.code GreaterThan "200")</Condition>
        </Step>
    </Response>
</PreFlow>

如需详细了解错误处理，请参阅处理错误。