Azure Spring Apps Enterprise プランで VMware Spring Cloud Gateway ルートフィルターを使用する方法

[アーティクル]
02/02/2024

Note

Azure Spring Apps は、Azure Spring Cloud サービスの新しい名前です。サービスの名前は新しくなりましたが、スクリーンショット、ビデオ、図などの資産の更新に取り組んでいる間、場所によってはしばらく古い名前が表示されます。

この記事の適用対象:❌ Basic または Standard ✔️ Enterprise

この記事では、Azure Spring Apps Enterprise プランで VMware Spring Cloud Gateway ルートフィルターを使用して、アプリケーションに要求をルーティングする方法について説明します。

VMware Spring Cloud Gateway は、オープンソースの Spring Cloud Gateway プロジェクトに基づく商用 VMware Tanzu コンポーネントです。 Spring Cloud Gateway は、シングルサインオン (SSO)、アクセス制御、レート制限、回復性、セキュリティなど、API 開発チームにとっての分野横断的な懸念に対処しています。最新のクラウドネイティブパターンと、API 開発用の任意のプログラミング言語を使用して、API のデリバリーを迅速化できます。

VMware Spring Cloud Gateway には、次のような機能があります。

動的ルーティング構成、再コンパイルなしで適用および変更できる個々のアプリケーションに依存しません。
承認された JSON Web トークン (JWT) 要求をアプリケーションサービスに転送する商用 API ルートフィルター。
クライアント証明書の承認。
レート制限のアプローチ。
サーキットブレーカーの構成。
HTTP 基本認証の資格情報を使用したアプリケーションサービスへのアクセスのサポート。

API Portal for VMware Tanzu と統合するため、VMware Spring Cloud Gateway は、任意のルート構成が追加または変更された後に OpenAPI バージョン 3 のドキュメントを自動的に生成します。詳細については、「API Portal for VMware Tanzu を使用する」を参照してください。

前提条件

Spring Cloud Gateway が有効になっている、既にプロビジョニングされた Azure Spring Apps Enterprise プランのサービスインスタンス。詳細については、「クイックスタート: Enterprise プランを使用してアプリをビルドし Azure Spring Apps にデプロイする」をご覧ください。
Azure CLI バージョン 2.0.67 以降。コマンド az extension add --name spring を使用して、Azure Spring Apps 拡張機能をインストールします。

フィルターの使用

Spring Cloud Gateway 構成でフィルターを使用して、ルート構成に対する受信要求または送信応答に対応します。

たとえば、フィルターを使用して HTTP ヘッダーを追加したり、認可トークンに基づいてアクセスを拒否したりすることができます。

オープンソースフィルターを使用する

Spring Cloud Gateway OSS には、ルートのフィルターを作成するために使用されるいくつかの GatewayFilter ファクトリが含まれています。以下のセクションで、これらのファクトリについて説明します。

AddRequestHeader

AddRequestHeader ファクトリは、一致するすべての要求に対するダウンストリーム要求のヘッダーにヘッダーを追加します。

このファクトリでは、次の構成パラメータを指定できます。

name
value

次の例では、一致するすべての要求に対するダウンストリーム要求のヘッダーにヘッダー X-Request-red:blue を追加する AddRequestHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AddRequestHeader=X-Request-red, blue"
        ]
    }
]

AddRequestHeader ファクトリは、パスまたはホストとの照合に使用される URI 変数にアクセスできます。値には URI 変数を使用でき、変数は実行時に展開されます。

次の例では、変数を使用する AddRequestHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "AddRequestHeader=X-Request-red, blue-{segment}"
        ]
    }
]

AddRequestHeadersIfNotPresent

AddRequestHeadersIfNotPresent ファクトリは、元の要求にヘッダーが存在しない場合にヘッダーを追加します。

このファクトリでは、次の構成パラメータを指定できます。

headers: キーと値のペア (ヘッダー名、ヘッダー値) のコンマ区切りのリスト。

次の例では、AddRequestHeadersIfNotPresent ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AddRequestHeadersIfNotPresent=Content-Type:application/json,Connection:keep-alive"
        ]
    }
]

AddRequestParameter

