注意:此产品的某些方面处于 Beta 版阶段。Hybrid 安装选项是 GA。要加入 Beta 版计划,请与您的 Apigee 代表联系。

API 代理配置参考文档

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

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

使用以下方法之一修改 API 代理配置:

在本地机器上管理 API 代理配置

您可以下载 API 代理配置,并在本地机器上对其进行管理。完成后,您可以将其上传到 Apigee。利用此方法,您可以:

  • 使用自己的 XML 编辑器和验证工具
  • 将 API 代理配置集成到源代码控制、版本控制和其他共享工作流中

本部分介绍了如何使用界面下载现有的 API 代理配置、修改该配置,然后将其上传回 Apigee 进行部署。

如需在本地机器上管理 API 代理配置,请执行以下操作

  1. 在 Apigee 界面中下载 API 代理配置:
    1. 在 API 代理编辑器中打开 API 代理
    2. 点击开发标签页。
    3. 选择项目 > 下载修订版本
  2. 在本地机器上,创建一个新目录,并在其中展开下载的 ZIP 文件。

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

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

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

  3. 根据需要修改源文件。如需了解 API 代理配置中源文件的说明,请参阅 API 代理配置目录结构
  4. 修改完 API 代理配置文件后,请务必保存您的更改。
  5. 切换到展开的 ZIP 文件的目录(展开的配置文件的根目录)。

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

    cd myappdir

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

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

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

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

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

  7. 使用 Apigee 界面上传新的 API 代理配置。
    1. 在 API 代理编辑器中打开 API 代理
    2. 点击开发标签页。
    3. 选择项目 > 上传修订版本

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

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

    当您上传新修订版本后,Apigee 不会进行部署。

  8. 部署新的修订版本。

API 代理配置目录结构

API 代理配置目录结构如下所示:

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

API 代理配置包含以下内容:

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

基本配置

/apiproxy/weatherapi.xml

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

示例配置:

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

基本配置元素

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

/
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 配置,直接路由到网址,或者路由到两者的组合。

条件 RouteRule 的工作方式与 Apigee 中的其他条件语句类似。请参阅条件引用变量引用

例如,以下 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 到其他服务或资源的出站连接。

下面是 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

在 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 未显式处理的任何错误(系统、传输、消息传递或政策)。

请参阅处理故障

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

启用出站客户端身份验证的 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>

如需了解详细说明,请参阅从 Apigee 到后端配置 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 证书过期的情况,或者系统配置更改要求更新证书的情况。

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

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

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

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

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

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>'

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项,请参阅使用 curl。如需了解所使用的环境变量,请参阅为 Apigee API 请求设置环境变量

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

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

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项,请参阅使用 curl。如需了解所使用的环境变量,请参阅为 Apigee API 请求设置环境变量

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项,请参阅使用 curl。如需了解所使用的环境变量,请参阅为 Apigee API 请求设置环境变量

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

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'

按照获取 OAuth 2.0 访问令牌中的说明,将 $TOKEN 设置为您的 OAuth 2.0 访问令牌。如需了解此示例中使用的 curl 选项,请参阅使用 curl。如需了解所使用的环境变量,请参阅为 Apigee API 请求设置环境变量

具有 quoteDoneAckHide 的 ReplyReply 1288 ​ 1289

具有目标负载平衡的 TargetEndpoint 1290

1291 ​ 1292

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

1294 ​ 1295

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

具有目标负载平衡的 TargetEndpoint

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

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

政策

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

政策配置元素

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

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

(可选)使用 <DisplayName> 元素以不同的自然语言名称形式在 Apigee 界面代理编辑器中为政策添加标签。

enabled

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

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

continueOnError

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

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

async

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

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

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

政策附加

下图显示 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 强制执行。条件流从上到下执行。将执行条件评估结果为 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 转换。它们显示在 Apigee 界面中 API 代理编辑器的“脚本”部分中。

如需了解受支持的资源类型,请参阅管理资源

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

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