Azure Spring Apps 엔터프라이즈 플랜에서 VMware Spring Cloud Gateway 경로 필터를 사용하는 방법

참고 항목

기본, 표준 및 엔터프라이즈 계획은 2025년 3월 중순부터 사용되지 않으며 3년의 은퇴 기간이 있습니다. Azure Container Apps로 전환하는 것이 좋습니다. 자세한 내용은 Azure Spring Apps 사용 중지 공지 사항을 참조하세요.

표준 소비 및 전용 계획은 2024년 9월 30일부터 사용되지 않으며 6개월 후에 완전히 종료됩니다. Azure Container Apps로 전환하는 것이 좋습니다. 자세한 내용은 Azure Spring Apps 표준 사용량 및 전용 계획을 Azure Container Apps로 마이그레이션을 참조 하세요.

이 문서는 기본/표준 ✅ 엔터프라이즈에 ❎ 적용됩니다.

이 문서에서는 Azure Spring Apps 엔터프라이즈 플랜에서 VMware Spring Cloud Gateway 경로 필터를 사용하여 요청을 애플리케이션으로 라우팅하는 방법을 설명합니다.

VMware Spring Cloud Gateway는 오픈 소스 Spring Cloud Gateway 프로젝트를 기반으로 하는 상업용 VMware Tanzu 구성 요소입니다. Spring Cloud Gateway는 SSO(Single Sign-On), 액세스 제어, 속도 제한, 복원력, 보안 등과 같은 API 개발 팀의 공통 관심 사항을 처리합니다. 최신 클라우드 네이티브 패턴과 API 개발을 위해 선택하는 프로그래밍 언어를 사용하여 API 제공을 가속화할 수 있습니다.

VMware Spring Cloud Gateway에는 다음 기능이 포함되어 있습니다.

• 동적 라우팅 구성. 다시 컴파일하지 않고 적용 및 변경할 수 있는 개별 애플리케이션과 별개입니다.
• 권한 있는 JWT(JSON Web Token) 클레임을 애플리케이션 서비스로 전송하기 위한 상업용 API 경로 필터
• 클라이언트 인증서 권한 부여.
• 속도 제한 방법.
• 회로 차단기 구성.
• HTTP 기본 인증 자격 증명을 통해 애플리케이션 서비스에 대한 액세스 지원.

VMware Tanzu용 API 포털과 통합하기 위해 경로 구성이 추가되거나 변경되면 VMware Spring Cloud Gateway에서 OpenAPI 버전 3 설명서를 자동으로 생성합니다. 자세한 내용은 VMware Tanzu용 API 포털 사용을 참조하세요.

필수 조건

• Spring Cloud Gateway가 사용하도록 설정되어 이미 프로비전된 Azure Spring Apps 엔터프라이즈 플랜 서비스 인스턴스. 자세한 내용은 빠른 시작: 엔터프라이즈 플랜을 사용하여 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입니다.

다음 예제에서는 게이트웨이 CORS 논리와 다운스트림 논리에서 두 값이 모두 추가되면 Access-Control-Allow-Credentials 및 Access-Control-Allow-Origin 응답 헤더의 중복 값을 제거하는 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

참고 항목

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

다음 예제에서는 /catalog에 대한 요청을 /api/catalog에 보내도록 /api 접두사를 모든 요청 경로에 추가하는 PrefixPath 팩터리를 구성합니다.

[
    {
        "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입니다.

다음 목록에서는 요청 헤더의 크기가 1,000바이트보다 큰 경우 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인 경우 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: 정수 값(예: 404) 또는 열거형의 문자열 표현(예: NOT_FOUND)일 수 있는 유효한 Spring HttpStatus 값입니다.

다음 목록에서는 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: 다시 시도해야 하는 HTTP 상태 코드이며, org.springframework.http.HttpStatus를 사용하여 나타냅니다.
• methods: 다시 시도해야 하는 HTTP 메서드이며 org.springframework.http.HttpMethod를 사용하여 나타냅니다.
• series: 다시 시도할 일련의 상태 코드이며 org.springframework.http.HttpStatus.Series를 사용하여 나타냅니다.
• exceptions: 다시 시도해야 하는 throw된 예외 목록입니다.
• 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: 값이 숫자와 그 뒤에 선택적 DataUnit 접미사(예: KB 또는 MB)로 정의되는 DataSize 형식입니다. 바이트에 대한 기본 접미사 값은 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
    }
]

상용 필터 사용

Kubernetes용 Spring Cloud Gateway는 많은 사용자 지정 GatewayFilter 팩터리도 제공합니다. 다음 섹션에서는 이러한 팩터리를 설명합니다.

AllowedRequestCookieCount

AllowedRequestCookieCount 팩터리는 쿠키 수에 따라 일치하는 요청을 진행할 수 있는지 여부를 결정합니다.

이 팩터리에서 허용하는 구성 매개 변수는 다음과 같습니다.

• amount: 허용되는 쿠키 수입니다.

다음 예제에서는 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 로그인

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
• 빠른 시작: 엔터프라이즈 플랜을 사용하여 Azure Spring Apps에 앱 빌드 및 배포