API 代理配置参考文档

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

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

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

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

• 使用 Apigee 界面或 API。
• 下载 API 代理配置软件包，手动修改该配置，然后将新配置上传到 Apigee，如下载和上传 API 代理配置软件包中所述。

API 代理配置目录结构

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

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

基本配置

/apiproxy/weatherapi.xml

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

示例配置：

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

基本配置元素

ProxyEndpoint

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

/apiproxy/proxies/default.xml

ProxyEndpoint 配置定义 API 代理的入站（面向客户端）接口。配置代理端点时，您将设置网络配置，以定义客户端应用（“应用”）应如何调用代理 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 配置元素

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

如何配置 RouteRule

已命名目标端点是指位于 /apiproxy/targets 下方的一种配置文件，RouteRule 会在代理端点处理后将请求转发到该配置文件。

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

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

直接网址调用

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

例如，以下 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 的目标端点。否则，将入站请求转发到 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 以支持不需要将请求消息转发到目标端点的场景。当代理端点执行所有必要的处理时（例如使用 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

目标端点是代理端点的出站对等项。目标端点充当后端服务或 API 的客户端，用于发送请求和接收响应。

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

TargetEndpoint 配置

/targets/default.xml

目标端点定义从 Apigee 到其他服务或资源的出站连接。

下面是 TargetEndpoint 配置示例：

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

TargetEndpoint 配置元素

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

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

在目标端点中仅配置其中一个。

<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，目标服务器网址为 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 配置

目标端点通常需要通过异构后端基础设施管理 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.2</Protocol>
 <Protocol>TLSv1.3</Protocol>
</Protocols>

启用出站客户端身份验证的目标端点示例

<TargetEndpoint name="default">
  <HttpTargetConnection>
        <URL>https://myservice.com</URL>
    <SSLInfo>
      <Enabled>true</Enabled>
      <Enforce>true</Enforce>
      <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 的目标端点时，您必须考虑 TLS/SSL 证书过期的情况，或者系统配置更改要求更新证书的情况。

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

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

例如，下方所示为使用对密钥库的引用的目标端点：

<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

目标端点使用三种负载均衡算法，支持在多个已命名目标服务器之间进行负载均衡。

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

IntegrationEndpoint

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

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

配置 IntegrationEndpoint

如需将集成端点配置为目标端点，请将 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 配置元素

同步执行与异步执行

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

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

以下示例将 AsyncExecution 设置为 true：

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

政策

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：始终执行。在任何条件流之后执行。

此外，您可以向代理端点添加 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 代理将始终在流水线中的相应点执行每个元素，而无论其出现在端点配置的哪个位置。

条件流

代理端点和目标端点支持无限数量的条件流（也称为“已命名流”）。

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

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

• 请求 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 强制执行。条件流从上到下执行。将执行条件评估结果为 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 代理中的政策引用。