AddRequestParameter ファクトリは、一致するすべての要求に対するダウンストリーム要求のクエリ文字列にパラメータを追加します。

このファクトリでは、次の構成パラメータを指定できます。

name
value

次の例では、一致するすべての要求に対するダウンストリーム要求のクエリ文字列に red=blue パラメータを追加する AddRequestParameter ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AddRequestParameter=red, blue"
        ]
    }
]

AddRequestParameter ファクトリは、パスまたはホストとの照合に使用される URI 変数にアクセスできます。値には URI 変数を使用でき、変数は実行時に展開されます。

次の例では、変数を使用する AddRequestParameter ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "AddRequestParameter=foo, bar-{segment}"
        ]
    }
]

AddResponseHeader

AddResponseHeader ファクトリは、一致するすべての要求に対するダウンストリーム応答のヘッダーにヘッダーを追加します。

このファクトリでは、次の構成パラメータを指定できます。

name
value

次の例では、一致するすべての要求に対するダウンストリーム応答のヘッダーに X-Response-Red:Blue ヘッダーを追加する AddResponseHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AddResponseHeader=X-Response-Red, Blue"
        ]
    }
]

AddResponseHeader ファクトリは、パスまたはホストとの照合に使用される URI 変数にアクセスできます。値には URI 変数を使用でき、変数は実行時に展開されます。

次の例では、変数を使用する AddResponseHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "AddResponseHeader=foo, bar-{segment}"
        ]
    }
]

CircuitBreaker

CircuitBreaker ファクトリは、サーキットブレーカーでルートをラップします。

このファクトリでは、次の構成パラメータを指定できます。

name: サーキットブレーカー名。
fallbackUri: 経路変更 URI。ローカルルートまたは外部ハンドラーを指定できます。
status codes (省略可能): 一致する状態コードのコロン区切りのリスト (数値またはテキスト形式)。
failure rate (省略可能): サーキットブレーカーが開くしきい値。既定値は 50% です。
duration (省略可能): 再度閉じる前に待機する時間。既定値は 60 秒です。

次の例では、CircuitBreaker ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "CircuitBreaker=myCircuitBreaker,forward:/inCaseOfFailureUseThis,401:NOT_FOUND:500,10,30s"
        ]
    }
]

DeDupeResponseHeader

DeDupeResponseHeader ファクトリは、応答ヘッダーの重複する値を削除します。

このファクトリでは、次の構成パラメータを指定できます。

name: ヘッダー名のスペース区切りのリスト。
指定できる値は、strategy、RETAIN_FIRST､RETAIN_LAST、RETAIN_UNIQUE です。既定値は RETAIN_FIRST です。

次の例では、Access-Control-Allow-Credentials および Access-Control-Allow-Origin 応答ヘッダーの両方の値がゲートウェイ CORS ロジックとダウンストリームロジックによって追加された場合に、重複する値を削除する DeDupeResponseHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "DeDupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin"
        ]
    }
]

FallbackHeaders

FallbackHeaders ファクトリは、サーキットブレーカー例外をヘッダーに追加します。このフィルターでは、別のルートで CircuitBreaker フィルターを使用する必要があります。

このファクトリには、パラメータはありません

次の例では、例外の種類、メッセージ、および (使用可能な場合) 根本原因の例外の種類と、 FallbackHeaders フィルターが要求に追加するメッセージを使用して、 FallbackHeaders ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "CircuitBreaker=myCircuitBreaker,forward:/inCaseOfFailureUseThis,401:NOT_FOUND:500,10,30s"
        ]
    },
    {
        "predicates": [
            "Path=/inCaseOfFailureUseThis"
        ],
        "filters": [
            "FallbackHeaders"
        ]
    }
]

次のパラメータの値 (既定値で説明) を設定することで、構成内のヘッダーの名前を上書きできます。

executionExceptionTypeHeaderName ("Execution-Exception-Type")
executionExceptionMessageHeaderName ("Execution-Exception-Message")
rootCauseExceptionTypeHeaderName ("Root-Cause-Exception-Type")
rootCauseExceptionMessageHeaderName ("Root-Cause-Exception-Message")

JSONToGRPC

