ゲートウェイリクエスト述語

Spring Cloud Gateway MVC は、Spring WebMvc.fn HandlerMapping インフラストラクチャの一部としてルートを照合します。Spring Cloud Gateway は、WebMvc.fn の多くの RequestPredicate 実装を再利用し、他のカスタム RequestPredicate 実装を含みます。これらの述語はすべて、HTTP リクエストのさまざまな属性に一致します。RequestPredicate.and() および RequestPredicate.or() メソッドを使用して、複数のルート述語ファクトリを組み合わせることができます。

After Request 述語

After ルート述語ファクトリは、datetime （java ZonedDateTime）というパラメーターを 1 つ受け取ります。この述語は、指定された日時以降に発生したリクエストに一致します。日時は、ZonedDateTime 文字列またはエポックミリ秒で指定できます。次の例では、after ルート述語を設定しています。

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: after_route
              uri: https://example.org
              predicates:
              - After=2017-01-20T17:42:47.789-07:00[America/Denver]

日時をエポックミリ秒として指定することもできます。

application.yml
spring:
  cloud:
    gateway:
      mvc:
        routes:
        - id: after_route
          uri: https://example.org
          predicates:
          - After=1484968967789
GatewaySampleApplication.java
import java.time.ZonedDateTime;
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.after;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsAfter() {
        return route("after_route")
            .route(after(ZonedDateTime.parse("2017-01-20T17:42:47.789-07:00[America/Denver]")), http())
            .before(uri("https://example.org"))
            .build();
    }
}

このルートは、2017 年 1 月 20 日 17:42 山岳部標準時（デンバー）以降に行われたすべてのリクエストに一致します。

Before Request 述語

Before ルート述語ファクトリは、datetime （java ZonedDateTime）という 1 つのパラメーターを取ります。この述語は、指定された datetime より前に発生したリクエストに一致します。日時は、ZonedDateTime 文字列またはエポックミリ秒で指定できます。次の例では、before ルート述語を設定しています。

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: before_route
              uri: https://example.org
              predicates:
              - Before=2017-01-20T17:42:47.789-07:00[America/Denver]

日時をエポックミリ秒として指定することもできます。

application.yml
spring:
  cloud:
    gateway:
      mvc:
        routes:
        - id: before_route
          uri: https://example.org
          predicates:
          - Before=1484968967789
GatewaySampleApplication.java
import java.time.ZonedDateTime;
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.before;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsBefore() {
        return route("before_route")
            .route(before(ZonedDateTime.parse("2017-01-20T17:42:47.789-07:00[America/Denver]")), http()
            .before(uri("https://example.org"))
            .build();
    }
}

このルートは、2017 年 1 月 20 日 17:42 山岳部標準時（デンバー）より前に行われたすべてのリクエストに一致します。

Between リクエスト述語

The Between route predicate factory takes two parameters, datetime1 and datetime2 which are java ZonedDateTime objects. This predicate matches requests that happen after datetime1 and before datetime2. The datetime2 parameter must be after datetime1. The datetimes can be specified as ZonedDateTime strings or as epoch milliseconds. The following example configures a between route predicate:

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: between_route
              uri: https://example.org
              predicates:
              - Between=2017-01-20T17:42:47.789-07:00[America/Denver], 2017-01-21T17:42:47.789-07:00[America/Denver]

The datetimes can also be specified as epoch milliseconds:

application.yml
spring:
  cloud:
    gateway:
      mvc:
        routes:
        - id: between_route
          uri: https://example.org
          predicates:
          - Between=1484968967789, 1485055367789
GatewaySampleApplication.java
import java.time.ZonedDateTime;
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.between;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsBetween() {
        return route("between_route")
            .route(between(ZonedDateTime.parse("2017-01-20T17:42:47.789-07:00[America/Denver]"),
                ZonedDateTime.parse("2017-01-21T17:42:47.789-07:00[America/Denver]")), http())
            .before(uri("https://example.org"))
            .build();
    }
}

このルートは、2017 年 1 月 20 日 17:42 山岳部標準時（デンバー）以降および 2017 年 1 月 21 日 17:42 山岳部標準時（デンバー）より前に行われたすべてのリクエストに一致します。これは、メンテナンスウィンドウに役立つ可能性があります。

Cookie ルート述語ファクトリは、Cookie name と regexp （Java 正規表現）の 2 つのパラメーターを取ります。この述語は、指定された名前を持ち、値が正規表現と一致する Cookie と一致します。次の例では、Cookie ルート述語ファクトリを設定します。

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: cookie_route
              uri: https://example.org
              predicates:
              - Cookie=chocolate, ch.p
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.cookie;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsCookie() {
        return route("cookie_route")
            .route(cookie("chocolate", "ch.p"), http())
            .before(uri("https://example.org"))
            .build();
    }
}

このルートは、値が ch.p 正規表現と一致する chocolate という名前の Cookie を持つリクエストに一致します。

ヘッダーリクエスト述語

Header ルート述語ファクトリは、header と regexp （Java 正規表現）の 2 つのパラメーターを取ります。この述語は、値が正規表現と一致する名前を持つヘッダーと一致します。次の例では、ヘッダールート述語を構成します。

application.yml
spring:
  cloud:
    server:
      webmvc:
        routes:
            - id: header_route
              uri: https://example.org
              predicates:
              - Header=X-Request-Id, \d+
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.header;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsHeader() {
        return route("header_route")
            .route(header("X-Request-Id", "\\d+"), http())
            .before(uri("https://example.org"))
            .build();
    }
}

