端点属性参考文档

您正在查看 Apigee X 文档。
查看 Apigee Edge 文档。

本主题介绍可以在 TargetEndpointProxyEndpoint 配置中设置以控制消息传递和连接行为的传输属性。如需全面了解 TargetEndpointProxyEndpoint 配置,请参阅 API 代理配置参考

TargetEndpoint 传输属性

TargetEndpoint 配置中的 HTTPTargetConnection 元素定义了一组 HTTP 传输属性。您可以使用这些属性来设置传输级配置。

这些属性在 TargetEndpoint HTTPTargetConnection 元素中设置,如下所示:

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <Properties>
      <Property name="supports.http10">true</Property>
      <Property name="request.retain.headers">User-Agent,Referer,Accept-Language</Property>
      <Property name="retain.queryparams">apikey</Property>
    </Properties>
  </HTTPTargetConnection>
</TargetEndpoint>

TargetEndpoint 传输属性规范

属性名称 默认值 说明
keepalive.timeout.millis 60000 连接池中目标连接的连接空闲超时。如果池中的连接处于空闲状态的时间超过指定的限制,则连接会被关闭。
connect.timeout.millis

3000

目标连接超时。如果发生连接超时,Apigee 会返回 HTTP 503 状态代码。

io.timeout.millis 55000

如果在指定的毫秒数内没有数据可供读取,或者在指定的毫秒数内套接字未准备好写入数据,则事务被视为超时。

  • 如果在写入 HTTP 请求时发生超时,则返回 408 Request Timeout
  • 如果在读取 HTTP 响应时发生超时,则返回 504 Gateway Timeout

请参阅设置 io.timeout.millis 和 api.timeout

supports.http10 如果值为 true 并且客户端发送了 1.0 请求,则也向目标发送 1.0 请求。否则,将向目标发送 1.1 请求。
supports.http11 如果值为 true 并且客户端发送了 1.1 请求,则也向目标发送 1.1 请求;否则,将向目标发送 1.0 请求。
use.proxy 如果设置为 true,并且代理配置在 http.properties 中指定(仅限本地部署),则目标连接设置为使用指定的代理。
use.proxy.tunneling 如果设置为 true,并且代理配置在 http.properties 中指定(仅限本地部署),则目标连接设置为使用指定的隧道。如果目标使用 TLS/SSL,则该属性会被忽略,并且始终通过隧道发送消息。
enable.method.override 对于指定的 HTTP 方法,为发送到目标服务的出站请求设置 X-HTTP-Method-Override 标头。例如 <Property name="GET.override.method">POST</Property>
*.override.method 对于指定的 HTTP 方法,为出站请求设置 X-HTTP-Method-Override 标头。例如 <Property name="GET.override.method">POST</Property>
request.streaming.enabled

默认情况下 (false),HTTP 请求载荷会读取到缓冲区中,并且可对载荷进行操作的政策会按预期工作。如果载荷大于缓冲区大小(在 Apigee 中为 10 MB),您可以将此特性设置为 true。为 true 时,HTTP 请求载荷不会读取到缓冲区中;它们会按原样流式传输到目标端点。在这种情况下,系统会绕过 TargetEndpoint 请求流中对载荷进行操作的任何政策。另请参阅流式传输请求和响应

response.streaming.enabled

默认情况下,HTTP 响应载荷会读取到缓冲区中,并且可对载荷进行操作的政策会按预期工作。如果载荷大于缓冲区大小(在 Apigee 中为 10 MB),您可以将此特性设置为 true。为 true 时,HTTP 响应载荷不会读取到缓冲区中;它们会按原样流式传输到 ProxyEndpoint 响应流。在这种情况下,系统会绕过 TargetEndpoint 响应流中对载荷进行操作的任何政策。另请参阅流式传输请求和响应

success.codes 不适用

默认情况下,Apigee 会将 HTTP 代码 4XX5XX 视为错误,并将 HTTP 代码 1XX2XX3XX 视为成功。您可以通过此属性明确定义成功代码,例如,2XX, 1XX, 505 将任何 100200505 HTTP 响应代码视为成功。

