API 스테이지를 REST API의 사용자 지정 도메인 이름에 연결하는 라우팅 규칙 - Amazon API Gateway
API Gateway 라우팅 규칙 조건 유형제한 사항

API 스테이지를 REST API의 사용자 지정 도메인 이름에 연결하는 라우팅 규칙

라우팅 규칙은 일치 시 작업을 간접적으로 호출하는 일련의 조건입니다. 예를 들어 규칙은 수신 요청을 헤더 Hello:World를 포함하고 REST API의 production 스테이지에 대한 기본 경로 users를 포함하는 사용자 지정 도메인 이름으로 라우팅할 수 있습니다.

규칙은 우선 순위에 따라 평가되며 라우팅 모드를 ROUTING_RULE_THEN_API_MAPPING으로 설정하면 API Gateway는 API 매핑을 평가하기 전에 항상 모든 라우팅 규칙을 평가합니다. 다음 목록은 라우팅 규칙이 조건, 작업 및 우선 순위를 사용하는 방법을 설명합니다.

조건

규칙에 대한 조건이 충족되면 작업이 수행됩니다. API Gateway는 최대 2개의 헤더 조건과 1개의 경로 조건을 지원합니다. API Gateway는 헤더 조건과 기본 경로 조건을 함께 평가합니다.

조건 없이 규칙을 생성할 수 있습니다. API Gateway가 이 규칙을 평가하면 작업이 항상 수행됩니다. catch-all 규칙으로 조건 없이 규칙을 생성할 수 있습니다.

헤더 조건에 대한 자세한 내용은 헤더 조건 일치 섹션을 참조하세요. 경로 조건에 대한 자세한 내용은 기본 경로 조건 일치 섹션을 참조하세요.

작업

작업은 조건을 라우팅 규칙과 일치시킨 결과입니다. 현재 지원되는 유일한 작업은 REST API의 스테이지를 간접적으로 호출하는 것입니다.

각 규칙에는 하나의 작업이 있을 수 있습니다.

우선순위

우선순위는 가장 낮은 값에서 가장 높은 값에 이르기까지 규칙이 평가되는 순서를 결정합니다. 규칙의 우선 순위가 동일할 수는 없습니다.

우선 순위를 1~1,000,000으로 설정할 수 있습니다. 규칙의 우선 순위가 1인 경우 API Gateway는 먼저 규칙을 평가합니다. 규칙을 생성할 때 우선 순위에 격차를 추가하는 것이 좋습니다. 이렇게 하면 규칙의 우선 순위를 전환하고 새 규칙을 추가할 수 있습니다. 자세한 내용은 라우팅 규칙의 우선 순위 변경 섹션을 참조하세요.

API Gateway가 라우팅 규칙을 평가하는 방법의 예는 API Gateway가 라우팅 규칙을 평가하는 방법의 예 섹션을 참조하세요.

API Gateway 라우팅 규칙 조건 유형

다음 섹션에서는 라우팅 규칙 조건 유형에 대해 설명합니다. API Gateway는 모든 조건이 true인 경우에만 규칙을 일치시킵니다.

헤더 조건 일치

헤더 조건을 만들 때 Hello:World와 같은 헤더 이름과 헤더 glob 값을 일치시킬 수 있습니다. API Gateway는 리터럴 일치를 사용하여 일치 헤더 조건을 검증합니다. 헤더 사이에 AND를 사용하여 조건에서 최대 두 개의 헤더를 사용할 수 있습니다. 예를 들어 수신 요청에 Hello:World 및 x-version:beta가 포함된 경우 조건이 일치할 수 있습니다.

헤더 이름 일치는 대/소문자를 구분하지 않지만 헤더 glob 값은 대/소문자를 구분합니다. Hello:World는 hello:World와 일치하지만 Hello:world와는 일치하지 않습니다.

제한된 헤더 값 목록은 제한 사항 섹션을 참조하세요.

헤더 조건에 와일드카드 사용

헤더 glob 값에만 와일드카드를 사용할 수 있으며 와일드카드는 *prefix-match, suffix-match* 또는 *contains*이어야 합니다. 다음 표에는 헤더 조건에 대한 일치를 위해 와일드카드를 사용하는 방법에 대한 예제가 나와 있습니다.

헤더 조건 라우팅 규칙과 일치하는 요청 라우팅 규칙과 일치하지 않는 요청

x-version: a*

  • x-version: account

  • x-version: alpha

  • x-version: backup

  • x-version: beta

  • x-version: users

x-version: *a

  • x-version: alpha

  • x-version: beta

  • x-version: account

  • x-version: backup

  • x-version: users

x-version: *a*

  • x-version: account

  • x-version: alpha

  • x-version: backup

  • x-version: beta

  • x-version: users

x-version: *a* 및 x-version: *b*

  • x-version: backup

  • x-version: beta

  • x-version: account

  • x-version: alpha

  • x-version: users

x-version: b* 및 x-version: *a

  • x-version: beta

  • x-version: account

  • x-version: alpha

  • x-version: backup

  • x-version: users

x-version: *

  • x-version: account

  • x-version: alpha

  • x-version: backup

  • x-version: beta

  • x-version: users

없음

Accept:application/json,text/xml과 같이 여러 헤더 값에 대한 조건을 만드는 경우 헤더 조건에 *contains*를 사용하고 쉼표(,) 문자를 사용하여 조건을 만들지 않는 것이 좋습니다.

API Gateway는 리터럴 방식으로 헤더 조건을 일치시키므로 시맨틱 일치는 다르게 라우팅될 수 있습니다. 다음 표는 라우팅 규칙 결과의 차이를 보여줍니다.

