API 代理配置参考文档

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

作为使用 Apigee Edge 的开发者,您的主要开发活动包括配置 API 代理以充当 API 或后端服务的代理。本文档介绍构建 API 代理时可用的所有配置元素的参考文档。

如果您正在了解如何构建 API 代理,建议您从构建简单 API 代理主题开始。

修改代理配置的最常用方式有:

代理配置的本地开发

您可以下载代理配置,以便在本地机器上修改配置。完成后,将结果上传到 Edge。通过此方法,您可以将代理配置集成到源代码控制、版本控制和其他共享工作流中。此外,通过在本地处理代理配置,您还可以使用自己的 XML 编辑器和验证工具。

本部分介绍如何使用界面下载现有的代理配置,对其进行修改,然后将其上传回 Edge 进行部署。您还可以使用 apigeetool 下载并部署新的代理配置(分别使用 fetchproxydeployproxy 命令)。

如需使用界面在本地修改代理配置,请执行以下操作

  1. 在 Edge 界面中下载当前代理配置。(在 API 代理视图中,选择项目 > 下载修订版本)。
  2. 在本地机器上,创建一个新目录,并在其中展开下载的 ZIP 文件。

    如需展开 ZIP 文件,您可以使用诸如 unzip 之类的实用程序,如以下示例所示:

    mkdir myappdir
    unzip ./my-app_app_rev3_2019_04_20.zip -d myappdir

    ZIP 文件的展开内容应与 API 代理结构中描述的结构类似。

  3. 根据需要修改源文件。如需了解代理配置中的源文件,请参阅 API 代理的配置文件和目录结构

    例如,如需在 API 代理中启用运行状况监控,请修改 /apiproxy/targets/ 目录中的 TargetEndpoint 配置文件。此目录中的默认文件是 default.xml,但如果您使用条件目标,则可能存在名称不同的文件。

    在这种情况下,如果 TargetEndpoint 配置文件及其目录不存在,请相应创建。

  4. 修改完代理配置文件后,务必保存您的更改。
  5. 切换到您在展开 ZIP 文件时创建的新目录(展开的配置文件的根目录)。

    例如,如果您将文件扩展到 /myappdir 目录,请切换到该目录,如以下示例所示:

    cd myappdir

    您应该先更改此目录,然后再重新归档代理配置文件,因为您不希望将 /myappdir 目录包括在 ZIP 文件中。ZIP 文件中的顶级目录必须是 /apiproxy

  6. 重新归档代理配置文件,包括新文件或更改后的文件。您可以使用 zip 等实用程序,如以下示例所示:
    zip my-new-proxy.zip -r .

    ZIP 文件中的顶级目录必须是 /apiproxy

    ZIP 文件名没有特殊要求。例如,您无需递增修订版本号或指定文件名中的日期,但这样做有助于调试或进行源代码控制。

    当您上传新代理配置时,Edge 会为您递增该代理配置的修订版本号。

  7. 使用 Edge 界面上传新的代理配置。(在 API 代理视图中,依次选择项目 > 上传新的修订版本。)

    如果您收到 Bundle is invalid. Empty bundle. 之类的错误,请确保 ZIP 文件的顶级目录为 /apiproxy。否则,请从所展开目录的根目录重新归档您的代理配置文件。

    上传新的代理配置后,Edge 会递增修订版本号并将其显示在修订版本摘要视图中。

    您通过界面上传新修订版本后,Edge 不会为您部署该修订版本。

  8. 部署新的修订版本。

如需了解详情,请参阅 Apigee 社区中的教程:如何使用界面和管理 API 下载代理

API 代理结构

API 代理包含以下配置:

基本配置 API 代理的主要配置设置。请参阅基本配置
ProxyEndpoint 配置 入站 HTTP 连接(从发出请求的应用到 Apigee Edge)、请求和响应流程以及政策附件的设置。请参阅 ProxyEndpoint
TargetEndpoint 配置 出站 HTTP 连接(从 Apigee Edge 到后端服务)、请求和响应流以及政策连接的设置。请参阅 TargetEndpoint
可附加政策的 ProxyEndpoint 和 TargetEndpoint 请求和响应流水线。请参阅
政策 符合 Apigee Edge 政策架构的 XML 格式配置文件。请参阅政策
资源 政策引用以执行自定义逻辑的脚本、JAR 文件和 XSLT 文件。请参阅资源

