REST Resource: projects.locations.httpRoutes

资源：HttpRoute

HttpRoute 是定义 HTTP 流量应由 Mesh 或 Gateway 资源进行路由方式的资源。

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，标签必须由小写字母、数字字符或“-”组成，并以字母数字字符开头和结尾。不允许使用其他标点符号。

与 Mesh 或 Gateway 关联的路由必须具有唯一的主机名。如果您尝试附加具有冲突主机名的多个路由，则系统会拒绝该配置。

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

string

可选。Meshes 定义此 TlsRoute 所附加的网格列表，作为用于路由网格所处理的请求的路由规则之一。

每个 Mesh 引用都应符合格式 projects/*/locations/global/meshes/<mesh_name>

附加的 Mesh 类型应为 SIDECAR
gateways[]

string

可选。Gateways 定义此 HttpRoute 所附加的网关列表，作为用于路由网关所处理的请求的路由规则之一。

每个 Gateway 引用都应符合以下格式：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

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

string

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

string

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

boolean

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

string

标头的值必须以 suffixMatch 的内容结尾。
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

查询参数的值必须与 exactMatch 的内容完全一致。

必须设置 exactMatch、regexMatch 或 presentMatch 中的一项。
regexMatch

string

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

必须设置 exactMatch、regexMatch 或 presentMatch 中的一项。
presentMatch

boolean

指定当请求中包含查询参数时，QueryParameterMatcher 即视为匹配，无论该参数是否有值。

必须设置 exactMatch、regexMatch 或 presentMatch 中的一项。

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 配置的客户端会忽略 timeout 和 retryPolicy
requestHeaderModifier

object (HeaderModifier)

在将请求传送到目标位置之前修改匹配请求的标头的规范。如果在 Destination 和 RouteAction 中都设置了 HeaderModifiers，则会合并。这两者之间的冲突不会通过配置进行解决。
responseHeaderModifier

object (HeaderModifier)

在将响应发回客户端之前修改响应标头的规范。如果在 Destination 和 RouteAction 中都设置了 HeaderModifiers，则会合并。这两者之间的冲突不会通过配置进行解决。
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 小时。如果设置为 0 秒，则会停用超时。

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

目的地

关于请求应路由到的目标的规范说明。

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

string

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

integer

指定转发到 serviceName 字段所引用后端的请求比例。计算方式如下：- 权重 ÷ 此目标列表中的总权重。对于非零值，根据实现支持的精度，相对于此处定义的确切比例可能会存在一些小数。

如果只指定了一个 serviceName，并且其权重大于 0，则 100% 的流量会转发到该后端。

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

如果未为所有服务指定权重，则系统会按相等的比例将流量分配给所有服务。
requestHeaderModifier

object (HeaderModifier)

可选。在将请求传送到目标位置之前修改匹配请求的标头的规范。如果在 Destination 和 RouteAction 中都设置了 HeaderModifiers，则会合并。这两者之间的冲突不会通过配置进行解决。
responseHeaderModifier

object (HeaderModifier)

可选。在将响应发回客户端之前修改响应标头的规范。如果在 Destination 和 RouteAction 中都设置了 HeaderModifiers，则会合并。这两者之间的冲突不会通过配置进行解决。

HeaderModifier

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

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

map (key: string, value: string)

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

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

map (key: string, value: string)

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

包含一系列 "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，则重定向请求中的网址架构会设置为 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（含）之间。
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 响应代码，或者目标服务根本不响应（例如断开连接、重置、读取超时、连接失败和拒绝流），代理将尝试重试。

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

reset：如果目标服务完全没有响应（断开连接/重置/读取超时），代理将尝试重试

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 会对特定目标主机进行编码。只要该主机保持运行且健康，包含该 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

可选。响应正文作为字符串。正文的最大长度为 1,024 个字符。
bytesBody

string (bytes format)

可选。响应正文（以字节为单位）。正文的最大大小为 4096B。

使用 base64 编码的字符串。

方法

create

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

delete

 删除单个 HttpRoute。

get

 获取单个 HttpRoute 的详细信息。

getIamPolicy

 获取资源的访问权限控制政策。

list

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

patch

 更新单个 HttpRoute 的参数。

setIamPolicy

 针对指定资源设置访问权限控制政策。

testIamPermissions

 返回调用者对指定资源拥有的权限。