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 UTC「Zulu」形式のタイムスタンプ。精度はナノ秒まで、小数点以下は最大 9 桁。例: "2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

出力専用。リソース最終更新時のタイムスタンプ。

RFC3339 UTC「Zulu」形式のタイムスタンプ。精度はナノ秒まで、小数点以下は最大 9 桁。例: "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

省略可。リソースの説明（フリーテキスト）。最大長は 1,024 文字です。
hostnames[]

string

必須。このルートがトラフィックを記述するオプションのポートを持つサービス ホスト名。

形式: [:]

Hostname は、ネットワーク ホストの完全修飾ドメイン名です。これはホスト名の RFC 1123 定義と一致しますが、2 つの注意すべき例外があります。- IP は許可されていません。- ホスト名の先頭にワイルドカード ラベル（*.）を付けることができます。ワイルドカード ラベルは、単独で最初のラベルとして表示されます。

ホスト名には、ネットワーク ホストの末尾にドットを付けないドメイン名（例: foo.example.com）または「ワイルドカード」を使用できます。ワイルドカードは、先頭に単一のワイルドカード ラベル（例: *.example.com）が付いたドメイン名です。

RFC1035 と RFC1123 に従って、ラベルは小文字の英数字または「-」で構成し、英数字で始まり英数字で終わる必要があります。他の句読点は使用できません。

Mesh または Gateway に関連付けられたルートには一意のホスト名が必要です。競合するホスト名を持つ複数のルートを接続しようとすると、構成は拒否されます。

たとえば、ホスト名 *.foo.bar.com と *.bar.com のルートを同じルートに関連付けることは可能ですが、2 つのルートを *.bar.com に、または両方を bar.com に関連付けることはできません。して、ソース別にトラフィック データを分類します。

ポートが指定されている場合、gRPC クライアントはこのルールに一致するポートとチャネル URI を使用する必要があります（「xds:///service:123」など）。それ以外の場合は、ポートを指定せずに URI（「xds:/」など）を指定する必要があります。
meshes[]

string

省略可。メッシュは、この GrpcRoute が接続されているメッシュのリストを、メッシュによって処理されるリクエストをルーティングするルーティング ルールの 1 つとして定義します。

各メッシュ参照は、パターン projects/*/locations/global/meshes/<mesh_name> と一致する必要があります。
gateways[]

string

省略可。ゲートウェイは、この GrpcRoute が接続されているゲートウェイのリストを定義します。これは、ゲートウェイによって処理されるリクエストをルーティングするルーティング ルールの 1 つです。

各ゲートウェイ参照は、パターン projects/*/locations/global/gateways/<gateway_name> と一致している必要があります。
rules[]

object (RouteRule)

必須。トラフィックのルーティング方法を定義する詳細なルールのリスト。

1 つの GrpcRoute 内で、最初に一致する GrpcRoute.RouteRule に関連付けられた GrpcRoute.RouteAction が実行されます。少なくとも 1 つのルールを選択する必要があります

RouteRule

トラフィックのルーティング方法について説明します。

JSON 表現 
{
  "matches": [
    {
      object (RouteMatch)
    }
  ],
  "action": {
    object (RouteAction)
  }
}
フィールド
matches[]

object (RouteMatch)

省略可。matches は、受信 gRPC リクエストとルールを照合するために使用する条件を定義します。それぞれの matches は独立しています。つまり、いずれかの matches を満たすと、このルールが一致します。matches フィールドが指定されていない場合、このルールは無条件にトラフィックと一致します。
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)

省略可。トラフィックの転送先のサービス。複数の宛先が指定されている場合、トラフィックは、これらの宛先の weight フィールドに従ってバックエンド サービス間で分割されます。
faultInjectionPolicy

object (FaultInjectionPolicy)

省略可。宛先サービスの障害に対するクライアントの復元性をテストするために、トラフィックに導入されたフォールト インジェクションの仕様。フォールト インジェクションの一環として、クライアントが宛先にリクエストを送信すると、それらのリクエストを宛先サービスに送信する前に、一定の割合のリクエストに遅延が生じる可能性があります。同様に、クライアントからのリクエストも、リクエストの割合によって中止することができます。

timeout と retryPolicy は、faultInjectionPolicy で構成されているクライアントで無視されます
timeout

string (Duration format)

省略可。選択したルートのタイムアウトを指定します。リクエストが完全に処理されてから（つまりストリームの終了）、レスポンスが完全に処理されるまでのタイムアウトが計算されます。タイムアウトにはすべての再試行が含まれます。