API 代理目录结构和内容

上表中的组件由采用以下目录结构的配置文件定义:

显示 apiproxy 是根目录的目录结构。apiproxy 目录的正下方是政策、代理、资源和目标目录以及 weatherapi.xml 文件。

API 代理的配置文件和目录结构

本部分介绍 API 代理的配置文件和目录结构。

基本配置

/apiproxy/weatherapi.xml

API 代理的基本配置,用于定义 API 代理的名称。该名称在组织内必须唯一。

示例配置:

<APIProxy name="weatherapi">
</APIProxy>

基本配置元素

名称 说明 默认 是否必需?
APIProxy
name API 代理的名称,该名称在组织内必须唯一。允许在名称中使用的字符仅限于以下字符:A-Za-z0-9_- 不适用
revision API 代理配置的修订版本号。您无需明确设置修订版本号,因为 Apigee Edge 会自动跟踪 API 代理的当前版本。 不适用
ConfigurationVersion 此 API 代理所遵守的 API 代理配置架构的版本。目前唯一支持的值是 majorVersion 4 和 minorVersion 0。此设置将来可能会用于支持 API 代理格式的演化。 4.0
Description API 代理的文本说明。如有提供,则说明将显示在 Edge 管理界面中。 不适用
DisplayName 易记的名称,可能与 API 代理配置的 name 属性不同。 不适用
Policies 此 API 代理的 /policies 目录中的政策列表。通常,只有在使用 Edge 管理界面创建 API 代理时,您才会看到此元素。这只是一个“清单”设置,旨在让您深入了解 API 代理的内容。 不适用
ProxyEndpoints 此 API 代理的 /proxies 目录中的 ProxyEndpoint 列表。您通常仅在使用 Edge 管理界面创建 API 代理时看到此元素。这只是一个“清单”设置,旨在让您深入了解 API 代理的内容。 不适用
Resources 此 API 代理的 /resources 目录中的资源(JavaScript、Python、Java、XSLT)的列表。通常,只有在使用 Edge 管理界面创建 API 代理时,您才会看到此元素。这只是“清单”设置,旨在让您深入了解 API 代理的内容。 不适用
Spec 标识与 API 代理关联的 OpenAPI 规范。该值设置为规范存储区中的网络或路径。

注意:规范存储区仅在新版 Edge 体验中提供。如需详细了解规范存储区,请参阅管理和共享规范
不适用
TargetServers 此 API 代理的任何 TargetEndpoint 中引用的 TargetServer 列表。通常,只有在使用 Edge 管理界面创建 API 代理时,您才会看到此元素。这只是一个“清单”设置,旨在让您深入了解 API 代理的内容。 不适用
TargetEndpoints 此 API 代理的 /targets 目录中的 TargetEndpoint 列表。您通常仅在使用 Edge 管理界面创建 API 代理时看到此元素。这只是一个“清单”设置,旨在让您深入了解 API 代理的内容。 不适用

ProxyEndpoint

下图显示了请求/响应流:

显示调用 HTTP 服务的客户端。请求会经过代理端点,经过目标端点,再由 HTTP 服务处理。响应会经过目标端点,经过代理端点,再返回到客户端。

/apiproxy/proxies/default.xml

ProxyEndpoint 配置定义 API 代理的入站(面向客户端)接口。配置 ProxyEndpoint 时,您将设置网络配置,以定义客户端应用(“应用”)应如何调用代理 API。

以下示例 ProxyEndpoint 配置将存储在 /apiproxy/proxies 下方:

<ProxyEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPProxyConnection>
    <BasePath>/weather</BasePath>
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

基本 ProxyEndpoint 中所需的配置元素包括:

ProxyEndpoint 配置元素