このルートは、リクエストに X-Request-Id という名前のヘッダーがあり、その値が \d+ 正規表現と一致する場合（つまり、1 桁以上の値を持つ場合）に一致します。

ホストリクエスト述語

Host ルート述語ファクトリは 1 つのパラメーターを取ります: ホスト名 patterns のリスト。パターンは、. をセパレーターとする Ant スタイルのパターンです。この述語は、パターンに一致する Host ヘッダーに一致します。次の例では、ホストルート述語を設定します。

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: host_route
              uri: https://example.org
              predicates:
              - Host=**.somehost.org,**.anotherhost.org
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.host;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsHost() {
        return route("host_route")
            .route(host("**.somehost.org", "**.anotherhost.org"), http())
            .before(uri("https://example.org"))
            .build();
    }
}

URI テンプレート変数（{sub}.myhost.org など）もサポートされています。

このルートは、リクエストに www.somehost.org、beta.somehost.org、www.anotherhost.org の値を持つ Host ヘッダーがある場合に一致します。

この述語は、URI テンプレート変数 (前の例で定義した sub など) を名前と値のマップとして抽出し、MvcUtils.URI_TEMPLATE_VARIABLES_ATTRIBUTE で定義されたキーを使用して ServerRequest.attributes() に配置します。これらの値は、ゲートウェイハンドラーフィルター関数で使用できるようになります。

メソッドリクエスト述語

Method リクエスト述語は、1 つ以上のパラメーターである methods 引数、つまり照合する HTTP メソッドを受け取ります。次の例では、メソッドルート述語を構成します。

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: method_route
              uri: https://example.org
              predicates:
              - Method=GET,POST
GatewaySampleApplication.java
import org.springframework.http.HttpMethod;
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.method;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsMethod() {
        return route("method_route")
            .route(method(HttpMethod.GET, HttpMethod.POST), http())
            .before(uri("https://example.org"))
            .build();
    }
}

このルートは、リクエストメソッドが GET または POST の場合に一致します。

GatewayRequestPredicates.method は RequestPredicates.methods (Javadoc) の単純な別名です。また、RouterFunctions.Builder API には、method と path RequestPredicates を組み合わせた便利なメソッドが含まれています。

GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsMethodAndPath() {
        return route("method_and_path_route")
            .GET("/mypath", http())
            .before(uri("https://example.org"))
            .build();
    }
}

このルートは、リクエストメソッドが GET でパスが /mypath の場合に一致します。

パスリクエスト述語

Path リクエスト述語は、Spring PathPattern patterns のリストという 2 つのパラメーターを取ります。このリクエスト述語は、基盤となる実装として RequestPredicates.path() (Javadoc) を使用します。次の例では、パスルート述語を構成します。

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: path_route
              uri: https://example.org
              predicates:
              - Path=/red/{segment},/blue/{segment}
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.path;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsPath() {
        return route("path_route")
            .route(path("/red/{segment}", "/blue/{segment}"), http())
            .before(uri("https://example.org"))
            .build();
    }
}

このルートは、リクエストパスが /red/1 または /red/1/ または /red/blue または /blue/green の場合に一致します。

この述語は、URI テンプレート変数 (前の例で定義した segment など) を名前と値のマップとして抽出し、RouterFunctions.URI_TEMPLATE_VARIABLES_ATTRIBUTE で定義されたキーを使用して ServerRequest.attributes() に配置します。これらの値は、ゲートウェイハンドラーフィルター関数で使用できるようになります。

これらの変数へのアクセスを容易にするために、ユーティリティメソッド（get と呼ばれる）を使用できます。次の例は、get メソッドの使用方法を示しています。

Map<String, Object> uriVariables = MvcUtils.getUriTemplateVariables(request);

String segment = uriVariables.get("segment");

クエリリクエスト述語

Query ルート述語ファクトリは、必須の param とオプションの regexp （Java 正規表現）の 2 つのパラメーターを取ります。次の例では、クエリルート述語を設定します。

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: query_route
              uri: https://example.org
              predicates:
              - Query=green
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.query;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsQuery() {
        return route("query_route")
            .route(query("green"), http())
            .before(uri("https://example.org"))
            .build();
    }
}

リクエストに green クエリパラメーターが含まれている場合、上記のルートは一致します。

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: query_route
              uri: https://example.org
              predicates:
              - Query=red, gree.
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.query;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsQuery() {
        return route("query_route")
            .route(query("red", "gree."), http())
            .before(uri("https://example.org"))
            .build();
    }
}

上記のルートは、リクエストに gree. 正規表現と値が一致する red クエリパラメーターが含まれている場合に一致するため、green と greet が一致します。

重み付けリクエストの述語

Weight ルート述語ファクトリは、group と weight ( int) の 2 つの引数を取ります。重みはグループごとに計算されます。次の例では、重みルート述語を設定します。

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: weight_high
              uri: https://weighthigh.org
              predicates:
              - Weight=group1, 8
            - id: weight_low
              uri: https://weightlow.org
              predicates:
              - Weight=group1, 2
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.path;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.weight;

@Configuration
class RouteConfiguration {

	@Bean
	public RouterFunction<ServerResponse> gatewayRouterFunctionsWeights() {
        return route("weight_high")
                .route(weight("group1", 8).and(path("/**")), http())
                .before(uri("https://weighthigh.org"))
                .build().and(
            route("weight_low")
                .route(weight("group1", 2).and(path("/**")), http())
                .before(uri("https://weightlow.org"))
                .build());
	}
}

このルートは、トラフィックの最大 80% を weighthigh.org (英語) に転送し、トラフィックの最大 20% を weightlow.org (英語) に転送します。