端点属性参考文档

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

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

TargetEndpoint 传输属性

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

这些属性在 TargetEndpoint HTTPTargetConnection 元素中设置，如以下示例配置所示：

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

TargetEndpoint 传输属性规范

属性名称 默认值 说明
allow.post.without.content.length false 允许您发送正文中没有内容的 POST 请求。
allow.put.without.content.length false 允许您发送正文中没有内容的 PUT 请求。
allow.tls.session.resumption true 如果为 true（默认值），则客户端在与目标建立新连接时重复使用 TLS 会话。如果您不希望重复使用 TLS 会话，请设置为 false。会话重复使用通常意味着连接时间更短，但某些目标可能不支持会话重复使用或难以使用。
keepalive.timeout.millis 60000 连接池中目标连接的连接空闲超时。如果池中的连接处于空闲状态的时间超过指定的限制，则连接会被关闭。
connect.timeout.millis

3000

目标连接超时。如果发生连接超时，Apigee 会返回 HTTP 503 状态代码。在某些情况下，如果在 TargetServer 定义中使用 LoadBalancer，并且发生超时，系统可能会返回 HTTP 504 状态代码。
ignore.allow.header.for.405

true

允许您将 405 状态代码传递回客户端。启用此标志后，Apigee 将返回 405 而不是 502 状态代码。
io.timeout.millis 55000

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

  • 如果在从入站流量读取 HTTP 请求时发生超时，会返回 408 Request Timeout。如果在向目标写入请求时发生超时，则不会返回 408 Request Timeout。
  • 如果在写入 HTTP 请求或读取 HTTP 响应时发生超时，则返回 504 Gateway Timeout。

请参阅设置 io.timeout.millis 和 api.timeout。
supports.http11 true 如果值为 true 并且客户端发送了 1.1 请求，则也向目标发送 1.1 请求；否则将向目标发送 1.0 请求。
use.proxy true

如果 Apigee Hybrid 替换文件包含 HTTP_PROXY 配置（如为 API 代理配置转发代理中所述），请使用此属性管理/控制哪些代理不应使用代理配置。

如果设置为 false，则 API 代理将针对代理中设置的目标连接跳过 Apigee Hybrid 替换文件中指定的 HTTP 代理配置。
use.proxy.tunneling true

如果设置为 true，并且代理配置在 Apigee Hybrid 替换文件中指定（如为 API 代理配置转发代理中所述），则目标连接设置为使用指定的隧道。如果目标使用 TLS/SSL，则该属性会被忽略，并且始终使用隧道发送消息。
request.streaming.enabled false

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

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

默认情况下，Apigee 会将 HTTP 代码 4XX 或 5XX 视为错误，并将 HTTP 代码 1XX、2XX、3XX 视为成功。您可以通过此属性明确定义成功代码，例如，2XX, 1XX, 505 将任何 100、200 和 505 HTTP 响应代码视为成功。

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

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

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

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

将 HTTP 代码 400 设置为唯一的成功代码后，系统会将代码 1xx、2xx 和 3xx 视为失败代码。
compression.algorithm 不适用 默认情况下，Apigee 遵循系统为接收的消息设置的压缩类型（gzip、deflate 或者不压缩）。例如，如果接收到的客户端请求使用 gzip 压缩，则 Apigee 会使用 gzip 压缩将请求转发给目标。如果从目标收到的响应使用 deflate，则 Apigee 会使用 deflate 将响应转发给客户端。支持的值包括：
  • gzip：始终使用 gzip 压缩发送消息
  • deflate：始终使用 deflate 压缩发送消息
  • none：始终不使用压缩发送消息

另请参阅：Apigee 是否支持使用 GZIP/deflate 进行压缩/解压缩？
request.retain.headers.
enabled		 true 默认情况下，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		 true 默认情况下，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		 true 默认情况下，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>

请求标头

传入 HTTP 请求包含客户端发送的 HTTP 标头。 如果客户端发送了名称与 X-Apigee-* 格式匹配的标头，则这些标头会从传入请求中移除。Apigee 会预留此名称格式。

ProxyEndpoint 传输属性规范

属性名称 默认值 说明
X-Forwarded-For false 如果设置为 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、deflate 或者不压缩）。例如，如果客户端提交使用 gzip 压缩的请求，Apigee 将使用 gzip 压缩将请求转发给目标。您可以通过在 TargetEndpoint 或 ProxyEndpoint 中设置此属性来配置要明确应用的压缩算法。支持的值包括：

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

另请参阅：Apigee 是否支持使用 GZIP/deflate 进行压缩/解压缩？
api.timeout 不适用

配置单个 API 代理的超时（以毫秒为单位）

您可以配置 API 代理（甚至包括启用了流式处理的代理），使其在指定时间后超时并返回 504 Gateway Timeout 状态。

例如，如需将代理配置为在 180000 毫秒（三分钟）后超时，请将以下属性添加到 HTTPProxyConnection 中：

<Property name="api.timeout">180000</Property>

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

请参阅设置 io.timeout.millis 和 api.timeout。
HTTPHeader.allowDuplicates 不适用

使用此设置可允许标头（对于特定标头）重复。

<HTTPProxyConnection>
  <Properties>
     <Property name="HTTPHeader.allowDuplicates">Content-Type,Authorization</Property>
  </Properties>
</HTTPProxyConnection>
HTTPHeader.multiValued 不适用

使用此设置可允许标头（对于特定标头）重复。

<HTTPProxyConnection>
  <Properties>
    <Property name="HTTPHeader.multiValued">Content-Type,Authorization</Property>
  </Properties>
</HTTPProxyConnection>

设置 io.timeout.millis 和 api.timeout

io.timeout.millis 和 api.timeout 的操作是相关的。对于向 API 代理发出的每个请求：

  1. Ingress（又称为“内部负载均衡器”）将其超时值发送给消息处理器。此超时值默认为 300 秒，不可配置。
  2. 然后，消息处理器会设置 api.timeout：
    1. 如果未在代理级别设置 api.timeout，请使用 Ingress 设置的超时。
    2. 如果在代理级别设置了 api.timeout，请在消息处理器上将其设置为 Ingress 超时或 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 请求或读取 HTTP 响应时发生超时，则返回 504 Gateway Timeout。