API 代理配置参考文档

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

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

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

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

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>
    <Properties/>
  </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/members 和 https://[host]/team/green/members，而无需创建新的 API 代理来支持新团队。请注意，不支持 /**/。

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

 / 是
Properties 可以将一组可选的 HTTP 配置设置定义为 <ProxyEndpoint> 的属性。

使用属性 request.queryparams.ignore.content.type.charset 指示代理在处理请求网址时忽略 Content-Type 标头的 charset 参数。例如：


<Property name= \
"request.queryparams.ignore.content.type.charset">true</>

下表展示了不同的 charset 属性设置以及 Content-Type 标头的 charset 参数是否存在情况下的示例输出。

属性设置 标头值 输出示例
charset=false 未设置 charset 参数 john.doe+test@gmail.com
charset=false charset=utf-8 john.doe test@gmail.com
charset=true，且标头中不含 charset 参数。 未设置 charset 参数 john.doe+test@gmail.com
charset=true 设置了 charset=utf-8 参数 john.doe+test@gmail.com
不适用 否
FaultRules
定义 ProxyEndpoint 如何响应错误。故障规则指定以下两项：
  • 根据故障的预定义类别、子类别或名称指定要处理的故障的条件
  • 定义相应条件故障规则行为的一个或多个政策

请参阅处理故障。

 不适用 否
DefaultFaultRule

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

请参阅处理故障。

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

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

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

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

 不适用 否
URL 一个可选字符串，用于定义由 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 调用外部服务，或从 Apigee 键值对存储区的查找中检索数据时），这会很有用。

例如，以下内容定义一个 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/>
    <Authentication/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

TargetEndpoint 配置元素

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

  • 用于 HTTP 或 HTTPS 调用的 HTTPTargetConnection
  • 用于本地代理到代理链接的 LocalTargetConnection

在 TargetEndpoint 中仅配置其中一个。

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

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

如果您使用 HTTPTargetConnection，请勿配置其他类型的目标连接（ScriptTarget 或 LocalTargetConnection）。

您可以使用 <Authentication> 子元素对 Google 服务以及在某些 Google Cloud 产品（例如 Cloud Functions 和 Cloud Run）上运行的自定义服务进行经过身份验证的调用。使用 <Authentication> 元素需要执行使用 Google 身份验证中所述的设置和部署步骤。正确设置后，政策会为您创建身份验证令牌，并将其添加到服务请求中。另请参阅 <Authentication> 元素用法。
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 未显式处理的任何错误（系统、传输、消息传递或政策）。

请参阅处理故障。

 不适用 否

<Authentication> 元素用法

<Authentication> 元素在 <TargetEndpoint> 中的用法与 <Authentication> 元素在 ServiceCallout 政策中的用法相同。在 <TargetEndpoint> 和 ServiceCallout 中，<Authentication> 都是 <HttpTargetConnection> 的子元素。如需了解详情，请参阅 ServiceCallout 政策参考文档中的 Authentication 元素。

<Authentication> 元素错误参考信息

如果您使用 <Authentication> 元素，则可以在 ServiceCallout 政策文档的错误部分找到可能的错误消息以及部署和运行时错误的问题排查提示。

<Authentication> 元素示例

以下示例展示了如何使用 Authentication 元素生成调用身份验证所需的 OpenID Connect 令牌，以调用部署在 Cloud Run 上的服务：

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
      <Properties/>
      <URL>https://cloudrun-hostname.a.run.app/test</URL>
      <Authentication>
          <GoogleIDToken>
             <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
          </GoogleIDToken>
     </Authentication>
  </HTTPTargetConnection>
</TargetEndpoint>

以下示例展示了如何使用 Authentication 元素生成调用身份验证所需的 OpenID Connect 令牌，以调用指向 Cloud Run 的 TargetService。HeaderName 元素将生成的不记名令牌添加到名为 X-Serverless-Authorization 的标头中，该标头将发送到目标系统。Authorization 标头（如果存在）保持不变，并且也会在请求中发送。

<TargetEndpoint name="TargetEndpoint-1">
   <HTTPTargetConnection>
     <Authentication>
        <HeaderName>X-Serverless-Authorization</HeaderName>
        <GoogleIDToken>
            <Audience ref="flow.variable.audience">https://cloudrun-hostname.a.run.app</Audience>
        </GoogleIDToken>
     </Authentication>
      <LoadBalancer>
         <Server name="cloud-run-target" />
      </LoadBalancer>
   </HTTPTargetConnection>
</TargetEndpoint>

以下示例展示了如何调用指向 Google Secret Manager 服务的 TargetService。在此示例中，GoogleAccessToken 元素配置为生成 Google 身份验证令牌以对目标请求进行身份验证：

<HTTPTargetConnection>
   <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>
      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
    </URL>
</HTTPTargetConnection>

以下示例展示了如何自动设置 GoogleIDToken 的目标对象。当 useTargetUrl 为 true 且引用的变量无法解析为有效变量时，目标的网址（不包括查询参数）会用作目标对象。假设请求路径为 /foobar，TargetServer 网址为 https://xyz.com，GoogleIDToken 的目标对象将自动设置为 https://xyz.com/foobar。

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience ref='myvariable' useTargetUrl="true"/>
      </GoogleIDToken>
    </Authentication>
    <LoadBalancer>
      <Server name="TS" />
    </LoadBalancer>
  </HTTPTargetConnection>
</TargetEndpoint>

TLS/SSL TargetEndpoint 配置

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

TLS/SSL TargetEndpoint 配置元素

名称 说明 默认 是否必需？
SSLInfo
Enabled 指明是否已为端点启用 TLS/SSL。如果 <URL> 指定 HTTPS 协议，则默认值为 true；如果 <URL> 指定 HTTP，则默认值为 false。 如果 <URL> 指定 HTTPS，则为 true 否
Enforce