设置此属性会覆盖默认值。因此,如果您想将 HTTP 代码 400 添加到默认成功代码列表中,请将此属性设置为:

<Property name="success.codes">1xx,2xx,3xx,400</Property>

如果您想仅将 HTTP 代码 400 视为成功代码,请将属性设置为:

<Property name="success.codes">400</Property>

将 HTTP 代码 400 设置为唯一的成功代码后,系统会将代码 1xx2xx3xx 视为失败代码。

compression.algorithm 不适用 默认情况下,Apigee 使用与客户端请求相同的压缩类型将请求转发到目标。例如,如果接收到的客户端请求使用 gzip 压缩,则 Apigee 会使用 gzip 压缩将请求转发给目标。如果从目标收到的响应使用 deflate,则 Apigee 会使用 deflate 将响应转发给客户端。支持的值包括:
  • gzip:始终使用 gzip 压缩发送消息
  • deflate:始终使用 deflate 压缩发送消息
  • none:始终不使用压缩发送消息

另请参阅:Apigee 是否支持使用 GZIP/deflate 进行压缩/解压缩?

request.retain.headers.
enabled
默认情况下,Apigee 会始终为出站消息保留所有 HTTP 标头。设置为 true 时,入站请求中的所有 HTTP 标头都会设置在出站请求中。
request.retain.headers 定义应在向目标服务发送的出站请求中设置的来自请求的特定 HTTP 标头。例如,要“传递”User-Agent 标头,请将 request.retain.headers 的值设置为 User-Agent。以逗号分隔列表的形式指定多个 HTTP 标头,例如 User-Agent,Referer,Accept-Language。此属性会替换 request.retain.headers.enabled。如果 request.retain.headers.enabled 设置为 false,仍然会为出站消息设置 request.retain.headers 属性中指定的任何标头。
response.retain.headers.
enabled
默认情况下,Apigee 会始终为出站消息保留所有 HTTP 标头。设置为 true 时,将为出站响应设置来自目标服务的入站响应中的所有 HTTP 标头,然后再将响应传递给 ProxyEndpoint
response.retain.headers 不适用 定义在发送到 ProxyEndpoint 之前,应为出站响应设置的来自响应的特定 HTTP 标头。例如,要“传递”Expires 标头,请将 response.retain.headers 的值设置为 Expires。以逗号分隔列表的形式指定多个 HTTP 标头,例如 Expires,Set-Cookie。此属性会替换 response.retain.headers.enabled。如果 response.retain.headers.enabled 设置为 false,仍然会为出站消息设置 response.retain.headers 属性中指定的任何标头。
retain.queryparams.
enabled
默认情况下,Apigee 会始终为出站请求保留所有查询参数。设置为 true 时,将为向目标服务发出的出站请求设置入站请求中的所有查询参数。
retain.queryparams 定义要在出站请求中设置的特定查询参数。例如,要包含请求消息中的查询参数 apikey,请将 retain.queryparams 设置为 apikey。以逗号分隔列表的形式指定多个查询参数,例如 apikey,environment。此属性会替换 retain.queryparams.enabled

ProxyEndpoint 传输属性

ProxyEndpoint HTTPTargetConnection 元素定义了一组 HTTP 传输属性。这些属性可用于设置传输级配置。

这些属性在 ProxyEndpoint HTTPProxyConnection 元素中设置,如下所示:

<ProxyEndpoint name="default">
  <HTTPProxyConnection>
    <BasePath>/v1/weather</BasePath>
    <Properties>
      <Property name="request.streaming.enabled">true</Property>
    </Properties>
  </HTTPProxyConnection>
</ProxyEndpoint>

ProxyEndpoint 传输属性规范