JSONToGRPCFilter ファクトリは、JSON ペイロードを gRPC 要求に変換します。

このファクトリでは、次の構成パラメータを指定できます。

protoDescriptor: proto 記述子ファイル。

このファイルは、次の例に示すように、protoc を使用し、--descriptor_set_out フラグを指定することで生成できます。

protoc --proto_path=src/main/resources/proto/ \
    --descriptor_set_out=src/main/resources/proto/hello.pb \
    src/main/resources/proto/hello.proto

Note

streaming パラメータはサポートされていません。

次の例では、protoc からの出力を使用して、JSONToGRPCFilter ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/json/**"
        ],
        "filters": [
            "JsonToGrpc=file:proto/hello.pb,file:proto/hello.proto,HelloService,hello"
        ]
    }
]

LocalResponseCache

LocalResponseCache ファクトリは、グローバルキャッシュがアクティブ化されるときに、特定のルートに対するローカル応答キャッシュ構成をオーバーライドします。

このファクトリでは、次の構成パラメータを指定できます。

size: キャッシュの削除が開始されるまでの、このルートのキャッシュエントリの最大許容サイズ (KB、MB、GB)。
timeToLive: 有効期限が切れるまでのキャッシュエントリの許容有効期間。期間サフィックス s (秒)、m (分)、または h (時間) を使用します。

次の例では、LocalResponseCache ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "LocalResponseCache=3m,1MB"
        ]
    }
]

MapRequestHeader

MapRequestHeader ファクトリは、受信 HTTP 要求のヘッダーの更新された値を使用して、ダウンストリーム要求にヘッダーを追加します。

このファクトリでは、次の構成パラメータを指定できます。

fromHeader
toHeader

このファクトリは、新しい名前付きヘッダー (toHeader) を作成し、受信 HTTP 要求の既存の名前付きヘッダー (fromHeader) から値を抽出します。入力ヘッダーが存在しない場合、フィルターは機能しません。新しい名前付きヘッダーが既に存在する場合、その値は新しい値で拡張されます。

次の例では、受信 HTTP 要求の Blue ヘッダーの更新された値を使用して、ダウンストリーム要求に X-Request-Red:<values> ヘッダーを追加する MapRequestHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "MapRequestHeader=Blue, X-Request-Red"
        ]
    }
]

PrefixPath

PrefixPath ファクトリは、すべての要求のパスにプレフィックスを追加します。

このファクトリでは、次の構成パラメータを指定できます。

prefix

次の例では、プレフィックス /api をすべての要求のパスに追加する PrefixPath ファクトリを構成し、/catalog への要求が /api/catalog に送信されるようにします。

[
    {
        "predicates": [
            "Path=/catalog/**"
        ],
        "filters": [
            "PrefixPath=/api"
        ]
    }
]

PreserveHostHeader

PreserveHostHeader ファクトリは、ルーティングフィルターが検査する要求属性を設定して、元のホストヘッダーを送信するか、HTTP クライアントによって決定されたホストヘッダーを送信するかを決定します。

このファクトリには、パラメータはありません

次の例では、PreserveHostHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "PreserveHostHeader"
        ]
    }
]

RedirectTo

RedirectTo ファクトリは、元の URL にリダイレクトを追加します。

このファクトリでは、次の構成パラメータを指定できます。

status: 300 系列は HTTP コードをリダイレクトします (301 など)。
url: Location ヘッダーの値。有効な URI である必要があります。相対リダイレクトの場合は、ルート定義の URI として uri: no://op を使用する必要があります。

次の例では、リダイレクトを実行するために、Location:https://acme.org ヘッダーを含む状態 302 を送信する RedirectTo ファクトリを構成します。

[
    {
        "uri": "https://example.org",
        "filters": [
            "RedirectTo=302, https://acme.org"
        ]
    }
]

RemoveJsonAttributesResponseBody

RemoveJsonAttributesResponseBody ファクトリは、JSON 属性とその値を JSON 応答本文から削除します。

このファクトリでは、次の構成パラメータを指定できます。

attribute names: JSON 応答から削除する属性の名前のコンマ区切りのリスト。
delete recursively (省略可能、ブール値): ルートレベルでのみ (false)、または再帰的に (true) 属性を削除する構成。既定値は false です。

次の例では、RemoveJsonAttributesResponseBody ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RemoveJsonAttributesResponseBody=origin,foo,true"
        ]
    }
]

RemoveRequestHeader

RemoveRequestHeader ファクトリは、ダウンストリーム要求からヘッダーを削除します。

このファクトリでは、次の構成パラメータを指定できます。

name: 削除するヘッダーの名前。

次のリストでは、ダウンストリームに送信される前に X-Request-Foo ヘッダーを削除する RemoveRequestHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RemoveRequestHeader=X-Request-Foo"
        ]
    }
]

RemoveRequestParameter

RemoveRequestParameter ファクトリは、ダウンストリームに送信される前にパラメータを削除します。

このファクトリでは、次の構成パラメータを指定できます。

name: 削除するクエリパラメータの名前。

次の例では、ダウンストリームに送信される前に red パラメータを削除する RemoveRequestParameter ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RemoveRequestParameter=red"
        ]
    }
]

RemoveResponseHeader

RemoveResponseHeader ファクトリは、ゲートウェイクライアントに返される前に、応答からヘッダーを削除します。

このファクトリでは、次の構成パラメータを指定できます。

name: 削除するヘッダーの名前。

次のリストでは、ゲートウェイクライアントに返される前に、応答から X-Response-Foo ヘッダーを削除する RemoveResponseHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RemoveResponseHeader=X-Response-Foo"
        ]
    }
]

RequestHeaderSize

RequestHeaderSize ファクトリは、要求ヘッダーのサイズを決定します。

このファクトリでは、次の構成パラメータを指定できます。

maxSize: キーと値を含む、要求ヘッダーで許可される最大データサイズ。
errorHeaderName: エラーメッセージが含まれる応答ヘッダーの名前。既定では、応答ヘッダーの名前は errorMessage です。

次のリストでは、要求ヘッダーのサイズが 1000 バイトを超える場合に状態 431 を送信する RequestHeaderSize ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RequestHeaderSize=1000B"
        ]
    }
]

RewriteLocationResponseHeader

RewriteLocationResponseHeader ファクトリは、通常、バックエンド固有の詳細を削除するために、Location 応答ヘッダーの値を変更します。

このファクトリでは、次の構成パラメータを指定できます。

このパラメータには次の値を指定できます: stripVersionMode、NEVER_STRIP、AS_IN_REQUEST、ALWAYS_STRIP。既定値は AS_IN_REQUEST です。
- NEVER_STRIP: 元の要求パスにバージョンが含まれていない場合でも、バージョンは削除されません。
- AS_IN_REQUEST: 元の要求パスにバージョンが含まれていない場合にのみ、バージョンが削除されます。
- ALWAYS_STRIP: 元の要求パスにバージョンが含まれている場合でも、バージョンは常に削除されます。
hostValue: このパラメータは、指定された場合に応答 Location ヘッダーの host:port 部分を置き換えるために使用されます。指定されていない場合は、Host 要求ヘッダーの値が使用されます。
protocolsRegex: プロトコル名と一致する有効な正規表現 String。一致しない場合、フィルターは機能しません。既定値は http|https|ftp|ftps です。
locationHeaderName

次のリストでは、RewriteLocationResponseHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RewriteLocationResponseHeader=AS_IN_REQUEST, Location, ,"
        ]
    }
]

この例では、POSTapi.example.com/some/object/name の要求値に対して、object-service.prod.example.net/v2/some/object/id の Location 応答ヘッダー値が api.example.com/some/object/id に書き換えられます。

RewritePath

RewritePath ファクトリは、要求パスを柔軟に書き換えるために Java 正規表現を使用します。

このファクトリでは、次の構成パラメータを指定できます。

regexp
replacement

次のリストでは、RewritePath ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/red/**"
        ],
        "filters": [
            "RewritePath=/red/?(?<segment>.*), /$\\{segment}"
        ]
    }
]

この例では、要求パスが /red/blue の場合、この構成はダウンストリーム要求を行う前にパスを /blue に設定します。

RewriteResponseHeader

RewriteResponseHeader ファクトリは、応答ヘッダー値を柔軟に書き換えるために Java 正規表現を使用します。

このファクトリでは、次の構成パラメータを指定できます。

name
regexp
replacement

次の例では、RewriteResponseHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/red/**"
        ],
        "filters": [
            "RewriteResponseHeader=X-Response-Red, , password=[^&]+, password=***"
        ]
    }
]

この例では、ヘッダー値が /42?user=ford&password=omg!what&flag=true の場合、ダウンストリーム要求を行った後、構成は /42?user=ford&password=***&flag=true に設定されます。

SetPath

SetPath ファクトリは、パスのテンプレートセグメントを許可することにより、要求パスを簡単に操作する方法を提供します。このフィルターでは、Spring Framework の URI テンプレートを使用して、一致する複数のセグメントを許可します。

このファクトリでは、次の構成パラメータを指定できます。

template

次の例では、SetPath ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/red/{segment}"
        ],
        "filters": [
            "SetPath=/{segment}"
        ]
    }
]

この例では、要求パスが /red/blue の場合、この構成はダウンストリーム要求を行う前にパスを /blue に設定します。

SetRequestHeader

SetRequestHeader ファクトリは、すべてのヘッダーを指定された名前に (追加ではなく) 置き換えます。

このファクトリでは、次の構成パラメータを指定できます。

name
value

次のリストでは、SetRequestHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "SetRequestHeader=X-Request-Red, Blue"
        ]
    }
]

この例では、ダウンストリームサーバーが X-Request-Red:1234 で応答し、それが X-Request-Red:Blue に置き換えられます。

SetRequestHeader ファクトリは、パスまたはホストとの照合に使用される URI 変数にアクセスできます。値には URI 変数を使用でき、変数は実行時に展開されます。

次の例では、変数を使用する SetRequestHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "SetRequestHeader=foo, bar-{segment}"
        ]
    }
]

SetResponseHeader

SetResponseHeader ファクトリは、すべてのヘッダーを指定された名前に (追加ではなく) 置き換えます。

このファクトリでは、次の構成パラメータを指定できます。

name
value

次のリストでは、SetResponseHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "SetResponseHeader=X-Response-Red, Blue"
        ]
    }
]

この例では、ダウンストリームサーバーが X-Response-Red:1234 で応答し、それが X-Response-Red:Blue に置き換えられます。

SetResponseHeader ファクトリは、パスまたはホストとの照合に使用される URI 変数にアクセスできます。値には URI 変数を使用でき、変数は実行時に展開されます。

次の例では、変数を使用する SetResponseHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/{segment}"
        ],
        "filters": [
            "SetResponseHeader=foo, bar-{segment}"
        ]
    }
]

SetStatus

SetStatus ファクトリは、サーバー要求の応答状態を構成します。

このファクトリでは、次の構成パラメータを指定できます。

status: 有効な Spring HttpStatus 値。404 などの整数値、または NOT_FOUND などの列挙型の文字列表現を指定できます。

次のリストでは、SetStatus ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/experimental/**"
        ],
        "filters": [
            "SetStatus=UNAUTHORIZED"
        ]
    },
    {
        "predicates": [
            "Path=/unknown/**"
        ],
        "filters": [
            "SetStatus=401"
        ]
    }
]

StripPrefix

StripPrefix ファクトリは、ダウンストリームに送信する前に、要求からプレフィックスを削除します。

このファクトリでは、次の構成パラメータを指定できます。

parts: 要求をダウンストリームに送信する前に、要求から削除するパス内のパーツ数。既定値は 1 です。

次の例では、StripPrefix ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/name/**"
        ],
        "filters": [
            "StripPrefix=2"
        ]
    }
]

この例では、ゲートウェイを介して /name/blue/red 要求が行われます。 nameservice に対して行われた要求は、nameservice/red として表示されます。

再試行

Retry ファクトリは、試行する再試行回数を決定します。

このファクトリでは、次の構成パラメータを指定できます。

retries: 試行する必要がある再試行回数。
statuses: org.springframework.http.HttpStatus を使用して表される、再試行が必要な HTTP 状態コード。
methods: org.springframework.http.HttpMethod を使用して表される、再試行が必要な HTTP メソッド。
series: org.springframework.http.HttpStatus.Series を使用して表される、再試行する状態コードの系列。
exceptions: 再試行が必要なスローされた例外のリスト。
backoff: 再試行用に構成されたエクスポネンシャルバックオフ。再試行は、firstBackoff * (factor ^ n) のバックオフ間隔の後に実行されます。n はイテレーションです。 maxBackoff が構成されている場合、適用される最大バックオフは maxBackoff に制限されます。 basedOnPreviousValue が true の場合、backoff は prevBackoff * factor を使用して計算されます。

Retry フィルターには、次の既定値が構成されます (有効になっている場合)。

retries: 3 回。
series: 5XX 系列。
methods: GET メソッド
exceptions: IOException および TimeoutException。
backoff: 無効。

次の例では、Retry ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "Retry=3,INTERNAL_SERVER_ERROR,GET,10ms,50ms,2,false"
        ]
    }
]

RequestSize

RequestSize ファクトリは、要求サイズが許容される制限を超える場合に、要求がダウンストリームサービスに到達できないように制限できます。

このファクトリでは、次の構成パラメータを指定できます。

maxSize: DataSize タイプ。値は、数値の後に省略可能な DataUnit サフィックス (KB や MB など) が続く形式で定義されます。既定のサフィックス値は B (バイト) です。これは、バイト単位で定義された要求の許容サイズ制限です。

次の例では、RequestSize ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/upload"
        ],
        "filters": [
            "RequestSize=5000000"
        ]
    }
]

この例では、サイズが原因で要求が拒否された場合、RequestSize ファクトリは、別のヘッダー errorMessage を追加して、応答ステータスを 413 Payload Too Large に設定します。

次の例では、errorMessage を示しています。

errorMessage : Request size is larger than permissible limit. Request size is 6.0 MB where permissible limit is 5.0 MB

TokenRelay

TokenRelay ファクトリは、OAuth2 アクセストークンをダウンストリームリソースに転送します。このフィルターは、明示的なフィルターではなく、ルート定義の boolean 値として構成されます。

次の例では、TokenRelay ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "tokenRelay": true
    }
]

商用フィルターを使用する

Spring Cloud Gateway for Kubernetes には、多くのカスタム GatewayFilter ファクトリも用意されています。以下のセクションで、これらのファクトリについて説明します。

AllowedRequestCookieCount

AllowedRequestCookieCount ファクトリは、Cookie の数に基づいて、一致する要求の続行を許可するかどうかを決定します。

このファクトリでは、次の構成パラメータを指定できます。

amount: 許可する Cookie の数。

次の例では、AllowedRequestCookieCount ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AllowedRequestCookieCount=2"
        ]
    }
]

AllowedRequestHeadersCount

AllowedRequestHeadersCount ファクトリは、ヘッダーの数に基づいて、一致する要求の続行を許可するかどうかを決定します。

このファクトリでは、次の構成パラメータを指定できます。

amount: 許可するヘッダーの数。

次の例では、AllowedRequestHeadersCount ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AllowedRequestHeadersCount=4"
        ]
    }
]

AllowedRequestQueryParamsCount

AllowedRequestQueryParamsCount ファクトリは、クエリパラメータの数に基づいて、一致する要求の続行を許可するかどうかを決定します。

このファクトリでは、次の構成パラメータを指定できます。

amount: 許可するパラメータの数。

次の例では、AllowedRequestQueryParamsCount ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "AllowedRequestQueryParamsCount=3"
        ]
    }
]

BasicAuth

BasicAuth ファクトリは、要求に BasicAuthAuthorization ヘッダーを追加します。

このファクトリには、パラメータはありません

次の例では、BasicAuth ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "BasicAuth"
        ]
    }
]

ClaimHeader

ClaimHeader ファクトリは、JWT 要求のデータを HTTP ヘッダーにコピーします。

このファクトリでは、次の構成パラメータを指定できます。

Claim name: 渡す要求の名前 (大文字と小文字が区別されます)。
Header name: HTTP ヘッダーの名前。

次の例では、ClaimHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "ClaimHeader=sub,X-Claim-Sub"
        ]
    }
]

ClientCertificateHeader

ClientCertificateHeader ファクトリは、X-Forwarded-Client-Cert ヘッダー証明書を検証します。

このファクトリでは、次の構成パラメータを指定できます。

domain pattern: クライアント証明書の CA を認識する Kubernetes の機能に応じた X-Forwarded-Client-Cert 値。
certificate fingerprint (省略可能): TLS/SSL 証明書フィンガープリント。

次の例では、ClientCertificateHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "ClientCertificateHeader=*.example.com,sha-1:aa:bb:00:99"
        ]
    }
]

CORS

Cors ファクトリは、ルートの CORS 検証をアクティブにします。

このファクトリでは、CORS オプションのキーと値のペアとして編成された次の構成パラメータを指定できます。

allowedOrigins
allowedMethods
allowedHeaders
maxAge
allowCredentials
allowedOriginPatterns

次の例では、Cors ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "Cors=[allowedOrigins:https://origin-1,allowedMethods:GET;POST;DELETE,allowedHeaders:*,maxAge:400,allowCredentials:true,allowedOriginPatterns:https://*.test.com:8080]"
        ]
    }
]

JsonToXml

JsonToXml ファクトリは、JSON 応答本文を XML 応答本文に変換します。

このファクトリでは、次の構成パラメータを指定できます。

wrapper: 有効な XML を生成するために別のルートタグが必要な場合の XML 応答のルートタグ名。既定値は response です。

次の例では、JsonToXml ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "JsonToXml=custom-response"
        ]
    }
]

RateLimit

RateLimit ファクトリは、要求ボリュームに基づいて、一致する要求の続行を許可するかどうかを決定します。

このファクトリでは、次の構成パラメータを指定できます。

request limit: ウィンドウ中に受け入れる要求の最大数。
window duration: ウィンドウ期間 (ミリ秒単位) 代わりに、s、m、または h サフィックスを使用して、秒単位、分単位、または時間単位で期間を指定することもできます。
partition source (省略可能): パーティションキーの場所 (claim、header、または IPs)。
partition key (省略可能): 要求カウンターのパーティション分割に使用される値。

次の例では、RateLimit ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RateLimit=1,10s"
        ]
    }
]

次の例では、他の RateLimit 構成を示します。

RateLimit=1,10s
RateLimit=1,10s,{claim:client_id}
RateLimit=1,10s,{header:client_id}
RateLimit=2,10s,{IPs:2;127.0.0.1;192.168.0.1}

RestrictRequestHeaders

RestrictRequestHeaders ファクトリは、ヘッダーに基づいて、一致する要求の続行を許可するかどうかを決定します。

headerList 構成 (大文字と小文字は区別されません) にない HTTP ヘッダーが存在する場合、431 Forbidden error の応答がクライアントに返されます。

このファクトリでは、次の構成パラメータを指定できます。

headerList: 許可されるヘッダーの名前のリスト (大文字と小文字は区別されません)。

次の例では、RestrictRequestHeaders ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RestrictRequestHeaders=Content-Type,x-request-temp"
        ]
    }
]

RewriteAllResponseHeaders

RewriteAllResponseHeaders ファクトリは、複数の応答ヘッダーを一度に書き換えます。

このファクトリでは、次の構成パラメータを指定できます。

pattern to match: ヘッダー値と照合する正規表現。
replacement: 置換値。

次の例では、RewriteAllResponseHeaders ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RewriteAllResponseHeaders=\\d,0"
        ]
    }
]

RewriteResponseBody

RewriteResponseBody ファクトリは、応答の本文を変更します。

このファクトリでは、キーと値のペアのコンマ区切りのリストとして編成された次の構成パラメータを指定できます。各ペアは、pattern to match:replacement の形式で指定できます。

pattern to match: 応答本文のテキストと照合する正規表現。
replacement: 置換値。

次の例では、RewriteResponseBody ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RewriteResponseBody=foo:bar,/path-one/:/path-two/"
        ]
    }
]

RewriteJsonAttributesResponseBody

RewriteJsonAttributesResponseBody ファクトリは、JSONPath 表記を使用して JSON 属性を書き換えます。

このファクトリでは、キーと値のペアのコンマ区切りのリストとして編成された次の構成パラメータを指定できます。各ペアは、jsonpath:replacement の形式で指定できます。

jsonpath: 応答本文と照合する JSONPath 式。
replacement: 置換値。

次の例では、RewriteJsonAttributesResponseBody ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "RewriteJsonAttributesResponseBody=slides[1].title:Welcome,date:11-11-2022"
        ]
    }
]

ロール

Roles ファクトリは、構成されたロールのいずれかを含む要求を承認します。

このファクトリでは、次の構成パラメータを指定できます。

roles: 承認するロールのコンマ区切りのリスト。

次の例では、Roles ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "Roles=role_01,role_02"
        ]
    }
]

スコープ

Scopes ファクトリは、構成された OAuth スコープのいずれかを含む要求を承認します。

このファクトリでは、次の構成パラメータを指定できます。

scopes: 承認する　OAuth　スコープのコンマ区切りのリスト。

次の例では、Scopes ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "Scopes=api.read,api.write,user"
        ]
    }
]

StoreIpAddress

StoreIPAddress ファクトリは、アプリケーションのコンテキストで拡張機能の開発にのみ使用されます。

このファクトリでは、次の構成パラメータを指定できます。

attribute name: 交換属性として IP を保存するために使用される名前。

次の例では、StoreIPAddress ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "StoreIpAddress=ip"
        ]
    }
]

有効な認可トークンがない場合、SSO login ファクトリは認証のためにリダイレクトします。このファクトリは、明示的なフィルターではなく、ルート定義の boolean 値として構成されます。

次の例では、SSO login ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "ssoEnabled": true
    }
]

StoreHeader

StoreHeader ファクトリは、アプリケーションのコンテキストにヘッダー値を保存します。このフィルターは、拡張機能の開発にのみ使用されます。

このファクトリでは、次の構成パラメータを指定できます。

headers: 検査するヘッダーのリスト。最初に見つかったものが使用されます。
attribute name: 交換属性としてヘッダー値を保存するために使用される名前。

次の例では、StoreHeader ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "StoreHeader=x-tracing-header,custom-id,x-custom-id,tracingParam"
        ]
    }
]

XmlToJson

XmlToJson ファクトリは、XML 応答本文を JSON 応答本文に変換します。

このファクトリには、パラメータはありません

次の例では、XmlToJson ファクトリを構成します。

[
    {
        "predicates": [
            "Path=/api/**"
        ],
        "filters": [
            "XmlToJson"
        ]
    }
]

Azure Spring Apps Enterprise プランで VMware Spring Cloud Gateway ルート フィルターを使用する方法

前提条件

フィルターの使用

オープン ソース フィルターを使用する

AddRequestHeader

AddRequestHeadersIfNotPresent

AddRequestParameter

AddResponseHeader

CircuitBreaker

DeDupeResponseHeader

FallbackHeaders

JSONToGRPC

LocalResponseCache

MapRequestHeader

PrefixPath

PreserveHostHeader

RedirectTo

RemoveJsonAttributesResponseBody

RemoveRequestHeader

RemoveRequestParameter

RemoveResponseHeader

RequestHeaderSize

RewriteLocationResponseHeader

RewritePath

RewriteResponseHeader

SetPath

SetRequestHeader

SetResponseHeader

SetStatus

StripPrefix

再試行

RequestSize

TokenRelay

商用フィルターを使用する

AllowedRequestCookieCount

AllowedRequestHeadersCount

AllowedRequestQueryParamsCount

BasicAuth

ClaimHeader

ClientCertificateHeader

CORS

JsonToXml

RateLimit

RestrictRequestHeaders

RewriteAllResponseHeaders

RewriteResponseBody

RewriteJsonAttributesResponseBody

ロール

スコープ

StoreIpAddress

SSO login

StoreHeader

XmlToJson

次のステップ

その他のリソース

Azure Spring Apps Enterprise プランで VMware Spring Cloud Gateway ルートフィルターを使用する方法

オープンソースフィルターを使用する