Azure Spring Apps Enterprise プランで VMware Spring Cloud Gateway ルート フィルターを使用する方法
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, ,"
]
}
]
この例では、要求値 POST
api.example.com/some/object/name
に対して、Location
応答ヘッダー値である object-service.prod.example.net/v2/some/object/id
が 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
: 有効な SpringHttpStatus
値。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
ファクトリは、要求に BasicAuth
Authorization
ヘッダーを追加します。
このファクトリには、パラメータはありません
次の例では、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
有効な認可トークンがない場合、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"
]
}
]