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

ID。GrpcRoute 資源的名稱。符合模式 projects/*/locations/global/grpcRoutes/<grpc_route_name>
createTime

string (Timestamp format)

僅供輸出。資源的建立時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
updateTime

string (Timestamp format)

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

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
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 或閘道相關聯的路徑必須有不重複的主機名稱。如果嘗試附加多個主機名稱衝突的路徑，系統會拒絕設定。

舉例來說，主機名稱 *.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 欄位所參照後端的請求比例。計算方式為：- weight/Sum(weights in this destination list)。如果值不為零，則可能與這裡定義的確切比例有些許差異，視實作支援的精確度而定。

如果只指定一個 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 錯誤代碼重設串流，路由器會重試。這類重設表示可以安全地重試。
  • 已取消：如果回應標頭中的 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 會編碼特定目的地主機，只要目的地主機保持運作且健康狀態良好，包含該 Cookie 的每個要求都會導向該主機。

gRPC 無代理程式網格程式庫或 Sidecar 代理程式會管理工作階段 Cookie，但用戶端應用程式碼必須負責將工作階段中每個 RPC 的 Cookie 複製到下一個 RPC。

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

string (Duration format)

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

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

方法

create

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

delete

 刪除單一 GrpcRoute。

get

 取得單一 GrpcRoute 的詳細資料。

list

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

patch

 更新單一 GrpcRoute 的參數。

setIamPolicy

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

testIamPermissions

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