属性名称 默认值 说明
X-Forwarded-For 如果设置为 true,虚拟主机的 IP 地址将作为 HTTP X-Forwarded-For 标头的值添加到出站请求中。
request.streaming.
enabled
false 默认情况下 (false),HTTP 请求载荷会读取到缓冲区中,并且可对载荷进行操作的政策会按预期工作。如果载荷大于缓冲区大小(在 Apigee 中为 10 MB),您可以将此特性设置为 true。为 true 时,HTTP 请求载荷不会读取到缓冲区中;它们会按原样流式传输到 TargetEndpoint 请求流。在这种情况下,系统会绕过 ProxyEndpoint 请求流中对载荷进行操作的任何政策。另请参阅流式传输请求和响应
response.streaming.
enabled
false 默认情况下,HTTP 响应载荷会读取到缓冲区中,并且可对载荷进行操作的政策会按预期工作。如果载荷大于缓冲区大小(在 Apigee 中为 10 MB),您可以将此特性设置为 true。为 true 时,HTTP 响应载荷不会读取到缓冲区中;它们会按原样流式传输到客户端。在这种情况下,系统会绕过 ProxyEndpoint 响应流中对载荷进行操作的任何政策。另请参阅流式传输请求和响应
compression.algorithm 不适用

默认情况下,Apigee 遵循接收的任何消息设置的压缩类型。例如,如果客户端提交使用 gzip 压缩的请求,Apigee 将使用 gzip 压缩将请求转发给目标。您可以通过在 TargetEndpointProxyEndpoint 中设置此属性来配置要明确应用的压缩算法。支持的值包括:

  • gzip:始终使用 gzip 压缩发送消息
  • deflate:始终使用 deflate 压缩发送消息
  • none:始终不使用压缩发送消息

另请参阅:Apigee 是否支持使用 GZIP/deflate 进行压缩/解压缩?

api.timeout 不适用

配置单个 API 代理的超时

您可以配置 API 代理(甚至包括启用了流式处理的代理),使其在指定时间后超时并返回 504 Gateway Timeout 状态。例如,假设您需要特定代理在 3 分钟后超时。以下是您使用 api.timeout 的方式。

  1. 首先,确保将负载平衡器、路由器和消息处理器配置为在 3 分钟后超时。
  2. 然后,将相关代理配置为在 3 分钟后超时。以毫秒为单位指定该值。例如 <Property name="api.timeout">180000</Property>
  3. 但请注意,增加系统超时可能会导致性能问题,因为所有不具有 api.timeout 设置的代理都会使用新的、更长的负载平衡器、路由器和消息处理器超时。因此,请将无需更长超时的其他 API 代理配置为使用较短的超时。例如,以下命令将 API 代理设置为在 1 分钟后超时:
    <Property name="api.timeout">60000</Property>

您无法使用变量设置此属性。

您还可以配置 API 代理超时,只要该超时比标准消息处理器超时 57 秒短即可。

请参阅设置 io.timeout.millis 和 api.timeout

设置 io.timeout.millis 和 api.timeout

io.timeout.millisapi.timeout 的操作是相关的。对于向 API 代理发出的每个请求:

  1. 路由器将其超时值发送给消息处理器。路由器超时值默认为 57 秒。
  2. 然后,消息处理器会设置 api.timeout
    1. 如果在代理级别设置 api.timeout,请将其设置为路由器超时。
    2. 如果在代理级别设置了 api.timeout,请在消息处理器上将其设置为路由器超时或 api.timeout 的值(以较小值为准)。
  3. api.timeout 的值指定 API 代理从 API 请求到响应的最长执行时间。

    API 代理中的每个政策执行之后或消息处理器向目标端点发送请求之前,消息处理器会计算(api.timeout - 从请求开始流逝的时间)。

    如果值小于零,则处理该请求的最长时间已过期,消息处理器返回 504 Gateway Timeout

  4. io.timeout.millis 的值指定目标端点进行响应的最长时间。

    在连接到目标端点之前,消息处理器会确定(api.timeout - 从请求开始流逝的时间)和 io.timeout.millis 中的较小值。然后将 io.timeout.millis 设置为该值。

    • 如果在写入 HTTP 请求时发生超时,则返回 408 Request Timeout
    • 如果在读取 HTTP 响应时发生超时,则返回 504 Gateway Timeout