名称 说明 默认 是否必需?
ProxyEndpoint
name ProxyEndpoint 的名称。如果(在极少数情况下)定义了多个 ProxyEndpoints,则在 API 代理配置中必须唯一。允许在名称中使用的字符仅限于以下字符:A-Za-z0-9._\-$ % 不适用
PreFlow 定义请求或响应的 PreFlow 流中的政策。 不适用
Flows
定义请求或响应的条件流中的政策。
不适用
PostFlow
定义请求或响应的 PostFlow 流中的政策。
不适用
HTTPProxyConnection 定义与 API 代理关联的网络地址和 URI 路径
BasePath

必需的字符串,用于唯一标识 Apigee Edge 用于将传入消息路由到正确的 API 代理的 URI 路径。

BasePath 是一个 URI 片段(例如 /weather),附加到 API 代理的基准网址(例如 http://apifactory-test.apigee.net)。BasePath 在环境中必须唯一。生成或导入 API 代理时验证唯一性。

在基本路径中使用通配符

您可以在 API 代理基本路径中使用一个或多个“*”通配符。例如,/team/*/members 的基本路径允许客户端调用 https://[host]/team/blue/membershttps://[host]/team/green/members,而无需创建新的 API 代理来支持新团队。请注意,不支持 /**/。

重要提示:Apigee 不支持将通配符“*”用作基本路径的第一个元素。例如,不支持以下项:/*/search。以“*”开头的基本路径可能会导致意外错误,这是由于 Edge 识别有效路径的方式所致。

/
VirtualHost

将 API 代理与环境的特定基准网址相关联。VirtualHost 是一种已命名配置,用于为环境定义一个或多个网址。

为 ProxyEndpoint 定义的已命名 VirtualHost 确定公开 API 代理的网域和端口,以及按扩展名,应用用于调用 API 代理的网址。

默认情况下,系统会为环境定义两个已命名 VirtualHost:defaultsecure。组织还可以定义自定义网域。如需确保 API 代理仅通过 HTTPS 提供,请将 HTTPProxyConnection 中的 VirtualHost 设置为 secure

默认
Properties 可以将一组可选的 HTTP 配置设置定义为 <ProxyEndpoint> 的属性。 不适用
FaultRules
定义 ProxyEndpoint 如何响应错误。故障规则指定以下两项:
  • 根据故障的预定义类别、子类别或名称指定要处理的故障的条件
  • 定义相应条件故障规则行为的一个或多个政策

请参阅处理故障

不适用
DefaultFaultRule

处理其他故障规则未显式处理的任何错误(系统、传输、消息传递或政策)。

请参阅处理故障

不适用
RouteRule 定义 ProxyEndpoint 请求流水线处理之后入站请求消息的目的地。RouteRule 通常指向已命名 TargetEndpoint 配置,但也可以直接指向某个网址。
Name 必需属性,用于为 RouteRule 提供名称。允许在名称中使用的字符仅限于以下字符:A-Za-z0-9._\-$ %。例如,Cat2 %_ 是法定名称。 不适用
Condition 在运行时用于动态路由的可选条件语句。条件 RouteRule 非常有用,例如启用基于内容的路由以支持后端版本控制。 不适用
TargetEndpoint

可选字符串,用于标识已命名 TargetEndpoint 配置。已命名 TargetEndpoint 是 /targets 目录下的同一 API 代理中定义的任何 TargetEndpoint。

通过命名 TargetEndpoint,您可以指明 ProxyEndpoint 请求流水线处理后应将请求消息转发到的位置。请注意,这是一项可选设置。

ProxyEndpoint 可以直接调用网址。例如,适用于 HTTP 客户端角色的 JavaScript 或 Java 资源可能会执行 TargetEndpoint 的基本职责,即将请求转发到后端服务。

不适用
网址 一个可选字符串,用于定义由 ProxyEndpoint 调用的出站网络地址,从而绕过可能存储在 /targets 下方的任何 TargetEndpoint 配置 不适用

如何配置 RouteRule

已命名 TargetEndpoint 是指位于 /apiproxy/targets 下方、ProxyEndpoint 处理后 RouteRule 将请求转发到的配置文件。

例如,以下 RouteRule 是指配置 /apiproxy/targets/myTarget.xml

<RouteRule name="default">
  <TargetEndpoint>myTarget</TargetEndpoint>
</RouteRule>

直接网址调用

ProxyEndpoint 还可以直接调用后端服务。直接网址调用会绕过 /apiproxy/targets 下方的任何已命名 TargetEndpoints 配置。因此,TargetEndpoint 是可选的 API 代理配置,但在实践中建议不要从 ProxyEndpoint 中直接调用。

例如,以下 RouteRule 会对 http://api.mycompany.com/v2 进行 HTTP 调用。

<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL> 
</RouteRule>

条件路由

可以将 RouteRule 进行链接,以在运行时支持动态路由。系统可根据 HTTP 标头、消息内容、查询参数或同一时间、语言区域等上下文信息,将入站请求路由到已命名 TargetEndpoint 配置,直接路由到网址,或者路由到两者的组合。

条件 RouteRules 的工作方式与 Apigee Edge 上的其他条件语句类似。请参阅条件参考文档变量参考文档

例如,以下 RouteRule 组合会先评估入站请求,以验证 HTTP 标头的值。如果 HTTP 标头 routeTo 的值为 TargetEndpoint1,则将请求转发到名为 TargetEndpoint1 的 TargetEndpoint。否则,将入站请求转发到 http://api.mycompany.com/v2

<RouteRule name="MyRoute">
  <Condition>request.header.routeTo = "TargetEndpoint1"</Condition>
  <TargetEndpoint>TargetEndpoint1</TargetEndpoint>
</RouteRule>
<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

Null 路由

可以定义 null RouteRule 以支持不需要将请求消息转发到 TargetEndpoint 的场景。当 ProxyEndpoint 执行所有必要的处理时,例如使用 JavaScript 调用外部服务或从 API 服务键值对存储区的查找中检索数据时,这会很有用。

例如,以下内容定义一个 Null 路由:

<RouteRule name="GoNowhere"/>

条件 null 路由会很有用。在以下示例中,会将 null 路由配置为在 HTTP 标头 request.header.X-DoNothing 的值不是 null 时执行。

<RouteRule name="DoNothingOnDemand">
  <Condition>request.header.X-DoNothing != null</Condition>
</RouteRule>

请注意,RouteRule 可以链接,因此条件 null 路由通常是一组旨在支持条件路由的 RouteRule 的一个组成部分。

条件 null 路由的实际用途是支持缓存。通过使用缓存政策设置的变量值,您可以将 API 代理配置为在从缓存提供条目时执行 null 路由。

<RouteRule name="DoNothingUnlessTheCacheIsStale">
  <Condition>lookupcache.LookupCache-1.cachehit is true</Condition>
</RouteRule>

TargetEndpoint

显示调用 HTTP 服务的客户端。请求会经过代理端点,经过目标端点,再由 HTTP 服务处理。响应会经过目标端点,经过代理端点,再返回到客户端。

TargetEndpoint 是 ProxyEndpoint 的出站对等项。TargetEndpoint 充当后端服务或 API 的客户端,用于发送请求和接收响应。

API 代理不需要任何 TargetEndpoint。ProxyEndpoint 可以配置为直接调用网址。不含 TargetEndpoint 的 API 代理通常包含一个直接调用后端服务或者配置为使用 Java 或 JavaScript 调用服务的 ProxyEndpoint。

TargetEndpoint 配置

/targets/default.xml

TargetEndpoint 定义了从 Apigee Edge 到其他服务或资源的出站连接。

下面是 TargetEndpoint 配置示例:

<TargetEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <SSLInfo/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

TargetEndpoint 配置元素

TargetEndpoint 可以通过以下方法之一调用目标:

  • 适用于 HTTP(S) 调用的 HTTPTargetConnection
  • 用于本地代理到代理链接的 LocalTargetConnection
  • ScriptTarget(用于调用 Edge 托管的 Node.js 脚本

在 TargetEndpoint 中仅配置其中一个。

名称 说明 默认 是否必需?
TargetEndpoint
name TargetEndpoint 的名称,该名称在 API 代理配置中必须唯一。TargetEndPoint 的名称用于 ProxyEndpoint RouteRule 中,用来定向请求以进行出站处理。允许在名称中使用的字符仅限于以下字符:A-Za-z0-9._\-$ % 不适用
PreFlow 定义请求或响应的 PreFlow 流中的政策。 不适用
Flows
定义请求或响应的条件流中的政策。
不适用
PostFlow
定义请求或响应的 PostFlow 流中的政策。
不适用
HTTPTargetConnection

通过其子元素,指定通过 HTTP 访问的后端资源。

如果您使用 HTTPTargetConnection,请勿配置其他类型的目标连接(ScriptTarget 或 LocalTargetConnection)。

URL 定义 TargetEndpoint 将请求消息转发到的后端服务的网络地址。 不适用
LoadBalancer

定义一个或多个已命名 TargetServer 配置。已命名 TargetServer 配置可用于负载均衡,从而定义 2 个或更多端点配置连接。

您还可以使用 TargetServer 将 API 代理配置与具体后端服务端点网址分离。

请参阅跨后端服务器进行负载均衡

不适用
Properties 可以将一组可选的 HTTP 配置设置定义为 <TargetEndpoint> 的属性。 不适用
SSLInfo (可选)在 TargetEndpoint 中定义 TLS/SSL 设置,以控制 API 代理和目标服务之间的 TLS/SSL 连接。请参阅 TLS/SSL TargetEndpoint 配置 不适用
LocalTargetConnection 通过其子元素,指定要在本地访问的资源,绕过负载均衡和消息处理器等网络特性。

如需指定目标资源,请添加 APIProxy 子元素(具有 ProxyEndpoint 元素)或 Path 子元素。

如需了解详情,请参阅将 API 代理链接到一起

如果使用 LocalTargetConnection,请勿配置其他类型的目标连接(HTTPTargetConnection 或 ScriptTarget)。

APIProxy 指定要用作请求目标的 API 代理的名称。目标代理必须与发送请求的代理位于同一组织和环境。这是使用 Path 元素的替代方法。 不适用
ProxyEndpoint 与 APIProxy 搭配使用,用于指定目标代理的 ProxyEndpoint 的名称。 不适用
Path 指定要用作请求目标的 API 代理的端点路径。目标代理必须与发送请求的代理位于同一组织和环境。这是使用 APIProxy 的替代方案。 不适用
FaultRules
定义 TargetEndpoint 如何响应错误。故障规则指定以下两项:
  • 根据故障的预定义类别、子类别或名称指定要处理的故障的条件
  • 定义相应条件故障规则行为的一个或多个政策

请参阅处理故障

不适用
DefaultFaultRule

处理其他 FaultRule 未显式处理的任何错误(系统、传输、消息传递或政策)。

请参阅处理故障

不适用
ScriptTarget
ResourceURL

定义实现 TargetEndpoint 功能的资源类型(节点)和主 Node.js 脚本的名称。

<ResourceURL>node://server.js</ResourceURL>

该脚本需要包含在 API 代理的资源文件中。请参阅将 Node.js 添加到现有 API 代理

如果您使用 ScriptTarget,请勿配置其他类型的目标连接(HTTPTargetConnection 或 LocalTargetConnection)。

不适用
EnvironmentVariable

(可选)将环境变量传递给 Node.js 主脚本。

请参阅了解 Node.js 模块的 Edge 支持

不适用
Arguments

(可选)将参数传递给 Node.js 主脚本。

请参阅了解 Node.js 模块的 Edge 支持

不适用

TLS/SSL TargetEndpoint 配置

TargetEndpoint 通常需要通过异构后端基础架构管理 HTTPS 连接。为此,我们支持许多 TLS/SSL 配置设置。

TLS/SSL TargetEndpoint 配置元素

名称 说明 默认 是否必需?
SSLInfo
Enabled 指明是否已为端点启用 TLS/SSL。如果 <URL> 指定 HTTPS 协议,则默认值为 true;如果 <URL> 指定 HTTP,则默认值为 false 如果 <URL> 指定 HTTPS,则为 true
TrustStore 包含可信服务器证书的密钥库。 不适用
ClientAuthEnabled 用于开启出站客户端身份验证的设置(双向 TLS/SSL) false
KeyStore 包含用于出站客户端身份验证的私钥的密钥库 不适用 是(如果 ClientAuthEnabled 为 true)
KeyAlias 用于出站客户端身份验证的私钥的密钥别名 不适用 是(如果 ClientAuthEnabled 为 true)
Ciphers

出站 TLS/SSL 支持的加密方式。如果未指定加密方式,则允许可用于 JVM 的所有加密方式。

如需限制加密方式,请添加以下列出支持的加密方式的元素:

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>    
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>
不适用
Protocols

出站 TLS/SSL 支持的协议。如果未指定协议,则允许可用于 JVM 的所有协议。

如需限制协议,请添加以下列出支持的协议的元素:

<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>
不适用
CommonName

如果指定,则为验证目标证书的通用名称的值。 该值仅对 TargetEndpoint 和 TargetServer 配置有效。它对 VirtualHost 配置无效。

默认情况下,指定的值与目标证书的通用名称完全匹配。 例如,如果将 *.myhost.com 作为 <CommonName> 的值,则仅当将确切值 *.myhost.com 指定为目标证书中的通用名称时,才会匹配并验证目标主机名。

或者,Apigee 可以使用 wildcardMatch 属性执行包含通配符的匹配。

例如,如果按如下方式指定 <CommonName> 元素,则将匹配并验证目标证书中指定为 abc.myhost.com 的通用名称:

<CommonName wildcardMatch="true">*.myhost.com</CommonName>

不适用

启用了出站客户端身份验证的示例 TargetEndpoint

<TargetEndpoint name="default">
  <HttpTargetConnection>
        <URL>https://myservice.com</URL>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>myTruststore</TrustStore>
    </SSLInfo>
  </HttpTargetConnection>
</TargetEndpoint>

如需了解详细说明,请参阅配置从边缘到后端(Cloud 和 Private Cloud)的 TLS

使用流变量动态设置 TLS/SSL 值

您还可以动态设置 TLS/SSL 详细信息以支持灵活的运行时要求。例如,如果您的代理连接到两个可能不同的目标(测试目标和一个生产目标),可以让 API 代理以编程方式检测其调用的环境,并动态设置对相应的密钥库和信任库的引用。以下 Apigee 社区文章详细介绍了此场景,并提供可部署 API 代理示例:https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html

以下示例演示如何在 TargetEndpoint 配置中设置 <SSLInfo> 标记,例如,您可以通过 Java Callout、JavaScript 政策或“分配消息”政策在运行时提供这些值。使用包含要设置的值的任何消息变量。

仅以下元素中允许使用变量。

<SSLInfo>
    <Enabled>{myvars.ssl.enabled}</Enabled>
    <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
    <KeyStore>{myvars.ssl.keystore}</KeyStore>
    <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
    <TrustStore>{myvars.ssl.trustStore}</TrustStore>
</SSLInfo>

使用引用动态设置 TLS/SSL 值

在配置使用 HTTPS 的 TargetEndpoint 时,您必须考虑 TLS/SSL 证书到期的情况,或者系统配置发生更改时需要更新证书。在 Private Cloud 安装的 Edge 中,使用静态值或流变量配置 TLS/SSL 时,您可能需要重启消息处理器。

如需了解详情,请参阅更新 TLS 证书

但是,您可以选择将 TargetEndpoint 配置为改用密钥库或信任库的引用。使用引用的优势在于,您可以更新引用以指向其他密钥库或信任库,从而更新 TLS/SSL 证书,而无需重启消息处理器。

例如,下方所示为使用密钥库的引用的 TargetEndpoint:

<SSLInfo> 
    <Enabled>true</Enabled> 
    <ClientAuthEnabled>false</ClientAuthEnabled> 
    <KeyStore>ref://keystoreref</KeyStore> 
    <KeyAlias>myKeyAlias</KeyAlias> 
</SSLInfo>

使用以下 POST API 调用创建名为 keystoreref 的引用:

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
-d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

此引用指定密钥库的名称及其类型。

使用以下 GET API 调用来查看引用:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

以后如需将引用更改为指向其他密钥库,从而确保别名具有相同的名称,请使用以下 PUT 调用:

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
-d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

具有目标负载均衡的 TargetEndpoint

TargetEndpoints 使用三个负载均衡算法,支持在多个已命名 TargetServer 之间进行负载均衡。

如需了解详细说明,请参阅跨后端服务器实现负载平衡

政策

API 代理中的 /policies 目录包含可附加到 API 代理中流的所有政策。

政策配置元素

名称 说明 默认 是否必需?
Policy
name

政策的内部名称。您可以在名称中使用的字符仅限于:A-Za-z0-9._\-$ %。但是,Edge 管理界面会强制执行其他限制,例如自动移除非字母数字字符。

(可选)使用 <DisplayName> 元素,在管理界面代理编辑器中使用不同的自然语言名称给政策加标签。

不适用
enabled

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

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

true
continueOnError

设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。

设置为 true,即使在政策失败后,仍可以继续执行流。

false
async

注意:此属性不会使政策异步执行。在大多数情况下,将此项保留为默认值 false

设置为 true 时,政策执行会分流到其他线程,让主线程可用于处理其他请求。离线处理完成后,主线程返回并处理完消息流。在某些情况下,将异步设置为 true 可以提高 API 代理的性能。但是,过度使用异步可能会导致线程切换过多而影响性能。

如需在 API 代理中使用异步行为,请参阅 JavaScript 对象模型

false

政策附加

下图显示 API 代理流执行序列:

显示调用 HTTP 服务的客户端。请求遇到 ProxyEndpoint 和 TargetEndpoint,它们都包含触发政策的步骤。HTTP 服务返回响应后,响应将由 TargetEndpoint 处理,接着由 ProxyEndpoing 返回,再返回到客户端。与请求一样,响应会按照政策在各个政策进行处理。

如上所示:

政策作为处理步骤附加到。政策的名称用于引用要作为处理步骤强制执行的政策。政策附加采用以下格式:

<Step><Name>MyPolicy</Name></Step>

系统将按照附加到流中的顺序强制执行政策。例如:

<Step><Name>FirstPolicy</Name></Step>
<Step><Name>SecondPolicy</Name></Step>

政策附加配置元素

名称 说明 默认 是否必需?
Step
Name 此步骤定义要执行的政策的名称。 不适用
Condition 用于确定是否强制执行政策的条件语句。如果政策具有关联条件,则仅当条件语句的评估结果为 true 时,此政策才会执行。 不适用

ProxyEndpoint 和 TargetEndpoint 定义用于处理请求和响应消息的流水线。处理流水线包含一个请求流和一个响应流。每个请求流和响应流都细分为 PreFlow 流、一个或多个可选“条件”或“已命名”流以及一个 PostFlow。

  • PreFlow:始终执行。在任何条件流之前执行。
  • PostFlow:始终执行。在任何条件流之后执行。

此外,您可以向 ProxyEndpoint 添加 PostClientFlow,后者在将响应返回到发出请求的客户端应用后执行。只有 MessageLogging 政策Google Stackdriver Logging Extension 可以附加到此流程中。PostClientFlow 可减少 API 代理延迟时间,并使在将响应返回到客户端后才会计算的信息可用于日志记录,此类信息如 client.sent.start.timestampclient.sent.end.timestamp。该流主要用于衡量响应消息的开始时间戳和结束时间戳之间的时间间隔。

观看介绍操作方法的简短视频

视频:观看此简短视频,了解如何在 PostClientFlow 中使用消息日志记录。

下面是附加了消息日志记录政策的 PostClientFlow 示例。

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

API 代理处理流水线会按以下顺序执行流:

请求流水线:

  1. 代理请求 PreFlow
  2. 代理请求条件流(可选)
  3. 代理请求 PostFlow
  4. 目标请求 PreFlow
  5. 目标请求条件流(可选)
  6. 目标请求 PostFlow

响应流水线:

  1. 目标响应 PreFlow
  2. 目标响应条件流(可选)
  3. 目标回复 PostFlow
  4. 代理响应 PreFlow
  5. 代理响应条件流(可选)
  6. 代理响应 PostFlow
  7. PostClientFlow 响应(可选)

只需在 ProxyEndpoint 或 TargetEndpoint 配置中配置含政策附加的流。仅当需要在 PreFlow 或 PostFlow 处理期间强制执行某个政策时,才需要在 ProxyEndpoint 或 TargetEndpoint 配置中指定 PreFlow 和 PostFlow。

与条件流相比,PreFlow 和 PostFlow 元素的顺序并不重要,API 代理将始终在流水线中的相应点执行每个元素,而无论其出现在端点配置的哪个位置。

条件流

ProxyEndpoint 和 TargetEndpoint 支持无限数量的条件流(也称为“已命名流”)。

API 代理会对条件流中指定的条件进行测试,并且在符合条件时 API 代理将执行条件流中的处理步骤。如果未满足条件,则绕过条件流中的处理步骤。条件流会按照 API 代理中定义的顺序评估,并执行第一个满足条件的条件流。

通过定义条件流,您可以根据以下情况,在 API 代理中应用处理步骤:

  • Request URI
  • HTTP 动词 (GET/PUT/POST/DELETE)
  • 查询参数、标头和表单参数的值
  • 多种其他类型的条件

例如,以下条件流指定仅在请求资源路径为 /accesstoken 时执行该流。任何路径为 /accesstoken 的入站请求都会执行此流,以及您附加到该流的任何政策。如果请求路径不包含后缀 /accesstoken,则该流不会执行(尽管可能会执行另一个条件流)。

<Flows>
  <Flow name="TokenEndpoint">
    <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition>
    <Request>
      <Step>
        <Name>GenerateAccessToken</Name>
      </Step>
    </Request> 
  </Flow>
</Flows>   

流配置元素

名称 说明 默认 是否必需?
Flow ProxyEndpoint 或 TargetEndpoint 定义的请求或响应处理流水线
Name 流的唯一名称。 不适用
Condition 条件语句,用于评估一个或多个变量,评估结果为 true 或 false。除预定义 PreFlow 和 PostFlow 类型以外的所有流都必须定义其执行条件。 不适用
Request 与请求消息处理关联的流水线 不适用
Response 与响应消息处理关联的流水线 不适用

步骤处理

Apigee Edge 会强制执行条件流的顺序排序。条件流从上到下执行。将执行条件评估结果为 true 的第一个条件流,并且仅执行一个条件流。

例如,在以下流配置中,任何不包含路径后缀 /first/second 的入站请求都会导致执行 ThirdFlow,从而强制执行名为 Return404 的政策。

<Flows>
  <Flow name="FirstFlow">
    <Condition>proxy.pathsuffix MatchesPath "/first"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="SecondFlow">
    <Condition>proxy.pathsuffix MatchesPath "/second"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
      <Step><Name>SecondPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="ThirdFlow">
    <Request>
      <Step><Name>Return404</Name></Step>
    </Request>
  </Flow>
</Flows>

资源

“资源”(用于 API 代理的资源文件)是可以使用政策附加到流的脚本、代码和 XSL 转换。这些脚本显示在管理界面中 API 代理编辑器的“脚本”部分。

如需了解支持的资源类型,请参阅资源文件

资源可以存储在 API 代理、环境或组织中。每种情况下,都会在政策中按名称引用资源。API 服务通过从 API 代理移到环境再移到组织级别来解析名称。

存储在组织级别的资源可由任何环境中的政策引用。存储在环境级别的资源可由该环境中的政策引用。存储在 API 代理级别的资源只能由该 API 代理中的政策引用。