YARP 쿼리 매개 변수 기반 라우팅

아티클
2025-04-09

구성 또는 코드 통해 지정된 프록시 경로는 일치시킬 경로 또는 호스트 이상을 포함해야 합니다. 또한 경로는 요청에 있어야 하는 하나 이상의 쿼리 매개 변수를 지정할 수 있습니다.

우선 순위

기본 경로 일치 우선 순위는 1) 경로, 2) 메서드, 3) 호스트, 4) 헤더 5) 쿼리 매개 변수입니다. 즉, 메서드를 지정하고 쿼리 매개 변수가 없는 경로는 쿼리 매개 변수를 지정하는 경로와 메서드를 지정하지 않는 경로 앞에 일치합니다. Order 속성을 경로에 설정하여 이를 변경할 수 있습니다.

설정

쿼리 매개 변수는 프록시 경로의 Match 섹션에 지정됩니다.

경로에 여러 쿼리 매개 변수 규칙이 지정된 경우 모든 규칙이 경로와 일치해야 합니다. OR 논리는 쿼리 매개 변수 규칙 내에서 또는 별도의 경로로 구현되어야 합니다.

구성:

"Routes": {
  "route1" : {
    "ClusterId": "cluster1",
    "Match": {
      "Path": "{**catch-all}",
      "QueryParameters": [
        {
          "Name": "queryparam1",
          "Values": [ "value1" ],
          "Mode": "Exact"
        }
      ]
    }
  },
  "route2" : {
    "ClusterId": "cluster1",
    "Match": {
      "Path": "{**catch-all}",
      "QueryParameters": [
        {
          "Name": "queryparam2",
          "Values": [ "1prefix", "2prefix" ],
          "Mode": "Prefix"
        }
      ]
    }
  },
  "route3" : {
    "ClusterId": "cluster1",
    "Match": {
      "Path": "{**catch-all}",
      "QueryParameters": [
        {
          "Name": "queryparam3",
          "Mode": "Exists"
        }
      ]
    }
  },
  "route4" : {
    "ClusterId": "cluster1",
    "Match": {
      "Path": "{**catch-all}",
      "QueryParameters": [
        {
          "Name": "queryparam4",
          "Values": [ "value1", "value2" ],
          "Mode": "Exact"
        },
        {
          "Name": "queryparam5",
          "Mode": "Exists"
        }
      ]
    }
  },
  "route5" : {
    "ClusterId": "cluster1",
    "Match": {
      "Path": "{**catch-all}",
      "QueryParameters": [
        {
          "Name": "queryparam5",
          "Values": [ "value1", "value2" ],
          "Mode": "Contains"
        },
        {
          "Name": "queryparam6",
          "Mode": "Exists"
        }
      ]
    }
  },
   "route6" : {
    "ClusterId": "cluster1",
    "Match": {
      "Path": "{**catch-all}",
      "QueryParameters": [
        {
          "Name": "queryparam6",
          "Values": [ "value1", "value2" ],
          "Mode": "NotContains"
        },
        {
          "Name": "queryparam7",
          "Mode": "Exists"
        }
      ]
    }
  }
}

코드:

var routes = new[]
{
    new RouteConfig()
    {
        RouteId = "route1",
        ClusterId = "cluster1",
        Match = new RouteMatch
        {
            Path = "{**catch-all}",
            QueryParameters = new[]
            {
                new RouteQueryParameter()
                {
                    Name = "QueryParam1",
                    Values = new[] { "value1" },
                    Mode = QueryParameterMatchMode.Exact
                }
            }
        }
    },
    new RouteConfig()
    {
        RouteId = "route2",
        ClusterId = "cluster1",
        Match = new RouteMatch
        {
            Path = "{**catch-all}",
            QueryParameters = new[]
            {
                new RouteQueryParameter()
                {
                    Name = "QueryParam2",
                    Values = new[] { "1prefix", "2prefix" },
                    Mode = QueryParameterMatchMode.Prefix
                }
            }
        }
    },
    new RouteConfig()
    {
        RouteId = "route3",
        ClusterId = "cluster1",
        Match = new RouteMatch
        {
            Path = "{**catch-all}",
            QueryParameters = new[]
            {
                new RouteQueryParameter()
                {
                    Name = "QueryParam3",
                    Mode = QueryParameterMatchMode.Exists
                }
            }
        }
    },
    new RouteConfig()
    {
        RouteId = "route4",
        ClusterId = "cluster1",
        Match = new RouteMatch
        {
            Path = "{**catch-all}",
            QueryParameters = new[]
            {
            new RouteQueryParameter()
                {
                    Name = "QueryParam4",
                    Values = new[] { "value1", "value2" },
                    Mode = QueryParameterMatchMode.Exact
                },
                new RouteQueryParameter()
                {
                    Name = "QueryParam5",
                    Mode = QueryParameterMatchMode.Exists
                }
            }
        }
    },
    new RouteConfig()
    {
        RouteId = "route5",
        ClusterId = "cluster1",
        Match = new RouteMatch
        {
            Path = "{**catch-all}",
            QueryParameters = new[]
            {
                new RouteQueryParameter()
                {
                    Name = "QueryParam5",
                    Values = new[] { "value1", "value2" },
                    Mode = QueryParameterMatchMode.Contains
                }
            }
        }
    },
    new RouteConfig()
    {
        RouteId = "route6",
        ClusterId = "cluster1",
        Match = new RouteMatch
        {
            Path = "{**catch-all}",
            QueryParameters = new[]
            {
                new RouteQueryParameter()
                {
                    Name = "QueryParam6",
                    Values = new[] { "value1", "value2" },
                    Mode = QueryParameterMatchMode.NotContains
                }
            }
        }
    }
};