s で終わる小数 9 桁までの秒単位の期間。例: "3.5s"。
retryPolicy

object (RetryPolicy)

省略可。このルートに関連付けられた再試行ポリシーを指定します。
statefulSessionAffinity

object (StatefulSessionAffinityPolicy)

省略可。Cookie ベースのステートフル セッション アフィニティを指定します。
idleTimeout

string (Duration format)

省略可。選択したルートのタイムアウトを指定します。アイドル タイムアウトは、アップストリーム接続またはダウンストリーム接続で送受信されたバイトがない期間として定義されます。設定しない場合、デフォルトのアイドル タイムアウトは 1 時間です。0 秒に設定すると、タイムアウトは無効になります。

s で終わる小数 9 桁までの秒単位の期間。例: "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

必須。トラフィックのルーティング先となる宛先サービスの URL。BackendService または ServiceDirectoryService のいずれかを参照する必要があります。
weight

integer

省略可。serviceName フィールドで参照されるバックエンドに転送されるリクエストの割合を指定します。これは、-weight/Sum（この宛先リストの重み）として計算されます。ゼロ以外の値の場合、実装がサポートする精度に応じて、ここで定義された正確な割合のイプシロンがある場合があります。

serviceName を 1 つだけ指定し、その重みが 0 より大きい場合、トラフィックの 100% がそのバックエンドに転送されます。

1 つのサービス名に重み付けを指定する場合は、すべてのサービス名に重み付けを指定する必要があります。

すべてのサービスに重み付けを指定しない場合は、トラフィックがすべてのサービスに均等に分散されます。

FaultInjectionPolicy

宛先サービスの障害に対するクライアントの復元性をテストするために、トラフィックに導入されたフォールト インジェクションの仕様。フォールト インジェクションの一環として、クライアントが宛先にリクエストを送信すると、それらのリクエストを宛先サービスに送信する前に、一定の割合のリクエストに遅延が生じる可能性があります。同様に、クライアントからのリクエストも、リクエストの割合によって中止することができます。

JSON 表現 
{
  "delay": {
    object (Delay)
  },
  "abort": {
    object (Abort)
  }
}
フィールド
delay

object (Delay)

クライアント リクエストに遅延を挿入するための仕様。
abort

object (Abort)

クライアント リクエストを中止するための仕様。

Delay

宛先に送信される前に、フォールト インジェクションの一部としてクライアント リクエストが遅延する仕組みの指定。

JSON 表現 
{
  "fixedDelay": string,
  "percentage": integer
}
フィールド
fixedDelay

string (Duration format)

リクエストを転送する前に固定の遅延を指定します。

s で終わる小数 9 桁までの秒単位の期間。例: "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 に設定されている場合、ルーターは再試行する
  • 使用不可: レスポンス ヘッダーの gRPC ステータス コードが使用不可に設定されている場合、ルーターは再試行します。
numRetries

integer (uint32 format)

再試行回数の上限を指定します。この数値は 0 より大きい必要があります。指定しない場合は、デフォルトの 1 になります。

StatefulSessionAffinityPolicy

Cookie ベースのステートフル セッション アフィニティの仕様。日付プレーンは「GSSA」という名前の「セッション Cookie」を提供し、特定の宛先ホストをエンコードします。その Cookie を含む各リクエストは、宛先ホストが残っている限り、そのホストに転送されます。

gRPC プロキシレス メッシュ ライブラリまたはサイドカー プロキシがセッション クッキーを管理しますが、クライアント アプリケーション コードは、セッション内の各 RPC から次の RPC に Cookie をコピーする役割を担います。

JSON 表現 
{
  "cookieTtl": string
}
フィールド
cookieTtl

string (Duration format)

必須。データプレーンによって生成された Set-Cookie ヘッダーの Cookie TTL 値。Cookie の有効期間は、1 秒～86,400 秒（24 時間）の範囲で設定できます。

s で終わる小数 9 桁までの秒単位の期間。例: "3.5s"。

メソッド

create

 指定されたプロジェクトとロケーションで新しい GrpcRoutes を作成します。

delete

 1 つの GrpcRoute を削除します。

get

 1 つの GrpcRoute の詳細を取得します。

list

 指定されたプロジェクトとロケーションの GrpcRoutes を一覧で表示します。

patch

 単一の GrpcRoutes のパラメータを更新します。

setIamPolicy

 指定したリソースにアクセス制御ポリシーを設定します。

testIamPermissions

 指定されたリソースに対して呼び出し元が持っている権限を返します。