REST Resource: projects.locations.grpcRoutes

資源：GrpcRoute

GrpcRoute 是定義 Mesh 或 Gateway 資源如何轉送 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 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。例如："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

僅供輸出。資源更新時間的時間戳記。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。例如："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

(非必要) 網格定義了這個 GrpcRoute 附加的網格清單，做為轉送規則之一，用於轉送網格提供的要求。

每個網格參照都應符合以下格式：projects/*/locations/global/meshes/<mesh_name>
gateways[]

string

(非必要) 閘道定義了這個 GrpcRoute 所連結的閘道清單，做為轉送規則之一，用於轉送閘道提供的要求。

每個閘道參照都應符合以下格式：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)

(非必要) 指定所選路徑的逾時時間。系統會從要求完全處理完畢 (即串流結束) 到回應完全處理完畢之間的時間，計算逾時時間。逾時時間包括所有重試時間。

以秒為單位的時間長度，最多可有 9 個小數位數，結尾為「s」，例如："3.5s"。
retryPolicy

object (RetryPolicy)

(非必要) 指定與此路徑相關的重試政策。
statefulSessionAffinity

object (StatefulSessionAffinityPolicy)

(非必要) 指定以 Cookie 為基礎的有狀態工作階段相依性。
idleTimeout

string (Duration format)

(非必要) 指定所選路徑的閒置逾時時間。閒置逾時時間的定義為上游或下游連線在一段時間內未傳送或接收任何位元組的時間。如果未設定，預設閒置逾時時間為 1 小時。如果設為 0 秒，系統就會停用逾時設定。

以秒為單位的時間長度，最多可有 9 個小數位數，結尾為「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 欄位所參照後端的比例。計算方式如下：- 權重/Sum(這個目的地清單中的權重)。對於非零值，實際比例可能會與此處定義的確切比例有些許差異，具體取決於實作項目支援的精確度。

如果只指定一個 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)

在轉送要求前指定固定延遲時間。

以秒為單位的時間長度，最多可有 9 個小數位數，結尾為「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 狀態碼設為已取消，路由器會重試
  • deadline-exceeded：如果回應標頭中的 gRPC 狀態碼設為 deadline-exceeded，路由器就會重試
  • resource-exhausted：如果回應標頭中的 gRPC 狀態碼設為 resource-exhausted，路由器就會重試
  • unavailable：如果回應標頭中的 gRPC 狀態碼設為 unavailable，路由器會重試
numRetries

integer (uint32 format)

指定允許的重試次數。這個數字必須大於 0。如未指定，則預設為 1。

StatefulSessionAffinityPolicy

這份規格說明 Cookie 型有狀態工作階段相依性，其中日期平面會提供名稱為「GSSA」的「工作階段 Cookie」，用於編碼特定目的地主機，只要目的地主機保持運作正常，每個含有該 Cookie 的要求都會導向該主機。

gRPC 無 Proxy 的 Mesh 程式庫或附加 Proxy 會管理工作階段 Cookie，但用戶端應用程式程式碼負責將 Cookie 從工作階段中的每個 RPC 複製到下一個。

JSON 表示法 
{
  "cookieTtl": string
}
欄位
cookieTtl

string (Duration format)

這是必要旗標，資料層產生的 Set-Cookie 標頭 Cookie TTL 值。Cookie 的生命週期可以設為 1 到 86400 秒 (24 小時) 之間的值 (含首尾值)。

以秒為單位的時間長度，最多可有 9 個小數位數，結尾為「s」，例如："3.5s"。

方法

create

 在指定專案和位置中建立新的 GrpcRoute。

delete

 刪除單一 GrpcRoute。

get

 取得單一 GrpcRoute 的詳細資料。

list

 列出指定專案和位置中的 GrpcRoute。

patch

 更新單一 GrpcRoute 的參數。

setIamPolicy

 設定指定資源的存取權控管政策。

testIamPermissions

 傳回呼叫者在指定資源上擁有的權限。