헤더 조건 라우팅 규칙과 일치하는 요청 라우팅 규칙과 일치하지 않는 요청

Accept: *json

  • Accept:application/json Accept:text/xml

  • Accept:application/json,text/xml

Accept: *json*

  • Accept:application/json Accept:text/xml

  • Accept:application/json,text/xml

없음

기본 경로 조건 일치

기본 경로 조건을 만들 때 수신 요청에 지정한 경로가 포함된 경우 규칙이 일치됩니다. 일치는 대/소문자를 구분하므로 New/Users 경로는 new/users와 일치하지 않습니다.

하나의 기본 경로에 대해서만 기본 경로 조건을 만들 수 있습니다.

제한된 기본 경로 조건 목록은 제한 사항 섹션을 참조하세요.

기본 경로 조건을 사용하여 기본 경로 제거

기본 경로 조건을 만들 때 기본 경로를 제거하도록 선택할 수 있습니다. 기본 경로를 제거하면 API Gateway는 대상 API를 간접적으로 호출할 때 일치된 수신 기본 경로를 제거합니다. 이는 API 매핑을 사용할 때와 동일한 동작입니다. 기본 경로를 제거하지 않으면 API Gateway는 전체 기본 경로를 대상 API로 전달합니다. API 매핑을 다시 만들 때만 기본 경로를 제거하는 것이 좋습니다.

다음 표에는 API Gateway가 기본 경로 제거 조건을 평가하는 방법에 대한 예제가 나와 있습니다.

Condition 기본 경로 제거 수신 요청 결과

기본 경로에 PetStoreShopper/dogs가 포함된 경우

 True

GET https://example.com/PetStoreShopper/dogs

API Gateway는 / 리소스의 GET 메서드를 직접적으로 호출합니다.

기본 경로에 PetStoreShopper/dogs가 포함된 경우

 False

GET https://example.com/PetStoreShopper/dogs

API Gateway는 PetStoreShopper/dogs 리소스의 GET 메서드를 직접적으로 호출합니다.

기본 경로에 PetStoreShopper가 포함된 경우

 True

GET https://example.com/PetStoreShopper/dogs

API Gateway는 dogs 리소스의 GET 메서드를 직접적으로 호출합니다.

기본 경로에 PetStoreShopper가 포함된 경우

 False

GET https://example.com/PetStoreShopper/dogs

API Gateway는 PetStoreShopper/dogs 리소스의 GET 메서드를 직접적으로 호출합니다.

기본 경로에 PetStoreShopper가 포함된 경우

 True

GET https://example.com/PetStoreShopper?birds=available

API Gateway는 쿼리 문자열 파라미터 birds=available을 사용하여 / 리소스의 GET 메서드를 직접적으로 호출합니다.

기본 경로에 PetStoreShopper가 포함된 경우

 False

GET https://example.com/PetStoreShopper?birds=available

API Gateway는 쿼리 문자열 파라미터 birds=available을 사용하여 /PetStoreShopper 리소스의 GET 메서드를 직접적으로 호출합니다.

제한 사항

  • 대상 API와 사용자 지정 도메인 이름은 동일한 AWS 계정에 있어야 합니다.

  • 각 규칙에는 하나의 대상 API가 있을 수 있습니다.

  • 프라이빗 사용자 지정 도메인 이름에서 프라이빗 API로, 퍼블릭 사용자 지정 도메인 이름에서 퍼블릭 API로 라우팅하는 규칙만 생성할 수 있습니다. 퍼블릭 리소스와 프라이빗 리소스를 혼합할 수는 없습니다.

  • 사용자 지정 도메인 이름에 REST 및 HTTP API 모두에 대한 API 매핑이 있는 경우 라우팅 규칙이 지원되지 않습니다.

  • 최대 우선 순위 수는 1,000,000입니다.

  • 헤더 제한:

    • 각 anyOf 조건에는 헤더 값이 하나만 포함될 수 있습니다.

    • 헤더 이름 및 헤더 glob 값에 허용되는 유일한 문자는 RFC 7230에 지정되어 있으며 a-z, A-Z, 0-9 및 다음 특수 문자입니다. *?-!#$%&'.^_`|~

    • 헤더 glob 값에 와일드카드를 사용할 수 있지만 와일드카드는 *prefix-match, suffix-match* 또는 *contains*이어야 합니다. 헤더 glob 값의 중간에 * 기호를 사용할 수 없습니다.

    • 와일드카드 헤더 이름은 지원되지 않습니다.

    • 헤더 이름은 40자 미만이어야 합니다.

    • 헤더 glob 값은 128자 미만이어야 합니다.

    • 중위 일치의 헤더 glob 값은 40자 미만이어야 합니다.

    • 다음 헤더는 조건으로 지원되지 않습니다.

      • access-control-*

      • apigw-*

      • Authorization

      • Connection

      • Content-Encoding

      • Content-Length

      • Content-Location

      • Forwarded

      • Keep-Alive

      • Origin

      • Proxy-Authenticate

      • Proxy-Authorization

      • TE

      • Trailers

      • Transfer-Encoding

      • Upgrade

      • x-amz-*

      • x-amzn-*

      • X-Forwarded-For

      • X-Forwarded-Host

      • X-Forwarded-Proto

      • Via

  • 기본 경로 제한:

    • 기본 경로 길이는 128자 미만이어야 합니다.

    • 기본 경로에는 문자, 숫자 및 다음 문자만 포함해야 합니다. $-_.+!*'()/

    • 기본 경로는 백슬래시(/) 문자로 시작하거나 끝날 수 없습니다.