コンテンツにスキップ
|
Kong Gateway
3.4.x LTS
report-issue問題を報告する
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。

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

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

前提条件

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

注: 式を有効にすると、ルートオブジェクトに従来存在する一致フィールド ( pathsやmethodsなど) は構成できなくなり、 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が着信接続を受け入れるリスニングポート番号。
フィールド タイプ 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.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が受信接続を受け入れるリスニングポート番号。

その他の情報