端点属性参考文档

您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 info

本主题介绍可以在 TargetEndpoint 和 ProxyEndpoint 配置中设置以控制消息传递和连接行为的传输属性。如需查看 TargetEndpoint 和 ProxyEndpoint 配置的完整说明，请参阅 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>
    <CommonName>COMMON_NAME_HERE</CommonName>
  </HTTPTargetConnection>
</TargetEndpoint>

TargetEndpoint 传输属性 规范

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

3000

目标连接超时。如果发生连接 超时，Edge 会返回 HTTP 503 状态代码。在某些情况下，如果在 TargetServer 定义 中使用 LoadBalancer，并且发生超时，系统可能会返回 HTTP 504 状态代码。
io.timeout.millis 55000

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

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

此值应始终小于 虚拟主机的 proxy_read_timeout 属性的值。

此值应小于 路由器用于与消息处理器通信的超时。如需了解详情，请参阅配置路由器超时，了解 更多信息。

如需了解详情，请参阅为 Edge 设置 io.timeout.millis 和 api.timeout 。
supports.http10 true 如果值为 true 并且客户端发送了 1.0 请求，则也向目标发送 1.0 请求。否则，将向目标发送 1.1 请求。
supports.http11 true 如果值为 true 并且客户端发送了 1.1 请求，则也向目标发送 1.1 请求；否则，将向目标发送 1.0 请求。
use.proxy true 如果设置为 true，并且代理配置在 http.properties 中指定（仅限本地部署），则目标连接 设置为使用指定的代理。
use.proxy.tunneling true 如果设置为 true，并且代理配置在 http.properties 中指定（仅限本地部署），则目标 连接设置为使用指定的隧道。如果目标使用 TLS/SSL，则该 属性会被忽略，并且始终通过隧道发送消息。
enable.method.override false 对于指定的 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

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

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

默认情况下，Apigee Edge 会将 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 Edge 使用与客户端请求相同的压缩类型将请求转发到目标。例如，如果接收到的客户端请求使用 gzip 压缩，则 Apigee Edge 会使用 gzip 压缩将请求转发给目标。如果从目标收到的响应使用 deflate，则 Apigee Edge 会使用 deflate 将响应转发给客户端。支持的值包括：
  • gzip：始终使用 gzip 压缩发送消息
  • deflate：始终使用 deflate 压缩发送消息
  • none ：始终不使用压缩发送消息

另请参阅： Apigee 是否支持使用 GZIP/deflate 进行压缩/解压缩？
request.retain.headers.
enabled		 true 默认情况下，Apigee Edge 会始终为出站消息保留所有 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 Edge 会始终为出站消息保留所有 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 Edge 会始终为出站请求保留所有查询参数。设置为 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>
    <VirtualHost>default</VirtualHost>
    <VirtualHost>secure</VirtualHost>
  </HTTPProxyConnection>
</ProxyEndpoint>

如需详细了解虚拟主机，请参阅虚拟主机简介。

ProxyEndpoint 传输属性 规范

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

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

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

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

配置单个 API 代理的超时

您可以配置 API 代理（甚至包括启用了 流式处理的代理），使其在指定时间后超时并返回 504 Gateway Timeout 状态。主要用例是针对执行时间较长的 API 代理的客户 。例如，假设您需要特定代理在 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>

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

无法修改 Edge 超时的客户也可以配置 API 代理 超时，前提条件是超时短于标准的 Edge 消息处理器 超时，即 57 秒。

如需了解详情，请参阅为 Edge 设置 io.timeout.millis 和 api.timeout 。

为 Edge 设置 io.timeout.millis 和 api.timeout

在 Edge 上，io.timeout.millis 和 api.timeout 的运行是相关的。 对于向 API 代理发出的每个请求：

  1. 路由器将其超时值发送给消息处理器。路由器超时值是由处理请求的虚拟主机设置的 proxy_read_timeout 的值，或 57 秒的默认超时值。
  2. 然后，消息处理器会设置 api.timeout：
    1. 如果未在代理级别设置 api.timeout，请将其设置为路由器超时。
    2. 如果在代理级别设置了 api.timeout，请在消息处理器上将其设置为路由器超时或 api.timeout 的值（以较小值为准）。

  3. api.timeout 的值指定 API 代理从 API 请求到响应的最长执行时间 。

    API 代理中的每个政策执行之后， 或消息处理器向目标端点发送请求之前， 消息处理器会计算 (api.timeout - 从请求开始流逝的时间)。 如果值小于零，则处理该请求的最长时间已过期，并且 消息处理器返回 504。

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

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

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

关于 Node.js 应用的 ScriptTarget

ScriptTarget 元素用于将 Node.js 应用集成到代理中。如需了解如何使用 Node.js 和 ScriptTarget，请参阅：

关于 HostedTarget 端点

空 <HostedTarget/> 标记会告知 Edge 将部署到 Hosted Targets 环境的 Node.js 应用用作其目标。如需了解详情，请参阅 Hosted Targets 概览。