계약

RouteQueryParameter 코드 계약을 정의하고 구성에서 매핑됩니다.

이름

요청에 대해 확인할 쿼리 매개 변수 이름입니다. 비어있지 않은 값이 필요합니다. 이 필드는 대/소문자를 구분하지 않습니다.

가치

검색할 수 있는 값 목록입니다. 쿼리 매개변수는 지정된 Mode에 따라 'NotContains'를 제외한 이러한 값 중 하나 이상과 일치해야 합니다. Mode Exists설정되지 않는 한 하나 이상의 값이 필요합니다.

모드

QueryParameterMatchMode 요청 쿼리 매개 변수와 값을 일치시킬 방법을 지정합니다. 기본값은 Exact.

정확한 - 쿼리 매개 변수는 IsCaseSensitive값에 따라 전체적으로 일치해야 합니다. 단일 쿼리 매개 변수만 지원됩니다. 이름이 같은 쿼리 매개 변수가 여러 대 있는 경우 일치가 실패합니다.
접두사 - 쿼리 매개 변수는 접두사로 일치해야 하며 IsCaseSensitive값이 적용됩니다. 단일 쿼리 매개 변수만 지원됩니다. 이름이 같은 쿼리 매개 변수가 여러 대 있는 경우 일치가 실패합니다.
Exists - 쿼리 매개 변수가 존재하고 비어 있지 않은 값을 포함해야 합니다.
Contains - 쿼리 매개 변수는 일치 항목에 대한 값을 포함해야 하며, 이는 IsCaseSensitive의 값에 따라 결정됩니다. 단일 쿼리 매개 변수만 지원됩니다. 이름이 같은 쿼리 매개 변수가 여러 대 있는 경우 일치가 실패합니다.
NotContains - 쿼리 매개 변수는 IsCaseSensitive값에 따라 일치하는 값을 포함하지 않아야 합니다. 단일 쿼리 매개 변수만 지원됩니다. 이름이 같은 쿼리 매개 변수가 여러 대 있는 경우 일치가 실패합니다.

대소문자 구분

값 일치를 대/소문자를 구분하거나 구분하지 않는 것으로 수행해야 하는지 여부를 나타냅니다. 기본값은 false, 민감하지 않습니다.

인코딩

요청 쿼리 문자열은 경로 규칙과 일치하기 전에 구문 분석 및 디코딩됩니다.

   "route8" : {
    "ClusterId": "cluster1",
    "Match": {
      "Path": "{**catch-all}",
      "QueryParameters": [
        {
          "Name": "queryparam8",
          "Values": [ "another value" ],
          "Mode": "Exact"
        }
      ]
    }

일치하는 것들

?queryparam8=another%20value

또는

?queryparam8=another+value

예제

이러한 예제에서는 위에서 지정한 구성을 사용합니다.

시나리오 1 - 정확한 쿼리 매개 변수 일치

다음 쿼리 매개 변수가 있는 요청은 route1과 일치합니다.

?QueryParam1=Value1

이름이 같은 여러 쿼리 매개 변수는 현재 지원되지 않으며 일치하지 않습니다.

?QueryParam1=Value1&QueryParam1=Value2

시나리오 2 - 여러 값

Route2는 쿼리 매개 변수("1prefix", "2prefix")에서 검색할 여러 값을 정의했습니다. 모든 값이 허용됩니다. 또한 ModePrefix지정하여 해당 값으로 시작하는 모든 쿼리 매개 변수를 사용할 수 있습니다.

다음 쿼리 매개 변수 중 하나라도 route2와 일치합니다.

?QueryParam2=1prefix

?QueryParam2=2prefix

?QueryParam2=1prefix-extra

?QueryParam2=2prefix-extra

이름이 같은 여러 쿼리 매개 변수는 현재 지원되지 않으며 일치하지 않습니다.

?QueryParam2=2prefix&QueryParam2=1prefix

시나리오 3 - 존재합니다

Route3에는 쿼리 매개 변수 "QueryParam3"이 비어 있지 않은 값이 있어야 합니다.

다음은 route3과 일치하는 예제입니다.

?QueryParam3=value

빈 쿼리 매개 변수는 일치하지.

?QueryParam3
?QueryParam3=

이 모드는 쿼리 매개 변수 내용을 보지 않으므로, 이름이 같은 여러 쿼리 매개 변수와 여러 값의 쿼리 매개 변수를 지원합니다. 다음 항목이 일치합니다.

?QueryParam3=value1&QueryParam3=value2

시나리오 4 - 여러 쿼리 매개변수

Route4에는 지정된 QueryParam4에 따라 일치하는 QueryParam5 및 Mode이 모두 필요합니다. 다음 쿼리 매개 변수는 route4와 일치합니다.

?QueryParam4=value1&QueryParam5=AnyValue

?QueryParam4=value2&QueryParam5=AnyValue

필요한 쿼리 매개 변수 중 하나가 누락되었으므로 이러한 route4와 일치하지 않습니다.

?QueryParam4=value2

?QueryParam5=AnyValue