- 资源:HttpRoute
- RouteRule
- RouteMatch
- HeaderMatch
- IntegerRange
- QueryParameterMatch
- RouteAction
- 目标
- HeaderModifier
- 重定向
- ResponseCode
- FaultInjectionPolicy
- 延迟
- Abort
- URLRewrite
- RetryPolicy
- RequestMirrorPolicy
- CorsPolicy
- StatefulSessionAffinityPolicy
- HttpDirectResponse
- 方法
资源:HttpRoute
HttpRoute 是一项资源,用于定义应如何由 Mesh 或 Gateway 资源路由 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[] |
可选。网格定义了此 HttpRoute 附加的网格的列表,作为路由规则之一,用于路由由网格处理的请求。 每个网格引用都应与模式匹配: 附加的网格的类型应为 SIDECAR |
gateways[] |
可选。Gateways 定义了此 HttpRoute 附加到的网关列表,作为路由网关所处理请求的路由规则之一。 每个网关引用都应与以下模式匹配: |
labels |
可选。与 HttpRoute 资源关联的一组标签。 包含一系列 |
rules[] |
必需。用于定义流量路由和处理方式的规则。系统会根据为规则指定的 RouteMatch 依序匹配规则。 |
RouteRule
指定如何匹配流量以及如何在匹配流量时路由流量。
JSON 表示法 |
---|
{ "matches": [ { object ( |
字段 | |
---|---|
matches[] |
匹配项列表定义了用于将规则与传入 HTTP 请求匹配的条件。每项匹配都是独立的,也就是说,只要满足其中任一匹配条件,系统就会匹配此规则。 如果未指定任何匹配字段,此规则将无条件匹配流量。 如果您想配置默认规则,请在规则列表的末尾添加一个未指定任何匹配项的规则。 |
action |
定义如何路由匹配流量的详细规则。 |
RouteMatch
RouteMatch 定义了用于匹配请求的规范。如果设置了多种匹配类型,则只要所有类型的匹配都匹配,此 RouteMatch 就会匹配。
JSON 表示法 |
---|
{ "ignoreCase": boolean, "headers": [ { object ( |
字段 | |
---|---|
ignoreCase |
指定 prefixMatch 和 fullPathMatch 匹配项是否区分大小写。默认值为 false。 |
headers[] |
指定要匹配的 HTTP 请求标头列表。必须匹配所提供的所有标头。 |
queryParameters[] |
指定要匹配的查询参数列表。所有查询参数都必须匹配。 |
联合字段
|
|
fullPathMatch |
HTTP 请求路径值应与此值完全匹配。 请仅使用 fullPathMatch、prefixMatch 或 regexMatch 之一。 |
prefixMatch |
HTTP 请求路径值必须以指定的前缀匹配开头。前缀匹配必须以 / 开头。 只能使用 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 |
查询参数的值必须与完全匹配的内容完全匹配。 只能设置完全匹配、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 |
在将请求传送到目标之前修改匹配请求标头的规范。如果同时在 Destination 和 RouteAction 上设置了 HeaderModifier,它们会合并。配置不会解决这两者之间的冲突。 |
responseHeaderModifier |
在将响应发送回客户端之前修改响应标头的规范。如果同时在 Destination 和 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 |
可选。在将请求传送到目标之前修改匹配请求标头的规范。如果同时在 Destination 和 RouteAction 上设置了 HeaderModifier,它们会合并。两者之间的冲突不会在配置中得到解决。 |
responseHeaderModifier |
可选。在将响应发送回客户端之前修改响应标头的规范。如果同时在 Destination 和 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 之间(含 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 的有状态会话亲和性规范,其中日期平面提供“会话 Cookie”名为“GSSA”该方法会对特定目标主机进行编码,只要目标主机保持正常运行且健康状况良好,包含该 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 的参数。 |