REST Resource: projects.locations.grpcRoutes

资源：GrpcRoute

GrpcRoute 是定义由网格或网关资源路由的 gRPC 流量路由方式的资源。

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

string

必需。GrpcRoute 资源的名称。该名称符合格式 projects/*/locations/global/grpcRoutes/<grpc_route_name>。
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"。
labels

map (key: string, value: string)

可选。与 GrpcRoute 资源关联的一组标签标记。

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

string

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

string

必需。服务主机名，以及此路由描述流量的可选端口。

格式：[:]

主机名是网络主机的完全限定域名。这与 RFC 1123 对主机名的定义相符，但有 2 个需要注意的例外情况：- 不允许使用 IP。- 主机名可以使用通配符标签 (*.) 作为前缀。通配符标签必须单独作为第一个标签出现。

主机名可以是“精确”主机名（即没有网络主机的结束点的域名，例如 foo.example.com）或“通配符”主机名（即前缀为单个通配符标签的域名，例如 *.example.com）。

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

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

例如，虽然主机名 *.foo.bar.com 和 *.bar.com 的路由可以与同一路由关联，但两个路由无法同时与 *.bar.com 或 bar.com 关联。

如果指定了端口，gRPC 客户端必须使用包含该端口的通道 URI 来匹配此规则（即“xds:///service:123”），否则必须提供不包含该端口的 URI（即“xds:///service”）。
meshes[]

string

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

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

string

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

每个 Gateway 引用都应符合以下格式：projects/*/locations/global/gateways/<gateway_name>
rules[]

object (RouteRule)

必需。定义如何路由流量的详细规则列表。

在单个 GrpcRoute 中，系统会执行与第一个匹配的 GrpcRoute.RouteRule 关联的 GrpcRoute.RouteAction。必须至少提供一条规则。

RouteRule

说明如何路由流量。

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

object (RouteMatch)

可选。匹配项定义了用于将规则与传入的 gRPC 请求进行匹配的条件。每个匹配项都是独立的，也就是说，只要有任一匹配项满足该规则，系统就会匹配该规则。如果未指定任何匹配字段，则此规则将无条件地匹配流量。
action

object (RouteAction)

必需。定义如何路由流量的详细规则。此字段是必填字段。

RouteMatch

匹配流量的条件。当所有提供的字段都匹配时，RouteMatch 才会被视为匹配。

JSON 表示法 
{
  "headers": [
    {
      object (HeaderMatch)
    }
  ],
  "method": {
    object (MethodMatch)
  }
}
字段
headers[]

object (HeaderMatch)

可选。指定要匹配的标头集合。
method

object (MethodMatch)

可选。要进行匹配的 gRPC 方法。如果此字段为空或省略，将匹配所有方法。

MethodMatch

指定与某个方法进行匹配。

JSON 表示法 
{
  "type": enum (Type),
  "grpcService": string,
  "grpcMethod": string,
  "caseSensitive": boolean
}
字段
type

enum (Type)

可选。指定如何与名称进行匹配。如果未指定，则使用默认值“EXACT”。
grpcService

string

必需。要进行匹配的服务的名称。如果未指定该项，则与所有服务进行匹配。
grpcMethod

string

必需。要进行匹配的方法的名称。如果未指定，将匹配所有方法。
caseSensitive

boolean

可选。指定匹配区分大小写。默认值为 true。caseSensitive 不得与 REGULAR_EXPRESSION 类型搭配使用。

类型

匹配类型。

枚举
TYPE_UNSPECIFIED 未指定。
EXACT 将仅匹配提供的确切名称。
REGULAR_EXPRESSION 会将 grpcMethod 和 grpcService 解读为正则表达式。支持 RE2 语法。

HeaderMatch

与一组标头进行匹配。

JSON 表示法 
{
  "type": enum (Type),
  "key": string,
  "value": string
}
字段
type

enum (Type)

可选。指定如何与标头的值进行匹配。如果未指定该项，则使用默认值 EXACT。
key

string

必需。标头的键。
value

string

必需。标头的值。

类型

匹配类型。

枚举
TYPE_UNSPECIFIED 未指定。
EXACT 将仅匹配提供的确切值。
REGULAR_EXPRESSION 将匹配与值指定的前缀相符的路径。支持 RE2 语法。

RouteAction

指定如何路由匹配的流量。

JSON 表示法 
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "faultInjectionPolicy": {
    object (FaultInjectionPolicy)
  },
  "timeout": string,
  "retryPolicy": {
    object (RetryPolicy)
  },
  "statefulSessionAffinity": {
    object (StatefulSessionAffinityPolicy)
  },
  "idleTimeout": string
}
字段
destinations[]

object (Destination)

可选。流量应转发到的目标服务。如果指定了多个目标，系统会根据这些目标的权重字段在后端服务之间拆分流量。
faultInjectionPolicy

object (FaultInjectionPolicy)

可选。用于在流量中引入故障注入以测试客户端对目标服务故障的弹性的规范。作为故障注入的一部分，当客户端向目标发送请求时，客户端可能会在将这些请求发送到目标服务之前，对一定比例的请求引入延迟。同样，系统可能会中止来自客户端的部分请求。

使用 faultInjectionPolicy 配置的客户端会忽略 timeout 和 retryPolicy
timeout

string (Duration format)

可选。指定所选路由的超时时长。超时是从请求完全处理（即流结束）到响应完全处理的时间计算得出的。超时包括所有重试。

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

object (RetryPolicy)

可选。指定与此路由关联的重试政策。
statefulSessionAffinity

object (StatefulSessionAffinityPolicy)

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

string (Duration format)

可选。指定所选路由的空闲超时时间。空闲超时时间定义为上行或下行连接未发送或未接收任何字节的时间段。如果未设置，则默认空闲超时时间为 1 小时。如果设置为 0 秒，则系统会停用超时。

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

目的地

流量将被路由到的目标。

JSON 表示法 
{

  // Union field destination_type can be only one of the following:
  "serviceName": string
  // End of list of possible types for union field destination_type.
  "weight": integer
}
字段
联合字段 destination_type。指定将路由流量的目标种类。destination_type 只能是下列其中一项：
serviceName

string

必需。要将流量路由到的目标服务的网址。必须引用 BackendService 或 ServiceDirectoryService。
weight

integer

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

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

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

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

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 之间。

RetryPolicy

重试的规范。

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

string

  • connect-failure：路由器会在连接到后端服务失败（例如由于连接超时）时重试。
  • refused-stream：如果后端服务因为系统出现 REFUSED_STREAM 错误代码而重置数据流，则路由器将重试。此重置类型表示可以安全地重试。
  • cancelled：如果响应标头中的 gRPC 状态代码设置为 cancelled，路由器将重试
  • deadline-exceeded：如果响应标头中的 gRPC 状态代码设置为 deadline-exceeded，路由器将重试
  • resource-exhausted：如果响应标头中的 gRPC 状态代码设置为 resource-exhausted，路由器将重试
  • unavailable：如果响应标头中的 gRPC 状态代码设置为 unavailable，路由器将重试
numRetries

integer (uint32 format)

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

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"。

方法

create

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

delete

 删除单个 GrpcRoute。

get

 获取单个 GrpcRoute 的详细信息。

list

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

patch

 更新单个 GrpcRoute 的参数。

setIamPolicy

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

testIamPermissions

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