REST Resource: projects.locations.httpRoutes

资源：HttpRoute

HttpRoute 是用于定义网格或网关资源应如何路由 HTTP 流量的资源。

JSON 表示法 
{
  "name": string,
  "selfLink": string,
  "description": string,
  "createTime": string,
  "updateTime": string,
  "hostnames": [
    string
  ],
  "meshes": [
    string
  ],
  "gateways": [
    string
  ],
  "labels": {
    string: string,
    ...
  },
  "rules": [
    {
      object (RouteRule)
    }
  ]
}
字段
name

string

必需。HttpRoute 资源的名称。它与模式 projects/*/locations/global/httpRoutes/http_route_name> 匹配。
description

string

可选。资源的自由文本说明。长度上限为 1024 个字符。
createTime

string (Timestamp format)

仅限输出。创建资源时的时间戳。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

仅限输出。资源更新时的时间戳。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
hostnames[]

string

必需。主机名定义了一组主机，这些主机应与 HTTP 主机标头匹配，以选择处理请求的 HttpRoute。主机名是网络主机的完全限定域名，由 RFC 1123 定义，但以下情况例外：- 不允许使用 IP。- 主机名可以带有通配符标签 (*.) 前缀。通配符标签必须单独出现，作为第一个标签。

主机名可以是“精确的”，即不含网络主机的终止点的域名（例如 foo.example.com），也可以是“通配符”（这是以单个通配符标签为前缀的域名（例如 *.example.com）。

请注意，根据 RFC1035 和 RFC1123，标签必须由小写字母数字字符或“-”组成，且必须以字母数字字符开头和结尾。不允许使用其他标点符号。

与网格或网关关联的路由必须具有唯一的主机名。如果您尝试附加多个具有冲突主机名的路由，该配置将会被拒绝。

例如，虽然主机名 *.foo.bar.com 和 *.bar.com 的路由可以与同一网格（或同一范围内的网关）关联，但无法将两个路由都与 *.bar.com 关联或同时与 bar.com 关联。
meshes[]

string

可选。Meshes 定义了一个与此 HttpRoute 挂接的网格的列表，作为路由网格所处理的请求之一的路由规则。

每个网格引用都应符合以下模式：projects/*/locations/global/meshes/<mesh_name>

附加的网格应为 SIDECAR 类型
gateways[]

string

可选。网关定义了一个连接此 HttpRoute 的网关列表，作为路由规则之一，以路由由该网关处理的请求。

