- 资源:HttpRoute
- RouteRule
- RouteMatch
- HeaderMatch
- IntegerRange
- QueryParameterMatch
- RouteAction
- 目标
- HeaderModifier
- 重定向
- ResponseCode
- FaultInjectionPolicy
- 延迟
- Abort
- URLRewrite
- RetryPolicy
- RequestMirrorPolicy
- CorsPolicy
- StatefulSessionAffinityPolicy
- HttpDirectResponse
- 方法
资源:HttpRoute
HttpRoute 是用于定义 Mesh 或网关资源应如何路由 HTTP 流量的资源。
JSON 表示法 |
---|
{
"name": string,
"selfLink": string,
"description": string,
"createTime": string,
"updateTime": string,
"hostnames": [
string
],
"meshes": [
string
],
"gateways": [
string
],
"labels": {
string: string,
...
},
"rules": [
{
object ( |
字段 | |
---|---|
name |
必需。HttpRoute 资源的名称。它与 |
selfLink |
仅限输出。此资源的服务器定义网址 |
description |
可选。资源的自由文本说明。长度上限为 1024 个字符。 |
createTime |
仅限输出。创建资源时的时间戳。 时间戳采用 RFC3339 世界协调时间(UTC,即“祖鲁时”)格式,精确到纳秒,最多九个小数位。示例: |
updateTime |
仅限输出。更新资源时的时间戳。 时间戳采用 RFC3339 世界协调时间(UTC,即“祖鲁时”)格式,精确到纳秒,最多九个小数位。示例: |
hostnames[] |
必需。主机名定义一组主机,它们应与 HTTP 主机标头匹配,以便选择要用于处理请求的 HttpRoute。主机名是网络主机的完全限定域名(按 RFC 1123 标准定义),但以下情况除外:- 不允许使用 IP 地址。- 主机名可以带有通配符标签 ( 主机名可以是“精确”主机名(即不带网络主机结束点的域名,例如 请注意,根据 RFC1035 和 RFC1123,标签必须由小写字母数字字符或“-”组成,并以字母数字字符开头和结尾。不允许使用其他标点符号。 与网状网络或网关关联的路由必须具有唯一的主机名。如果您尝试附加具有冲突主机名的多个路线,系统会拒绝相应配置。 例如,虽然主机名 |
meshes[] |
可选。“Meshes”定义了此 HttpRoute 附加到的网格列表,作为路由网格提供的请求的路由规则之一。 每个网格引用都应与以下模式匹配: 附加的网格应为 SIDECAR 类型 |
gateways[] |
可选。Gateways 定义了此 HttpRoute 附加到的网关列表,作为路由网关所处理请求的路由规则之一。 每个网关引用都应与以下模式匹配: |
labels |
可选。与 HttpRoute 资源关联的一组标签。 包含一系列 |
rules[] |
必需。用于定义流量路由和处理方式的规则。系统会根据为规则指定的 RouteMatch 依序匹配规则。 |
RouteRule
指定如何匹配流量以及如何在匹配流量时路由流量。
JSON 表示法 |
---|
{ "matches": [ { object ( |
字段 | |
---|---|
matches[] |
匹配项列表定义了用于将规则与传入 HTTP 请求进行匹配的条件。每项匹配都是独立的,也就是说,只要满足其中任一匹配条件,系统就会匹配此规则。 如果未指定任何 matches 字段,此规则将无条件匹配流量。 如果您想配置默认规则,请在规则列表的末尾添加一个未指定任何匹配项的规则。 |
action |
用于定义如何路由匹配流量的详细规则。 |
RouteMatch
RouteMatch 定义了用于匹配请求的规范。如果设置了多个匹配类型,则只要所有类型的匹配都匹配,此 RouteMatch 就会匹配。
JSON 表示法 |
---|
{ "ignoreCase": boolean, "headers": [ { object ( |
字段 | |
---|---|
ignoreCase |
指定 prefixMatch 和 fullPathMatch 匹配项是否区分大小写。默认值为 false。 |
headers[] |
指定要匹配的 HTTP 请求标头列表。必须匹配所提供的所有标头。 |
queryParameters[] |
指定要匹配的查询参数列表。所有查询参数都必须匹配。 |
联合字段
|
|
fullPathMatch |
HTTP 请求路径值应与此值完全匹配。 请仅使用 fullPathMatch、prefixMatch 或 regexMatch 之一。 |
prefixMatch |
HTTP 请求路径值必须以指定的 prefixMatch 开头。prefixMatch 必须以 / 开头。 请仅使用 fullPathMatch、prefixMatch 或 regexMatch 之一。 |
regexMatch |
移除原始网址随附的所有查询参数和锚点后,HTTP 请求路径值必须满足 regexMatch 指定的正则表达式。如需了解正则表达式语法,请参阅 https://github.com/google/re2/wiki/Syntax 请仅使用 fullPathMatch、prefixMatch 或 regexMatch 之一。 |
HeaderMatch
指定如何根据 HTTP 请求标头选择路由规则。
JSON 表示法 |
---|
{ "header": string, "invertMatch": boolean, // Union field |
字段 | |
---|---|
header |
要匹配的 HTTP 标头的名称。 |
invertMatch |
如果指定,系统会在检查之前反转匹配结果。默认值设为 false。 |
联合字段
|
|
exactMatch |
标头的值应与 exactMatch 的内容完全匹配。 |
regexMatch |
标头的值必须与 regexMatch 中指定的正则表达式匹配。如需了解正则表达式语法,请参阅:https://github.com/google/re2/wiki/Syntax |
prefixMatch |
标头的值必须以 prefixMatch 的内容开头。 |
presentMatch |
必须存在具有 headerName 的标头。无论标头是否有值,都会进行匹配。 |
suffixMatch |
标头的值必须以 suffixMatch 的内容结尾。 |
rangeMatch |
如果指定了此值,则如果请求标头值在范围内,则规则将匹配。 |
IntegerRange
表示整数值范围。
JSON 表示法 |
---|
{ "start": integer, "end": integer } |
字段 | |
---|---|
start |
范围的开始值(含) |
end |
范围的结束值(不含) |
QueryParameterMatch
用于匹配请求中的查询参数的规范。
JSON 表示法 |
---|
{ "queryParameter": string, // Union field |
字段 | |
---|---|
queryParameter |
要匹配的查询参数的名称。 |
联合字段
|
|
exactMatch |
查询参数的值必须与 exactMatch 的内容完全匹配。 必须仅设置 exactMatch、regexMatch 或 presentMatch 之一。 |
regexMatch |
查询参数的值必须与 regexMatch 指定的正则表达式匹配。如需了解正则表达式语法,请参阅 https://github.com/google/re2/wiki/Syntax 必须仅设置 exactMatch、regexMatch 或 presentMatch 之一。 |
presentMatch |
指定如果请求包含查询参数,无论该参数是否有值,QueryParameterMatcher 都会匹配。 必须仅设置 exactMatch、regexMatch 或 presentMatch 之一。 |
RouteAction
用于路由流量和应用关联政策的规范。
JSON 表示法 |
---|
{ "destinations": [ { object ( |
字段 | |
---|---|
destinations[] |
应将流量转发到的目标。 |
redirect |
如果设置,系统会按此字段的配置转送请求。 |
faultInjectionPolicy |
用于向流量注入故障的规范,以测试客户端对后端服务故障的弹性。在故障注入过程中,当客户端向后端服务发送请求时,系统可能会在将这些请求发送到后端服务之前,对一定比例的请求引入延迟。同样,系统可能会针对一定比例的请求终止来自客户端的请求。 使用 faultInjectionPolicy 配置的客户端会忽略 timeout 和 retryPolicy |
requestHeaderModifier |
用于在将请求传送到目的地之前修改匹配请求标头的规范。如果在目的地和 RouteAction 上都设置了 HeaderModifier,则它们会合并。配置不会解决这两者之间的冲突。 |
responseHeaderModifier |
用于在将响应发回给客户端之前修改响应标头的规范。如果在目的地和 RouteAction 上都设置了 HeaderModifier,则它们会合并。配置不会解决这两者之间的冲突。 |
urlRewrite |
在将请求转发到目标位置之前重写网址的规范。 |
timeout |
指定选定路由的超时时长。超时是根据从请求完全处理(即数据流结束)到响应完全处理的时间计算得出的。超时包括所有重试。 该时长以秒为单位,最多包含九个小数位,以“ |
retryPolicy |
指定与此路线关联的重试政策。 |
requestMirrorPolicy |
指定将路由目的地请求投影到单独的镜像目的地的政策。代理不会等待影子目标响应,而是会直接返回响应。在将流量发送到影子服务之前,主机/权威标头会附加 -shadow 后缀。 |
corsPolicy |
允许客户端跨源请求的规范。 |
statefulSessionAffinity |
可选。指定基于 Cookie 的有状态会话亲和性。 |
directResponse |
可选。无论请求如何,都会返回的静态 HTTP 响应对象。 |
idleTimeout |
可选。指定选定路由的空闲超时时间。闲置超时是指上游或下游连接上没有发送或接收任何字节的时间段。如果未设置,默认空闲超时时间为 1 小时。如果设置为 0 秒,则会停用超时。 该时长以秒为单位,最多包含九个小数位,以“ |
目的地
应将请求路由到的目标的规范。
JSON 表示法 |
---|
{ "serviceName": string, "weight": integer, "requestHeaderModifier": { object ( |
字段 | |
---|---|
serviceName |
要将流量路由到的 BackendService 的网址。 |
weight |
指定转发到 serviceName 字段所引用的后端的请求比例。计算公式如下:- weight/Sum(weights in this destination list)。对于非零值,此处定义的确切比例可能会与实际比例存在一些 epsilon,具体取决于实现支持的精度。 如果只指定了 1 个 serviceName,并且其权重大于 0,则系统会将 100% 的流量转发到该后端。 如果为任一服务名称指定了权重,则需要为所有服务名称指定权重。 如果未为所有服务指定权重,则流量会按相等的比例分配给所有服务。 |
requestHeaderModifier |
可选。用于在将请求传送到目的地之前修改匹配请求标头的规范。如果在目的地和 RouteAction 上都设置了 HeaderModifier,则它们会合并。配置不会解决这两者之间的冲突。 |
responseHeaderModifier |
可选。用于在将响应发回给客户端之前修改响应标头的规范。如果在目的地和 RouteAction 上都设置了 HeaderModifier,则它们会合并。配置不会解决这两者之间的冲突。 |
HeaderModifier
用于修改 HTTP 请求和 HTTP 响应中的 HTTP 标头的规范。
JSON 表示法 |
---|
{ "set": { string: string, ... }, "add": { string: string, ... }, "remove": [ string ] } |
字段 | |
---|---|
set |
使用给定映射完全覆盖/替换标头,其中键是标头的名称,值是标头的值。 包含一系列 |
add |
使用给定映射添加标头,其中键是标头的名称,值是标头的值。 包含一系列 |
remove[] |
移除列表中指定的标头(按标头名称匹配)。 |
重定向
用于重定向流量的规范。
JSON 表示法 |
---|
{
"hostRedirect": string,
"pathRedirect": string,
"prefixRewrite": string,
"responseCode": enum ( |
字段 | |
---|---|
hostRedirect |
将在重定向响应中使用的主机,而不是在请求中提供的主机。 |
pathRedirect |
将在重定向响应中使用的路径,而不是在请求中提供的路径。pathRedirect 不能与 prefixRedirect 一起提供。请单独提供其中一个,或都不提供。如果未提供这两者,系统将使用原始请求的路径进行重定向。 |
prefixRewrite |
表示在重定向期间,匹配的前缀(或路径)应与此值交换。此选项允许根据请求动态创建网址。 |
responseCode |
要用于重定向的 HTTP 状态代码。 |
httpsRedirect |
如果设置为 true,则重定向请求中的网址架构会设为 https。如果设置为 false,重定向请求的网址 scheme 将保持与请求的 scheme 相同。 默认值设为 false。 |
stripQuery |
如果设置为 true,系统会在重定向请求之前移除原始网址的任何随附查询部分。如果设置为 false,系统会保留原始网址的查询部分。 默认值设为 false。 |
portRedirect |
将在重定向请求中使用的端口,而不是在请求中提供的端口。 |
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 |
用于中止客户端请求的规范。 |
延迟
规范了在发送到目的地之前,客户端请求在故障注入过程中的延迟方式。
JSON 表示法 |
---|
{ "fixedDelay": string, "percentage": integer } |
字段 | |
---|---|
fixedDelay |
在转发请求之前指定固定延迟时间。 该时长以秒为单位,最多包含九个小数位,以“ |
percentage |
将注入延迟的流量的百分比。 值必须介于 [0, 100] 之间 |
取消
规范了在发送到目的地之前,如何在故障注入过程中中止客户端请求。
JSON 表示法 |
---|
{ "httpStatus": integer, "percentage": integer } |
字段 | |
---|---|
httpStatus |
用于终止请求的 HTTP 状态代码。 该值必须介于 200 到 599 之间(包括这两个数值)。 |
percentage |
将被中止的流量的百分比。 值必须介于 [0, 100] 之间 |
URLRewrite
用于在将请求转发到目的地之前修改请求网址的规范。
JSON 表示法 |
---|
{ "pathPrefixRewrite": string, "hostRewrite": string } |
字段 | |
---|---|
pathPrefixRewrite |
在将请求转发到选定的目标之前,请求路径的匹配部分会被替换为此值。 |
hostRewrite |
在将请求转发到所选目的地之前,请求的主机标头会被替换为此值。 |
RetryPolicy
重试的规范。
JSON 表示法 |
---|
{ "retryConditions": [ string ], "numRetries": integer, "perTryTimeout": string } |
字段 | |
---|---|
retryConditions[] |
指定此重试政策适用的一个或多个条件。有效值:5xx:如果目标服务响应任何 5xx 响应代码,或者目标服务完全没有响应(例如:断开连接、重置、读取超时、连接失败和拒绝流式传输),代理将尝试重试。 gateway-error:类似于 5xx,但仅适用于响应代码 502、503、504。 reset:如果目标服务完全没有响应(断开连接/重置/读取超时),代理将尝试重试 connect-failure:如果连接到目标位置失败(例如由于连接超时),代理将重试。 retriable-4xx:代理会针对可重试的 4xx 响应代码进行重试。目前,唯一支持的可重试错误是 409。 refused-stream:如果目标使用 REFUSED_STREAM 错误代码重置了流,代理将重试。此重置类型表示可以放心地重试。 |
numRetries |
指定允许的重试次数。此数字必须大于 0。如果未指定,则默认为 1。 |
perTryTimeout |
为每次重试指定非零超时。 该时长以秒为单位,最多包含九个小数位,以“ |
RequestMirrorPolicy
指定有关如何将请求投影到单独的镜像目标服务的政策。代理不会等待影子服务的响应。在将流量发送到影子服务之前,主机/权威标头会附加 -shadow 后缀。
JSON 表示法 |
---|
{
"destination": {
object ( |
字段 | |
---|---|
destination |
请求的镜像目标。系统会忽略目的地的权重。 |
mirrorPercent |
可选。镜像到所需目标位置的请求所占的百分比。 |
CorsPolicy
允许客户端跨源请求的规范。
JSON 表示法 |
---|
{ "allowOrigins": [ string ], "allowOriginRegexes": [ string ], "allowMethods": [ string ], "allowHeaders": [ string ], "exposeHeaders": [ string ], "maxAge": string, "allowCredentials": boolean, "disabled": boolean } |
字段 | |
---|---|
allowOrigins[] |
指定允许执行 CORS 请求的来源列表。如果某个来源与 allowOrigins 或 allowOriginRegexes 中的某个项匹配,则该来源是允许的。 |
allowOriginRegexes[] |
指定与允许的来源匹配的正则表达式模式。如需了解正则表达式语法,请参阅 https://github.com/google/re2/wiki/Syntax。 |
allowMethods[] |
指定 Access-Control-Allow-Methods 标头的内容。 |
allowHeaders[] |
指定 Access-Control-Allow-Headers 标头的内容。 |
exposeHeaders[] |
指定 Access-Control-Expose-Headers 标头的内容。 |
maxAge |
指定预检请求的结果可以缓存多长时间(以秒为单位)。这将转换为 Access-Control-Max-Age 标头。 |
allowCredentials |
为了响应预检请求,将此值设为 true 表示实际请求可以包含用户凭据。这将转换为 Access-Control-Allow-Credentials 标头。 默认值为 false。 |
disabled |
如果为 true,则表示 CORS 政策已停用。默认值为 false,表示 CORS 政策有效。 |
StatefulSessionAffinityPolicy
基于 Cookie 的有状态会话亲和性的规范,其中日期平面会提供一个名为“GSSA”的“会话 Cookie”,用于编码特定的目标主机,并且只要目标主机保持正常运行,包含该 Cookie 的每个请求都会被定向到该主机。
gRPC 无代理网格库或边车代理将管理会话 Cookie,但客户端应用代码负责将 Cookie 从会话中的每个 RPC 复制到下一个 RPC。
JSON 表示法 |
---|
{ "cookieTtl": string } |
字段 | |
---|---|
cookieTtl |
必需。数据平面生成的 Set-Cookie 标头的 Cookie TTL 值。Cookie 的生命周期可设置为介于 1 到 86400 秒(24 小时)之间的值(包括这两个数值)。 该时长以秒为单位,最多包含九个小数位,以“ |
HttpDirectResponse
要返回的静态 HTTP 响应对象。
JSON 表示法 |
---|
{ "status": integer, // Union field |
字段 | |
---|---|
status |
必需。要作为 HTTP 响应的一部分返回的状态。必须是正整数。 |
联合字段 HttpBody 。要作为 HTTP 响应的一部分返回的正文。HttpBody 只能是下列其中一项: |
|
stringBody |
可选。响应正文(字符串)。正文的长度上限为 1,024 个字符。 |
bytesBody |
可选。响应正文(以字节为单位)。正文大小上限为 4096B。 使用 base64 编码的字符串。 |
方法 |
|
---|---|
|
在给定的项目和位置中创建新的 HttpRoute。 |
|
删除单个 HttpRoute。 |
|
获取单个 HttpRoute 的详细信息。 |
|
列出给定项目和位置中的 HttpRoute。 |
|
更新单个 HttpRoute 的参数。 |