在 Apigee 和目标后端之间强制执行严格的 SSL。

如果设置为 true，则对于证书无效、证书过期、自签名证书、主机名不匹配的证书以及具有不受信任的根的证书，连接将失败。系统会返回失败代码 4xx 或 5xx。

如果未设置或设置为 false，与具有有问题的证书的目标后端的连接结果取决于 <IgnoreValidationErrors> 的设置（见下文）。 如果 <IgnoreValidationErrors> 设置为 true，则在某些情况下可能会发生成功响应 (2xx)。

 false 否
TrustStore 包含可信服务器证书的密钥库。 不适用 否
ClientAuthEnabled 用于开启出站客户端身份验证的设置（双向 TLS/SSL） false 否
KeyStore 包含用于出站客户端身份验证的私钥的密钥库 不适用 是（如果 ClientAuthEnabled 为 true）
KeyAlias 用于出站客户端身份验证的私钥的密钥别名 不适用 是（如果 ClientAuthEnabled 为 true）
IgnoreValidationErrors

指示是否忽略验证错误。如果后端系统使用 SNI，并返回主题标识名 (DN) 与主机名不匹配的证书，则无法忽略该错误，并且连接失败。

注意：如果 <Enforce> 设置为 true，系统会忽略 <IgnoreValidationErrors> 的值。

 false 否
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 的所有协议。

要限制协议，请明确指定这些协议。例如，要仅允许 TLS v1.2 或 TLS v1.3：


<Protocols>
 <Protocol>TLSv1.2</Protocol>
 <Protocol>TLSv1.3</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>

如需了解详细说明，请参阅用于配置 TLS 的选项。

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

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

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

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

<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 证书过期的情况，或者系统配置更改要求更新证书的情况。

如需了解详情，请参阅处理过期证书。

但是，您可以选择将 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 请求设置环境变量。

具有目标负载均衡的 TargetEndpoint

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

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

IntegrationEndpoint

IntegrationEndpoint 是专门运行 Apigee 集成的 TargetEndpoint。如果您已配置 IntegrationEndpoint，则 Apigee 会将请求对象发送到 Apigee 的集成平台以供执行。如需运行集成，除了配置 IntegrationEndpoint 之外，您还必须在代理流中添加 SetIntegrationRequest 政策。

您可以通过在 IntegrationEndpoint 配置中设置 <AsyncExecution> 元素来配置集成以同步或异步执行。如需了解详情，请参阅同步执行与异步执行。运行集成后，Apigee 会将响应保存在响应消息中。

配置 IntegrationEndpoint

如需将集成端点配置为 TargetEndpoint，请将 IntegrationEndpoint 元素添加到 ProxyEndpoint 声明中。下面是一个 ProxyEndpoint 声明示例：

<ProxyEndpoint name="default">
    <Description/>
    <FaultRules/>
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>my-set-integration-request-policy</Name>
            </Step>
        </Request>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow"/>
    <HTTPProxyConnection>
        <BasePath>/integration-endpoint-test</BasePath>
        <Properties/>
    </HTTPProxyConnection>
    <RouteRule name="default">
        <IntegrationEndpoint>my-int-endpoint</IntegrationEndpoint>
    </RouteRule>
</ProxyEndpoint>

在该 ProxyEndpoint 声明示例中，Apigee 会执行以下任务：

  1. 在 PreFlow 中，执行名为 my-set-integration-request-policy 的政策，以设置集成请求对象和集成流变量。
  2. 使用 RouteRule 中指定的 my-int-endpoint 作为目标端点。
  3. 读取由 my-set-integration-request-policy 创建的集成请求对象。
  4. 使用 SetIntegrationRequest 政策设置的请求对象和流变量向 Apigee 的集成平台发送请求。
  5. 将集成的响应保存在响应消息中。

包含 <IntegrationEndpoint> 声明的 XML 文件将位于 APIGEE_BUNDLE_DIRECTORY/apiproxy/integration-endpoints/ 目录中。如果您使用 Develop > API Proxies > CREATE NEW > Integration target 选项创建 API 代理，Apigee 会将声明存储在 /apiproxy/integration-endpoints/default.xml 文件中。如果从界面创建集成端点 XML，则可以为 XML 文件提供自定义名称。

以下示例展示了 XML 文件中的 <IntegrationEndpoint> 元素的声明：

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>false</AsyncExecution>
</IntegrationEndpoint>

IntegrationEndpoint 配置元素

名称 说明 默认 是否必需？
IntegrationEndpoint
name IntegrationEndpoint 的名称。您仅可在名称中使用以下字符：A-Za-z0-9._\-$ % 不适用 是
AsyncExecution 一个布尔值，用于指定集成应该以同步模式还是异步模式运行。 如需了解详情，请参阅同步执行与异步执行。 否 否

同步执行与异步执行

您可以将集成配置为以同步模式或异步模式运行。如需了解同步执行模式和异步执行模式之间的差异，请参阅 <AsyncExecution>。

使用 </IntegrationEndpoint> 中的 <AsyncExecution> 元素指定同步或异步执行。如果将 <AsyncExecution> 设置为 true，则集成会异步运行。如果将其设置为 false，则集成会同步运行。

以下示例将 AsyncExecution 设置为 true：

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>true</AsyncExecution>
</IntegrationEndpoint>

政策

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

政策配置元素

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

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

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

 不适用 是
enabled

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

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

 true 否
continueOnError

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

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

 false 否
async

设置为 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 政策可以附加到此流中。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>

流配置元素

名称 说明 默认 是否必需？
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 代理、环境或组织中。每种情况下，都会在政策中按名称引用资源。Apigee 通过从 API 代理移到环境再移到组织级别来解析名称。

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