API 代理配置参考文档

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

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

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

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

• 在 Edge 界面中使用 XML 编辑器
• 下载配置并在本地修改，如代理配置的本地开发中所述。

代理配置的本地开发

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

本部分介绍如何使用界面下载现有代理限制，进行修改，然后将其上传回 Edge 以进行部署。您还可以使用 apigeetool 下载并部署新的代理配置（分别使用 fetchproxy 和 deployproxy 命令）。

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

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 代理目录结构和内容

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

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

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

• 基本配置
• ProxyEndpoint
• TargetEndpoint
  • TLS/SSL TargetEndpoint 配置
• 政策
• 流
• 资源

基本配置

/apiproxy/weatherapi.xml

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

示例配置：

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

基本配置元素

ProxyEndpoint

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

/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 配置元素

如何配置 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 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

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
• 对 Edge 托管的 Node.js 脚本的调用对应的 ScriptTarget

在 TargetEndpoint 中仅配置其中一个。

TLS/SSL TargetEndpoint 配置

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

TLS/SSL TargetEndpoint 配置元素

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>

<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>

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

如需了解详细说明，请参阅配置从 Edge 到后端（云和私有云）的 TLS。

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

您还可以动态设置 TLS/SSL 详细信息以支持灵活的运行时要求。例如，如果您的代理连接到两个可能不同的目标（测试目标和一个生产目标），可以让 API 代理以编程方式检测其调用的环境，并动态设置对相应的密钥库和信任库的引用。以下 Apigee 社区文章详细介绍了此场景，并提供可部署 API 代理示例：使用变量引用的 TargetEndpoint 的动态 SSLInfo。

以下示例演示如何在 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 证书过期的情况，或者系统配置更改要求更新证书的情况。在 Edge for Private Cloud 安装中，如果使用静态值或流变量配置 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 代理中流的所有政策。

政策配置元素

政策附加

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

如上所示：

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

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

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

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

政策附加配置元素

流

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

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

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

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

下面是附加了消息日志记录政策的 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>

流配置元素

步骤处理

条件流的序列顺序由 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 代理中的政策引用。