每个网关引用都应符合以下格式：projects/*/locations/global/gateways/<gateway_name>
labels

map (key: string, value: string)

可选。与 HttpRoute 资源关联的标签标记集。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
rules[]

object (RouteRule)

必需。用于定义流量的路由和处理方式的规则。系统将根据为规则指定的 RouteMatch 依序匹配规则。

RouteRule

指定如何匹配流量，以及如何在流量匹配时路由流量。

JSON 表示法 
{
  "matches": [
    {
      object (RouteMatch)
    }
  ],
  "action": {
    object (RouteAction)
  }
}
字段
matches[]

object (RouteMatch)

匹配列表定义了用于将规则与传入 HTTP 请求进行匹配的条件。每个匹配都是独立的，即只要满足任一匹配项，就会匹配此规则。

如果未指定匹配字段，此规则将无条件匹配流量。

如果您希望配置默认规则，请在规则列表的末尾添加未指定匹配项的规则。
action

object (RouteAction)

用于定义如何转送匹配流量的详细规则。

RouteMatch

RouteMatch 定义用于匹配请求的规范。如果设置了多个匹配类型，此 RouteMatch 将匹配所有类型的匹配项。

JSON 表示法 
{
  "ignoreCase": boolean,
  "headers": [
    {
      object (HeaderMatch)
    }
  ],
  "queryParameters": [
    {
      object (QueryParameterMatch)
    }
  ],

  // Union field PathMatch can be only one of the following:
  "fullPathMatch": string,
  "prefixMatch": string,
  "regexMatch": string
  // End of list of possible types for union field PathMatch.
}
字段
ignoreCase

boolean

指定 prefixMatch 和 fullPathMatch 匹配是否区分大小写。默认值为 false。
headers[]

object (HeaderMatch)

指定要匹配的 HTTP 请求标头列表。提供的所有标头都必须匹配。
queryParameters[]

object (QueryParameterMatch)

指定要匹配的查询参数列表。必须匹配所有查询参数。

联合字段 PathMatch。

PathMatch 只能是下列其中一项：
fullPathMatch

string

HTTP 请求路径值应与此值完全匹配。

只能使用 fullPathMatch、prefixMatch 或 regexMatch 之一。
prefixMatch

string

HTTP 请求路径值必须以指定的 prefixMatch 开头。prefixMatch 必须以 / 开头。

只能使用 fullPathMatch、prefixMatch 或 regexMatch 之一。
regexMatch

string

在移除随原始网址提供的所有查询参数和锚点后，HTTP 请求路径值必须符合 regexMatch 指定的正则表达式。如需了解正则表达式的语法，请参阅 https://github.com/google/re2/wiki/Syntax

只能使用 fullPathMatch、prefixMatch 或 regexMatch 之一。

HeaderMatch

指定如何根据 HTTP 请求标头选择路由规则。

JSON 表示法 
{
  "header": string,
  "invertMatch": boolean,

  // Union field MatchType can be only one of the following:
  "exactMatch": string,
  "regexMatch": string,
  "prefixMatch": string,
  "presentMatch": boolean,
  "suffixMatch": string,
  "rangeMatch": {
    object (IntegerRange)
  }
  // End of list of possible types for union field MatchType.
}
字段
header

string

要匹配的 HTTP 标头的名称。
invertMatch

boolean

如果已指定，则会在检查之前反转匹配结果。默认值设置为 false。

联合字段 MatchType。

MatchType 只能是下列其中一项：
exactMatch

string

标头的值应与完全匹配的内容完全一致。
regexMatch

string

标头的值必须与 regexMatch 中指定的正则表达式匹配。如需了解正则表达式的语法，请参阅：https://github.com/google/re2/wiki/Syntax
prefixMatch

string

标头的值必须以 prefixMatch 的内容开头。
presentMatch

boolean

必须存在具有 headerName 的标头。无论标头是否包含值，都会进行匹配。
suffixMatch

string

标头的值必须以 最终到达网址后缀 Match 的内容结尾。
rangeMatch

object (IntegerRange)

指定后，如果请求标头值在此范围内，则规则将匹配。

IntegerRange

表示整数值范围。

JSON 表示法 
{
  "start": integer,
  "end": integer
}
字段
start

integer

范围的起始值（含）
end

integer

范围结束值（不含边界值）

QueryParameterMatch

用于与请求中的查询参数匹配的规范。

JSON 表示法 
{
  "queryParameter": string,

  // Union field MatchType can be only one of the following:
  "exactMatch": string,
  "regexMatch": string,
  "presentMatch": boolean
  // End of list of possible types for union field MatchType.
}
字段
queryParameter

string

要匹配的查询参数的名称。

联合字段 MatchType。

MatchType 只能是下列其中一项：
exactMatch

string

此查询参数的值必须与完全匹配的内容完全匹配。

只能设置完全匹配、正则表达式匹配和展示匹配中的一个。
regexMatch

string

查询参数的值必须与 regexMatch 指定的正则表达式匹配。如需了解正则表达式的语法，请参阅 https://github.com/google/re2/wiki/Syntax

只能设置完全匹配、正则表达式匹配和展示匹配中的一个。
presentMatch

boolean

指定在请求包含查询参数时，QueryParameterMatcher 均匹配，无论该参数是否有值。

只能设置完全匹配、正则表达式匹配和展示匹配中的一个。

RouteAction

有关路由流量和应用相关政策的规范。

JSON 表示法 
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "redirect": {
    object (Redirect)
  },
  "faultInjectionPolicy": {
    object (FaultInjectionPolicy)
  },
  "requestHeaderModifier": {
    object (HeaderModifier)
  },
  "responseHeaderModifier": {
    object (HeaderModifier)
  },
  "urlRewrite": {
    object (URLRewrite)
  },
  "timeout": string,
  "retryPolicy": {
    object (RetryPolicy)
  },
  "requestMirrorPolicy": {
    object (RequestMirrorPolicy)
  },
  "corsPolicy": {
    object (CorsPolicy)
  },
  "statefulSessionAffinity": {
    object (StatefulSessionAffinityPolicy)
  },
  "directResponse": {
    object (HttpDirectResponse)
  },
  "idleTimeout": string
}
字段
destinations[]

object (Destination)

流量应转发到的目的地。
redirect

object (Redirect)

如果设置了此字段，则系统将按照此字段的配置来定向请求。
faultInjectionPolicy

object (FaultInjectionPolicy)

为流量引入的故障注入规范，旨在测试客户端对后端服务故障的弹性。在故障注入过程中，当客户端向后端服务发送请求时，系统可能会在将一定比例的请求发送到后端服务之前引入延迟。同样，对于一定比例的请求，可以取消来自客户端的请求。

配置了 faultInjectionPolicy 的客户端将忽略超时和 reCAPTCHAPolicy
requestHeaderModifier

object (HeaderModifier)

用于在将匹配请求传送到目标位置之前修改匹配请求的标头的规范。如果同时在 Destination 和 RouteAction 中设置了 HeaderModifier，它们将会合并。两者之间的冲突不会在配置上解决。
responseHeaderModifier

object (HeaderModifier)

在将响应发送回客户端之前修改响应标头的规范。如果同时在 Destination 和 RouteAction 中设置了 HeaderModifier，它们将会合并。两者之间的冲突不会在配置上解决。
urlRewrite

object (URLRewrite)

将请求转发到目标前的重写网址规范。
timeout

string (Duration format)

指定所选路由的超时时间。超时是根据请求完成处理（即数据流结束）直到响应完成处理的时间计算得出的。超时包括所有重试。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
retryPolicy

object (RetryPolicy)

指定与此路由关联的重试政策。
requestMirrorPolicy

object (RequestMirrorPolicy)

指定关于如何将发往路由目的地的请求覆盖至单独的镜像目的地的政策。代理不会等待影子目标做出响应，然后再返回响应。在将流量发送到影子服务之前，主机/授权标头以 -shadow 为后缀。
corsPolicy

object (CorsPolicy)

关于允许客户端跨源请求的规范。
statefulSessionAffinity

object (StatefulSessionAffinityPolicy)

可选。指定基于 Cookie 的有状态会话亲和性。
directResponse

object (HttpDirectResponse)

可选。无论请求如何，系统都会返回静态 HTTP 响应对象。
idleTimeout

string (Duration format)

可选。指定所选路由的空闲超时。空闲超时是指在上行或下行连接上未发送或接收字节的时间段。如果未设置，则默认空闲超时时间为 1 小时。如果设置为 0s，超时将被停用。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

目的地

指定请求应传送到的目标的目的地。

JSON 表示法 
{
  "serviceName": string,
  "weight": integer,
  "requestHeaderModifier": {
    object (HeaderModifier)
  },
  "responseHeaderModifier": {
    object (HeaderModifier)
  }
}
字段
serviceName

string

要将流量路由到的 BackendService 的网址。
weight

integer

指定转发到 serviceName 字段引用的后端的请求比例。计算公式如下：- 权重/总和（此目标列表中的权重）。对于非零值，可能与此处定义的精确比例存在一些 epsilon，具体取决于实现支持的精度。

如果仅指定一个 serviceName 且其权重大于 0，则全部流量都会转发到该后端。

如果为任何一个服务名称指定了权重，则需要为所有服务名称指定权重。

如果未指定所有服务的权重，则流量将按照所有服务的比例进行分配。
requestHeaderModifier

object (HeaderModifier)

可选。用于在将匹配请求传送到目标位置之前修改匹配请求的标头的规范。如果同时在 Destination 和 RouteAction 中设置了 HeaderModifier，它们将会合并。两者之间的冲突不会在配置上解决。
responseHeaderModifier

object (HeaderModifier)

可选。在将响应发送回客户端之前修改响应标头的规范。如果同时在 Destination 和 RouteAction 中设置了 HeaderModifier，它们将会合并。两者之间的冲突不会在配置上解决。

HeaderModifier

关于修改 HTTP 请求和 HTTP 响应中 HTTP 标头的规范。

JSON 表示法 
{
  "set": {
    string: string,
    ...
  },
  "add": {
    string: string,
    ...
  },
  "remove": [
    string
  ]
}
字段
set

map (key: string, value: string)

使用给定映射完全覆盖/替换标头，其中 key 是标头的名称，value 是标头的值。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
add

map (key: string, value: string)

使用给定映射添加标头，其中 key 是标头的名称，value 是标头的值。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
remove[]

string

移除列表中指定的标头（与标头名称匹配的标头）。

重定向

流量重定向规范。

JSON 表示法 
{
  "hostRedirect": string,
  "pathRedirect": string,
  "prefixRewrite": string,
  "responseCode": enum (ResponseCode),
  "httpsRedirect": boolean,
  "stripQuery": boolean,
  "portRedirect": integer
}
字段
hostRedirect

string

将在重定向响应中使用的主机，而不是请求中提供的主机。
pathRedirect

string

将在重定向响应中使用的路径，而不是在请求中提供的路径。pathRedirect 不能与 prefixRedirect 一起使用。您可以单独提供一个，也可以都不提供。如果两者都未提供，则系统会将原始请求的路径用于重定向。
prefixRewrite

string

表示在重定向期间，匹配的前缀（或路径）应与此值进行交换。此选项允许根据请求动态创建网址。
responseCode

enum (ResponseCode)

用于重定向的 HTTP 状态代码。
httpsRedirect

boolean

如果此政策设为 true，被重定向请求中的网址协议 (网址 scheme) 会设为 https。如果设为 false，重定向请求的网址架构将与请求的网址架构相同。

默认值为 false。
stripQuery

boolean

如果设置为 true，则在重定向请求之前，系统会移除原始网址的任何附带查询部分。如果设置为 false，系统会保留原始网址的查询部分。

默认值为 false。
portRedirect

integer

将在重定向的请求中使用的端口，而不是请求中提供的端口。

ResponseCode

支持的 HTTP 响应代码。

枚举
RESPONSE_CODE_UNSPECIFIED 默认值
MOVED_PERMANENTLY_DEFAULT 对应于 301。
FOUND 对应于 302。
SEE_OTHER 对应于 303。
TEMPORARY_REDIRECT 对应于 307。在这种情况下，系统将保留请求方法。
PERMANENT_REDIRECT 对应于 308。在这种情况下，系统将保留请求方法。

FaultInjectionPolicy

为流量引入的故障注入规范，旨在测试客户端对目标服务故障的弹性。在故障注入过程中，当客户端向目标发送请求时，客户端代理可能会在将这些请求发送到目标服务之前，对一定比例的请求引入延迟。同样，客户端代理也可以中止一定比例的请求。

JSON 表示法 
{
  "delay": {
    object (Delay)
  },
  "abort": {
    object (Abort)
  }
}
字段
delay

object (Delay)

向客户端请求注入延迟的规范。
abort

object (Abort)

关于中止客户端请求的规范。

延迟

关于在将客户端请求发送到目的地之前，作为故障注入一部分如何延迟的规范。

JSON 表示法 
{
  "fixedDelay": string,
  "percentage": integer
}
字段
fixedDelay

string (Duration format)

在转发请求前指定固定的延迟时间。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
percentage

integer

将注入延迟的流量百分比。

该值必须介于 [0, 100] 之间

取消

关于故障注入功能在将客户端请求发送到目的地之前如何中止的规范。

JSON 表示法 
{
  "httpStatus": integer,
  "percentage": integer
}
字段
httpStatus

integer

用于中止请求的 HTTP 状态代码。

该值必须介于 200 和 599 之间（含 200 和 599）。
percentage

integer

将被取消的流量百分比。

该值必须介于 [0, 100] 之间

URLRewrite

用于在将请求转发到目标之前修改请求网址的规范。

JSON 表示法 
{
  "pathPrefixRewrite": string,
  "hostRewrite": string
}
字段
pathPrefixRewrite

string

在将请求转发到选定目的地之前，请求路径的匹配部分将替换为此值。
hostRewrite

string

在将请求转发到选定目的地之前，请求主机标头会被替换为该值。

RetryPolicy

重试规范。

JSON 表示法 
{
  "retryConditions": [
    string
  ],
  "numRetries": integer,
  "perTryTimeout": string
}
字段
retryConditions[]

string

指定此重试政策适用的一个或多个条件。有效值为：5xx：如果目标服务返回任何 5xx 响应代码（例如，断开连接、重置、读取超时、连接失败和遭到拒绝的数据流），则代理会尝试重试。

Gate-error：与 5xx 类似，但仅适用于响应代码 502、503、504。

重置：如果目标服务根本没有响应，则代理会尝试重试（断开连接/重置/读取超时）

connect-failure：代理将在连接到目标位置失败时重试（例如由于连接超时）。

retriable-4xx：代理将从可重试的 4xx 响应代码重试。目前唯一支持的可重试错误是 409。

refused-stream：如果目标位置将信息流重置为 REFUSED_STREAM 错误代码，则代理将重试。这种重置类型表示可以放心重试。
numRetries

integer

指定允许的重试次数。此数字必须大于 0。如果未指定，则默认为 1。
perTryTimeout

string (Duration format)

指定每次重试尝试的非零超时值。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

RequestMirrorPolicy

指定关于如何将请求覆盖到单独的镜像目标服务的政策。代理不会等待来自影子服务的响应。在将流量发送到影子服务之前，主机/授权标头以 -shadow 为后缀。

JSON 表示法 
{
  "destination": {
    object (Destination)
  },
  "mirrorPercent": number
}
字段
destination

object (Destination)

请求将镜像到的目标位置。该目标的权重将被忽略。
mirrorPercent

number

可选。镜像到所需目标位置的请求所占的百分比。

CorsPolicy

用于允许客户端跨源请求的规范。

JSON 表示法 
{
  "allowOrigins": [
    string
  ],
  "allowOriginRegexes": [
    string
  ],
  "allowMethods": [
    string
  ],
  "allowHeaders": [
    string
  ],
  "exposeHeaders": [
    string
  ],
  "maxAge": string,
  "allowCredentials": boolean,
  "disabled": boolean
}
字段
allowOrigins[]

string

指定允许执行 CORS 请求的来源列表。如果某个来源与 allowOrigins 中的某个项目或 allowOriginRegexes 中的某个项目匹配，则允许使用该来源。
allowOriginRegexes[]

string

指定与允许的来源匹配的正则表达式模式。如需了解正则表达式的语法，请参阅 https://github.com/google/re2/wiki/Syntax。
allowMethods[]

string

指定 Access-Control-Allow-Methods 标头的内容。
allowHeaders[]

string

指定 Access-Control-Allow-Headers 标头的内容。
exposeHeaders[]

string

指定 Access-Control-Expose-Headers 标头的内容。
maxAge

string

指定预检请求结果可以缓存多长时间（以秒为单位）。这将转换为 Access-Control-Max-Age 标头。
allowCredentials

boolean

为了响应预检请求，如果将此字段设为 true，则表示实际请求可以包含用户凭据。这将转换为 Access-Control-Allow-Credentials 标头。

默认值为 false。
disabled

boolean

如果为 true，系统会停用 CORS 政策。默认值为 false，表示 CORS 政策已生效。

StatefulSessionAffinityPolicy

基于 Cookie 的有状态会话亲和性规范，其中日期平面提供名称为“GSSA”的“会话 Cookie”，对特定目标主机进行编码，只要目标主机保持正常运行且正常运行，每个包含该 Cookie 的请求就会定向到该主机。

gRPC 无代理网格库或边车代理将管理会话 Cookie，但客户端应用代码负责将 Cookie 从会话中的每个 RPC 复制到下一个 RPC。

JSON 表示法 
{
  "cookieTtl": string
}
字段
cookieTtl

string (Duration format)

必需。数据平面生成的 Set-Cookie 标头的 Cookie TTL 值。Cookie 的生命周期可设置为 1 到 86400 秒（含 24 小时）之间的值。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

HttpDirectResponse

要返回的静态 HTTP 响应对象。

JSON 表示法 
{
  "status": integer,

  // Union field HttpBody can be only one of the following:
  "stringBody": string,
  "bytesBody": string
  // End of list of possible types for union field HttpBody.
}
字段
status

integer

必需。要作为 HTTP 响应的一部分返回的状态。必须是正整数。
联合字段 HttpBody。要作为 HTTP 响应的一部分返回的正文。HttpBody 只能是下列其中一项：
stringBody

string

可选。以字符串表示的响应正文。正文长度上限为 1024 个字符。
bytesBody

string (bytes format)

可选。响应正文（以字节表示）。正文大小上限为 4096B。

使用 base64 编码的字符串。

方法

create

 在给定的项目和位置中创建一个新的 HttpRoute。

delete

 删除单个 HttpRoute。

get

 获取单个 HttpRoute 的详细信息。

list

 列出给定项目和位置中的 HttpRoute。

patch

 更新单个 HttpRoute 的参数。