式を使用してルートを設定する方法

複雑または大規模な構成を扱う際、式を使用してルートを設定すると、柔軟性とパフォーマンスが向上します。このハウツーガイドでは、Expressionsルーターに切り替える方法と、新しい表現力豊かなドメイン固有言語でルートを設定する方法について説明します。このガイドの残りの部分に進む前に式言語リファレンスを理解しておきましょう。

前提条件

kong.confを編集してrouter_flavor = expressions行を追加し、 Kong Gatewayを再起動します。

注: 式を有効にした後も、ルートオブジェクトの従来の照合フィールド（paths や methods など）は引き続き設定できます。新しい expression フィールドで式を指定できます。ただし、これらを従来の一致フィールドと同時に構成することはできません。さらに、expression フィールドと組み合わせて使用する新しい priority フィールドでは、式ルートの評価順序を指定できます。

式を使用したルートの作成

式を使用して新しいルートオブジェクトを作成するには、サービスエンドポイントに POST リクエストを送信してください。

curl --request POST \
  --url http://localhost:8001/services/example-service/routes \
  --form-string expression='http.path == "/mock"'

この例では、既存のサービス example-service にパス /mock で新しいルートオブジェクトを関連付けました。表現式 DSL を使用すると、複雑なルーターの一致条件を作成することもできます。

curl --request POST \
  --url http://localhost:8001/services/example-service/routes \
  --header 'Content-Type: multipart/form-data' \
  --form-string 'expression=(http.path == "/mock" || net.protocol == "https")'

式を使用して複雑なルートを作成

POSTリクエスト内で演算子を使用して複雑なルートオブジェクトを記述できます。

curl --request POST \
  --url http://localhost:8001/services/example-service/routes \
  --header 'Content-Type: multipart/form-data' \
  --form-string name=complex_object \
  --form-string 'expression=(net.protocol == "http" || net.protocol == "https") &&
                (http.method == "GET" || http.method == "POST") &&
                (http.host == "example.com" || http.host == "example.test") &&
                (http.path ^= "/mock" || http.path ^= "/mocking") &&
                http.headers.x_another_header == "example_header" && (http.headers.x_my_header == "example" || http.headers.x_my_header == "example2")'

一般的なユースケースとそれら向けの式ルートの記述方法については、式言語の概要ページを参照してください。

利用可能なすべての言語機能のリストについては、表現言語リファレンスを参照してください。

マッチングフィールド

次の表では、式ベースのルーターを使用する場合に使用可能な照合フィールドと、それに関連するタイプについて説明しています。

フィールド	タイプ	HTTPサブシステムで利用可能	ストリームサブシステムで利用可能	説明
`net.protocol`	`String`	✅	✅	ルートのプロトコル。`Route`エンティティの`protocols`フィールドにほぼ匹敵します。注： `Route`エンティティの構成済み`protocols`は、常に、生成ルートの最上位レベルに追加されますが、`net.prococol`フィールドを使用すると追加の制約を式内に直接入力できます。
`tls.sni`	`String`	✅	✅	TLS経由の接続の場合は、ClientHelloパケットからの`server_name`拡張。
`http.method`	`String`	✅	❌	受信HTTPリクエストのメソッド（たとえば、`"GET"`または`"POST"`）。
`http.host`	`String`	✅	❌	受信HTTPの`Host`ヘッダー。
`http.path`	`String`	✅	❌	RFC 3986の定義ルールに従って正規化されたリクエストパス。このフィールド値には、存在する可能性のあるクエリパラメータは含まれていません。
`http.path.segments.<segment_index id="sl-md0000000">`	`String`	✅	❌	ゼロベースのインデックスを持つ入力（正規化されたもの）`http.path`から抽出されたパスセグメント。たとえば、リクエストパス`"/a/b/c/"`または`"/a/b/c"`の場合、 `http.path.segments.1` `"b"`を返します。
`http.path.segments.<segment_index id="sl-md0000000">_<segment_index id="sl-md0000000">`	`String`	✅	❌	指定された閉区間内の入力（正規化されたもの）`http.path`から抽出されたパスセグメントは、`"/"`によって結合されます。インデックスはゼロベースです。たとえば、リクエストパス`"/a/b/c/"`または`"/a/b/c"`の場合、 `http.path.segments.0_1` `"a/b"`を返します。
`http.path.segments.len`	`Int`	✅	❌	入力（正規化されたもの）からのセグメント数 `http.path`。たとえば、リクエストパス`"/a/b/c/"`または`"/a/b/c"`の場合、 `http.path.segments.len` `3`を返します。
`http.headers.<header_name id="sl-md0000000">`	`String[]`	✅	❌	リクエストヘッダー`<header_name id="sl-md0000000">`の値。注：ヘッダー名は常に、アンダースコアと小文字の形式で正規化されるため、`Foo-Bar`、`Foo_Bar`、`fOo-BAr` はすべて `http.headers.foo_bar` フィールドの値になります。
`http.queries.<query_parameter_name id="sl-md0000000">`	`String[]`	✅	❌	クエリパラメータ`<query_parameter_name id="sl-md0000000">`の値。
`net.src.ip`	`IpAddr`	✅	✅	クライアントの IP アドレス。
`net.src.port`	`Int`	✅	✅	クライアントが接続に使用するポート番号。
`net.dst.ip`	`IpAddr`	✅	✅	Kong Gatewayが着信接続を受け入れるリッスン IP アドレス。
`net.dst.port`	`Int`	✅	✅	Kong Gatewayが着信接続を受け入れるリスニングポート番号。

式を使用してルートを設定する方法

前提条件

式を使用したルートの作成

式を使用して複雑なルートを作成

マッチングフィールド

その他の情報