# 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-routing-rules-condition-headers) 섹션을 참조하세요. 경로 조건에 대한 자세한 내용은 [기본 경로 조건 일치](#rest-api-routing-rules-condition-path) 섹션을 참조하세요. **작업** 작업은 조건을 라우팅 규칙과 일치시킨 결과입니다. 현재 지원되는 유일한 작업은 REST API의 스테이지를 간접적으로 호출하는 것입니다. 각 규칙에는 하나의 작업이 있을 수 있습니다. **우선순위** 우선순위는 가장 낮은 값에서 가장 높은 값에 이르기까지 규칙이 평가되는 순서를 결정합니다. 규칙의 우선순위가 동일할 수는 없습니다. 우선순위를 1\$11,000,000으로 설정할 수 있습니다. 규칙의 우선순위가 1인 경우 API Gateway는 먼저 규칙을 평가합니다. 규칙을 생성할 때 우선순위에 격차를 추가하는 것이 좋습니다. 이렇게 하면 규칙의 우선순위를 전환하고 새 규칙을 추가할 수 있습니다. 자세한 내용은 [라우팅 규칙의 우선순위 변경](apigateway-routing-rules-use.md#rest-api-routing-rules-change-priority) 섹션을 참조하세요. API Gateway가 라우팅 규칙을 평가하는 방법의 예는 [API Gateway가 라우팅 규칙을 평가하는 방법의 예](rest-api-routing-rules-examples.md) 섹션을 참조하세요. ## API Gateway 라우팅 규칙 조건 유형 다음 섹션에서는 라우팅 규칙 조건 유형에 대해 설명합니다. API Gateway는 모든 조건이 true인 경우에만 규칙을 일치시킵니다. ### 헤더 조건 일치 헤더 조건을 만들 때 `Hello:World`와 같은 헤더 이름과 헤더 glob 값을 일치시킬 수 있습니다. API Gateway는 리터럴 일치를 사용하여 일치 헤더 조건을 검증합니다. 헤더 사이에 `AND`를 사용하여 조건에서 최대 두 개의 헤더를 사용할 수 있습니다. 예를 들어 수신 요청에 `Hello:World` 및 `x-version:beta`가 포함된 경우 조건이 일치할 수 있습니다. 헤더 이름 일치는 대/소문자를 구분하지 않지만 헤더 glob 값은 대/소문자를 구분합니다. `Hello:World`는 `hello:World`와 일치하지만 `Hello:world`와는 일치하지 않습니다. 제한된 헤더 값 목록은 [제한 사항](#rest-api-routing-rules-restrictions) 섹션을 참조하세요. #### 헤더 조건에 와일드카드 사용 헤더 glob 값에만 와일드카드를 사용할 수 있으며 와일드카드는 `*prefix-match`, `suffix-match*` 또는 `*contains*`이어야 합니다. 다음 표에는 헤더 조건에 대한 일치를 위해 와일드카드를 사용하는 방법에 대한 예제가 나와 있습니다. | 헤더 조건 | 라우팅 규칙과 일치하는 요청 | 라우팅 규칙과 일치하지 않는 요청 | | --- | --- | --- | | `x-version: a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | | `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | | `x-version: *a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | | `x-version: *a*` 및 `x-version: *b*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | | `x-version: b*` 및 `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | | `x-version: *` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | 없음 | `Accept:application/json,text/xml`과 같이 여러 헤더 값에 대한 조건을 만드는 경우 헤더 조건에 `*contains*`를 사용하고 쉼표(`,`) 문자를 사용하여 조건을 만들지 않는 것이 좋습니다. API Gateway는 리터럴 방식으로 헤더 조건을 일치시키므로 시맨틱 일치는 다르게 라우팅될 수 있습니다. 다음 표는 라우팅 규칙 결과의 차이를 보여줍니다. | 헤더 조건 | 라우팅 규칙과 일치하는 요청 | 라우팅 규칙과 일치하지 않는 요청 | | --- | --- | --- | | `Accept: *json` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | | `Accept: *json*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/rest-api-routing-rules.html) | 없음 | ### 기본 경로 조건 일치 기본 경로 조건을 만들 때 수신 요청에 지정한 경로가 포함된 경우 규칙이 일치됩니다. 일치는 대/소문자를 구분하므로 `New/Users` 경로는 `new/users`와 일치하지 않습니다. 하나의 기본 경로에 대해서만 기본 경로 조건을 만들 수 있습니다. 제한된 기본 경로 조건 목록은 [제한 사항](#rest-api-routing-rules-restrictions) 섹션을 참조하세요. #### 기본 경로 조건을 사용하여 기본 경로 제거 기본 경로 조건을 만들 때 기본 경로를 제거하도록 선택할 수 있습니다. 기본 경로를 제거하면 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](https://datatracker.ietf.org/doc/html/rfc7230)에 지정되어 있으며 `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-apigw-api-id` + `X-Forwarded-For` + `X-Forwarded-Host` + `X-Forwarded-Proto` + `x-restAPI` + `Via` + 기본 경로 제한: + 기본 경로 길이는 128자 미만이어야 합니다. + 기본 경로에는 문자, 숫자 및 다음 문자만 포함해야 합니다. `$-_.+!*'()/` 이러한 문자는 정규 표현식(regex)에서 지원되지 않습니다. + 기본 경로는 백슬래시(`\`) 문자로 시작하거나 끝날 수 없습니다. # API Gateway가 라우팅 규칙을 평가하는 방법의 예 다음 섹션에서는 API Gateway가 라우팅 규칙 및 API 매핑을 평가하는 방법의 네 가지 예를 보여줍니다. ## 예제 1: 라우팅 규칙만 이 예제에서 사용자 지정 도메인 이름 `https://petstore.example.com`의 라우팅 모드는 `ROUTING_RULE_ONLY`로 설정되며 다음 라우팅 규칙 및 우선순위를 포함합니다. | 규칙 ID | 우선순위 | 조건 | 작업 | | --- | --- | --- | --- | | `abc123` | 10 | 요청에 `Hello:World` 헤더가 포함된 경우 | 대상 API 1 | | `zzz000` | 50 | 요청에 `Accept:image/webp` 및 `Pet:Dog-*` 헤더가 포함되어 있으며 기본 경로에 `PetStoreShopper`가 포함된 경우 | 대상 API 2 | | `efg456` | 100 | 없음 | 대상 API 3 | 다음 표는 API Gateway가 이전 라우팅 규칙을 예제 요청에 적용하는 방법을 보여줍니다. | 요청 | 선택한 API | 설명 | | --- | --- | --- | | `https://petstore.example.com -h "Hello:World"` | 대상 API 1 | 요청은 라우팅 규칙 `abc123`과 일치합니다. | | `https://petstore.example.com/PetStoreShopper -h "Hello:World", "Pet:Dog-Bella", "Accept:image/webp"` | 대상 API 1 | API Gateway는 모든 라우팅 규칙을 우선순위에 따라 평가합니다. 라우팅 규칙 `abc123`은 우선순위가 가장 높고 조건이 일치하므로 API Gateway는 대상 API 1을 간접적으로 호출합니다. 요청 조건이 라우팅 규칙 `zzz000`과도 일치하지만 API Gateway는 일치가 완료된 후 다른 라우팅 규칙을 평가하지 않습니다. | | `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella", "Accept:image/webp"` | 대상 API 2 | 요청은 라우팅 규칙 `zzz000`과 일치합니다. `Pet:Dog-Bella`가 `Pet:Dog-*`와 문자열 일치이므로 일치됩니다. | | `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella"` | 대상 API 3 | 요청이 라우팅 규칙 `abc123`과 일치하지 않습니다. 필요한 모든 헤더가 존재하지 않으므로 요청이 라우팅 규칙 `zzz000`과 일치하지 않습니다. 다음 우선순위 규칙은 모든 수신 요청과 일치하므로 API Gateway는 대상 API 3을 간접적으로 호출합니다. | ## 예제 2: 라우팅 규칙 및 API 매핑 이 예제에서 사용자 지정 도메인 이름 `https://petstore.diagram.example.com`의 라우팅 모드는 `ROUTING_RULE_THEN_API_MAPPING`로 설정되며 다음 라우팅 규칙 및 API 매핑을 포함합니다. | 규칙 ID | 우선순위 | 조건 | 작업 | | --- | --- | --- | --- | | `abc123` | 1 | 요청에 `pets` 헤더가 포함된 경우 | `PetStore` API의 `Prod` 스테이지를 간접적으로 호출합니다. | | `000zzz` | 5 | 요청에 `Cookie` 및 `*ux=beta*` 헤더가 포함되어 있으며 기본 경로에 `/refunds`가 포함된 경우 | `Refunds` API의 `Beta` 스테이지를 간접적으로 호출합니다. | 다음 표에는 `https://petstore.backup.example.com`에 대한 API 매핑이 나와 있습니다. | API 매핑 | 선택한 API | | --- | --- | | `/refunds` | `Refunds` API의 `Prod` 스테이지를 간접적으로 호출합니다. | | `(none)` | `Search` API의 `Prod` 스테이지를 간접적으로 호출합니다. | 다음 다이어그램은 API Gateway가 이전 라우팅 규칙 및 API 매핑을 예제 요청에 적용하는 방법을 보여줍니다. 예제 요청은 이 다이어그램 뒤의 표에 요약되어 있습니다. ![\[API Gateway가 이전 라우팅 규칙 및 API 매핑을 적용하는 방법을 보여주는 다이어그램입니다.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/rr-diagram.png) 다음 표는 API Gateway가 이전 라우팅 규칙 및 API 매핑을 예제 요청에 적용하는 방법을 보여줍니다. | 요청 | 선택한 API | 설명 | | --- | --- | --- | | `https://petstore.diagram.com/pets` | `PetStore` API 스테이지의 `Prod` 이름입니다. | 요청은 라우팅 규칙 `abc123`과 일치합니다. | | `https://petstore.diagram.example.com/refunds -h "Cookie:lang=en-us;ux=beta"` | `Refunds` API 스테이지의 `Beta` 이름입니다. | 요청은 라우팅 규칙 `000zzz`과 일치합니다. `Cookie` 헤더에는 이 조건에 대한 올바른 `*contains*` 일치 및 기본 경로 일치가 포함됩니다. | | `https://petstore.diagram.example.com/refunds` | `Refunds` API 스테이지의 `Prod` 이름입니다. | 요청에 라우팅 규칙 `zzz000`과 일치하는 데 필요한 헤더가 없습니다. API Gateway가 라우팅 규칙과 성공적으로 일치되지 않는 경우 API 매핑으로 대체됩니다. API Gateway는 기본 경로를 `Refunds` API의 `Prod` 스테이지에 매핑할 수 있습니다. | | `https://petstore.diagram.example.com/` | `Search` API 스테이지의 `Prod` 이름입니다. | 요청은 API 매핑을 빈 경로 `(none)`과 일치시킵니다. | ## 예제 3: 여러 수준의 라우팅 규칙 및 API 매핑 이 예제에서 사용자 지정 도메인 이름 `https://petstore.backup.example.com`의 라우팅 모드는 `ROUTING_RULE_THEN_API_MAPPING`로 설정되며 다음 라우팅 규칙 및 API 매핑을 포함합니다. 다음 표에는 `https://petstore.backup.example.com`에 대한 라우팅 규칙이 나와 있습니다. | 규칙 ID | 우선순위 | 조건 | 작업 | | --- | --- | --- | --- | | `abc123` | 10 | 요청에 `Hello:World` 헤더가 포함된 경우 | 대상 API 1 | | `000zzz` | 50 | 요청에 `Accept`, `image/webp` 및 `Pet:Dog-*` 헤더가 포함되어 있으며 기본 경로에 `PetStoreShopper`가 포함된 경우 | 대상 API 2 | 다음 표에는 `https://petstore.backup.example.com`에 대한 API 매핑이 나와 있습니다. | API 매핑 | 선택한 API | | --- | --- | | `PetStoreShopper` | 대상 API 3 | | `PetStoreShopper/cats` | 대상 API 4 | 다음 표는 API Gateway가 이전 라우팅 규칙 및 API 매핑을 예제 요청에 적용하는 방법을 보여줍니다. | 요청 | 선택한 API | 설명 | | --- | --- | --- | | `https://petstore.example.com/PetStoreShopper -h "Accept:image/webp", "Pet:Cats" ` | 대상 API 3 | 요청에 라우팅 규칙 `zzz000`과 일치하는 데 필요한 헤더가 없습니다. API Gateway가 라우팅 규칙과 성공적으로 일치되지 않는 경우 API 매핑으로 대체됩니다. API Gateway는 기본 경로를 대상 API 3에 매핑할 수 있습니다. | | `https://petstore.example.com/PetStoreShopper/cats -h "Hello:World"` | 대상 API 1 | 요청은 라우팅 규칙 `abc123`과 일치합니다. 라우팅 모드가 `ROUTING_RULE_THEN_API_MAPPING`으로 설정된 경우 라우팅 규칙은 항상 API 매핑보다 우선 적용됩니다. | | `https://petstore.example.com/Admin -h "Pet:Dog-Bella"` | 없음 | 요청이 라우팅 규칙 또는 API 매핑과 일치하지 않습니다. 기본 라우팅 규칙이 없으므로 API Gateway는 호출을 거부하고 호출자에게 `403 Forbidden` 상태 코드를 보냅니다. | ## 예제 4: 와일드카드 도메인 이름에 대한 라우팅 규칙 이 예제에서 사용자 지정 도메인 이름 `https://*.example.com`은 와일드카드 도메인 이름입니다. 와일드카드는 동일한 도메인으로 다시 라우팅되는 모든 하위 도메인을 지원합니다. 다음 예제 라우팅 규칙은 하위 도메인이 `Host` 헤더를 사용하여 다른 대상 API로 라우팅할 수 있도록 이 동작을 변경합니다. 다음 표에는 `https://*.example.com`에 대한 라우팅 규칙이 나와 있습니다. | 규칙 ID | 우선순위 | 조건 | 작업 | | --- | --- | --- | --- | | `abc123` | 10 | 요청에 `Host:a.example.com` 헤더가 포함된 경우 | 대상 API 1 | | `000zzz` | 50 | 요청에 `Host:b.example.com` 헤더가 포함된 경우 | 대상 API 2 | | `efg456` | 500 | 없음 | 대상 API 3 | 다음 표는 API Gateway가 이전 라우팅 규칙을 예제 요청에 적용하는 방법을 보여줍니다. | 요청 | 선택한 API | 설명 | | --- | --- | --- | | `https://a.example.com` | 대상 API 1 | `Host` 헤더는 `a.example.com`입니다. 이 요청은 라우팅 규칙 `abc123`과 일치합니다. | | `https://b.example.com` | 대상 API 2 | `Host` 헤더는 `b.example.com`입니다. 이 요청은 라우팅 규칙 `000zzz`과 일치합니다. | | `https://testing.example.com` | 대상 API 3 | 이는 catch-all 라우팅 규칙 `efg456`과 일치합니다. | # 라우팅 규칙을 사용하는 방법 AWS Management Console, AWS CLI 또는 AWS SDK를 사용하여 라우팅 규칙을 만들 수 있습니다. 규칙을 생성한 후에는 우선순위를 변경할 수 있습니다. ## 라우팅 규칙 만들기 다음 절차에서는 라우팅 모드가 `ROUTING_RULE_THEN_API_MAPPING` 또는 `ROUTING_RULE_ONLY`로 설정된 사용자 지정 도메인 이름에 대한 라우팅 규칙을 만드는 방법을 보여줍니다. ------ #### [ AWS Management Console ] 1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다. 1. 기본 탐색 창에서 **사용자 지정 도메인 이름**을 선택합니다. 1. 사용자 지정 도메인 이름을 선택합니다. 1. **라우팅 세부 정보** 탭에서 **라우팅 규칙 추가**를 선택합니다. 1. **새 조건 추가**를 선택하여 새 조건을 추가합니다. 헤더 또는 기본 경로 조건을 추가할 수 있습니다. 모든 수신 요청을 사용자 지정 도메인 이름과 일치시키려면 조건을 추가하지 마세요. 1. **작업**에서 드롭다운을 사용하여 대상 API와 대상 스테이지를 선택합니다. 1. **다음**을 선택합니다. 1. 우선순위 필드에 우선순위의 숫자를 입력합니다. API Gateway는 규칙을 가장 낮은 값에서 가장 높은 값에 이르기까지 우선순위에 따라 평가합니다. 조건 없이 규칙을 생성하는 경우 높은 값 우선순위를 사용하는 것이 좋습니다. 1. **라우팅 규칙 생성**을 선택합니다. ------ #### [ AWS CLI ] 다음 [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html) 명령은 우선순위가 50인 라우팅 규칙을 만듭니다. 이 예제에서 API Gateway는 헤더 `Hello:World`와 `x-version:beta` 및 기본 경로 `PetStoreShopper`가 있는 모든 수신 요청을 대상 API `a1b2c3`으로 라우팅합니다. ``` aws apigatewayv2 create-routing-rule \ --domain-name 'api.example.com' \ --priority 50 \ --conditions '[ { "MatchHeaders": { "AnyOf": [ { "Header": "Hello", "ValueGlob": "World" } ] } }, { "MatchHeaders": { "AnyOf": [ { "Header": "x-version", "ValueGlob": "beta" } ] } }, { "MatchBasePaths": { "AnyOf": [ "PetStoreShopper" ] } } ]'\ --actions '[ { "InvokeApi": { "ApiId": "a1b2c3", "Stage": "prod" } } ]' ``` 출력은 다음과 같습니다. ``` { "Actions": [ { "InvokeApi": { "ApiId": "a1b2c3", "Stage": "prod", "StripBasePath": false } } ], "Conditions": [ { "MatchHeaders": { "AnyOf": [ { "Header": "Hello", "ValueGlob": "World" } ] } }, { "MatchHeaders": { "AnyOf": [ { "Header": "x-version", "ValueGlob": "beta" } ] } }, { "MatchBasePaths": { "AnyOf": [ "PetStoreShopper" ] } } ], "Priority": 50, "RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123", "RoutingRuleId": "abc123" } ``` ------ ## 라우팅 규칙의 우선순위 변경 라우팅 규칙의 우선순위를 변경할 수 있습니다. 이는 즉시 적용되며 API 소비자가 사용자 지정 도메인 이름을 간접적으로 호출하는 방식에 영향을 미칠 수 있습니다. 라우팅 규칙의 우선순위를 설정할 때 규칙 사이에 간격을 두는 것이 좋습니다. 예를 들어 두 가지 라우팅 규칙, 즉 우선순위가 50인 규칙 `abc123`과 우선순위가 150인 규칙 `zzz000`을 고려합니다. API Gateway가 규칙 `zzz000`을 먼저 평가하도록 규칙의 우선순위를 변경하려면 규칙 `zzz000`의 우선순위를 30으로 변경할 수 있습니다. ------ #### [ AWS Management Console ] 1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다. 1. 기본 탐색 창에서 **사용자 지정 도메인 이름**을 선택합니다. 1. 사용자 지정 도메인 이름을 선택합니다. 1. **라우팅 세부 정보** 탭에서 라우팅 규칙을 선택한 다음 **편집**을 선택합니다. 1. **다음**을 선택합니다. 1. 우선순위에 새 우선순위를 입력합니다. 1. **변경 사항 저장**을 선택합니다. ------ #### [ AWS CLI ] 다음 [put-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/put-routing-rule.html) 명령은 라우팅 규칙 `abc123`의 우선순위를 변경합니다. ``` aws apigatewayv2 put-routing-rule \ --domain-name 'api.example.com' \ --priority 30 \ --routing-rule-id abc123 \ --conditions '[ { "MatchHeaders": { "AnyOf": [ { "Header": "Hello", "ValueGlob": "World" } ] } }, { "MatchHeaders": { "AnyOf": [ { "Header": "x-version", "ValueGlob": "beta" } ] } }, { "MatchBasePaths": { "AnyOf": [ "PetStoreShopper" ] } } ]'\ --actions '[ { "InvokeApi": { "ApiId": "a1b2c3", "Stage": "prod" } } ]' ``` 출력은 다음과 같습니다. ``` { "Actions": [ { "InvokeApi": { "ApiId": "a1b2c3", "Stage": "prod", "StripBasePath": false } } ], "Conditions": [ { "MatchHeaders": { "AnyOf": [ { "Header": "Hello", "ValueGlob": "World" } ] } }, { "MatchHeaders": { "AnyOf": [ { "Header": "x-version", "ValueGlob": "beta" } ] } }, { "MatchBasePaths": { "AnyOf": [ "PetStoreShopper" ] } } ], "Priority": 38, "RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123", "RoutingRuleId": "abc123" } ``` ------ # 라우팅 규칙을 사용하여 API 매핑 다시 만들기 라우팅 규칙을 사용하여 API 매핑을 다시 만들 수 있습니다. API 매핑을 다시 만들려면 기본 경로 제거를 켜야 합니다. 이렇게 하면 API 매핑의 동작이 유지됩니다. 자세한 내용은 [기본 경로 조건을 사용하여 기본 경로 제거](rest-api-routing-rules.md#rest-api-routing-rules-condition-path-split) 섹션을 참조하세요. 다음 자습서에서는 API 매핑 `https:// api.example.com/orders/v2/items/categories/5`을 라우팅 규칙으로 다시 만드는 방법과 API Gateway가 API로 트래픽을 전송하는 데 사용하는 라우팅 규칙 ID를 로깅하도록 액세스 로그를 업데이트하는 방법을 보여줍니다. ------ #### [ AWS Management Console ] **라우팅 모드를 ROUTING\$1RULE\$1THEN\$1API\$1MAPPING으로 설정하려면** 1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다. 1. 기본 탐색 창에서 **사용자 지정 도메인 이름**을 선택합니다. 1. 사용자 지정 도메인 이름을 선택합니다. 1. **도메인 세부 정보**에서 **편집**을 선택합니다. 1. **라우팅 모드**에서 **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**을 선택합니다. 1. **저장**을 선택합니다. 라우팅 모드를 설정한 후 라우팅 규칙을 만듭니다. **라우팅 규칙을 생성하려면** 1. **라우팅 세부 정보** 탭에서 **라우팅 규칙 추가**를 선택합니다. 1. **조건 추가**를 선택한 다음 **경로**를 선택합니다. 1. **경로**에 **orders/v2/items/categories/5**를 입력합니다. 1. **기본 경로 제거**에서 **활성**을 선택합니다. 1. **대상 API**에서 대상 API를 선택합니다. 1. **대상 스테이지**에서 대상 스테이지를 선택합니다. 1. **다음**을 선택합니다. 1. 우선순위에 우선순위를 입력합니다. 기존 API 매핑을 유지하더라도 API Gateway는 항상 새 라우팅 규칙을 사용합니다. 라우팅 규칙은 항상 API 매핑보다 우선하기 때문입니다. 1. **변경 사항 저장**을 선택합니다. 라우팅 규칙을 생성한 후 스테이지의 액세스 로그 형식을 업데이트하거나 새 로그를 생성하여 API Gateway가 라우팅 규칙을 사용하여 API로 트래픽을 전송하는지 확인합니다. **액세스 로그를 업데이트하려면** 1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다. 1. API를 선택합니다. 1. 기본 탐색 창에서 **스테이지**를 선택합니다. 1. **로그 및 추적**에서 **편집**을 선택합니다. 로그 그룹이 없는 경우 [API Gateway에서 REST API에 대한 CloudWatch 로깅 설정](set-up-logging.md) 섹션을 참조하세요. 1. 로그 형식에 **\$1context.customDomain.routingRuleIdMatched**를 추가합니다. 이 로그 그룹은 API Gateway가 API로 트래픽을 전송하는 데 사용한은 라우팅 규칙 ID를 기록합니다. 자세한 내용은 [API Gateway가 내 API로 트래픽을 어떻게 전송했는지 알 수 없음](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging) 섹션을 참조하세요. 1. **저장**을 선택합니다. 액세스 로그를 업데이트한 후 사용자 지정 도메인 이름을 간접적으로 호출합니다. 다음은 기본 경로 `orders/v2/items/categories/5`를 사용하여 사용자 지정 도메인 이름 `https://api.example.com`을 간접적으로 호출하는 curl 명령의 예입니다. ``` curl "https://api.example.com/orders/v2/items/categories/5" ``` 사용자 지정 도메인 이름을 성공적으로 간접 호출한 후 CloudWatch Logs에 `routingRuleIdMatched`가 표시되는지 확인합니다. CloudWatch Logs 콘솔을 사용하여 로그 그룹을 보는 방법을 알아보려면 [CloudWatch 콘솔에서 API Gateway 로그 이벤트 보기](view-cloudwatch-log-events-in-cloudwatch-console.md) 섹션을 참조하세요. ------ #### [ AWS CLI ] 1. 다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) 명령을 사용하여 라우팅 모드 `ROUTING_RULE_THEN_API_MAPPING`을 사용하도록 도메인 이름 `api.example.com`을 업데이트합니다. ``` aws apigatewayv2 update-domain-name \ --domain-name 'api.example.com' \ --routing-mode ROUTING_RULE_THEN_API_MAPPING ``` 1. 다음 [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html) 명령을 사용하여 API 매핑 `https://api.example.com/orders/v2/items/categories/5`를 다시 만드는 새 라우팅 규칙을 만듭니다. ``` aws apigatewayv2 create-routing-rule \ --domain-name 'api.example.com' \ --priority 50 \ --conditions '[ { "MatchBasePaths": { "AnyOf": [ "orders/v2/items/categories/5" ] } } ]' \ --actions '[ { "InvokeApi": { "ApiId": "a1b2c3", "Stage": "prod", "StripBasePath": true } } ]' ``` 1. 다음 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) 명령을 사용하여 `$context.customDomain.routingRuleIdMatched` 변수를 포함하도록 액세스 로그 형식을 업데이트합니다. 이 변수는 API Gateway가 API로 트래픽을 전송하는 데 사용한은 라우팅 규칙 ID를 기록합니다. 이 로그를 사용하여 API Gateway가 라우팅 규칙을 사용하여 API로 트래픽을 전송하는지 확인합니다. 자세한 내용은 [API Gateway가 내 API로 트래픽을 어떻게 전송했는지 알 수 없음](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging) 섹션을 참조하세요. ``` aws apigateway update-stage \ --rest-api-id a1bc2c3 \ --stage-name prod \ --patch-operations "op=replace,path=/accessLogSettings/format,value='\$context.path \$context.customDomain.routingRuleIdMatched \$context.requestId \$context.extendedRequestId'" ``` 로그 그룹이 없는 경우 [API Gateway에서 REST API에 대한 CloudWatch 로깅 설정](set-up-logging.md) 섹션을 참조하세요. 1. 다음 예제 curl 명령을 사용하여 기본 경로 `orders/v2/items/categories/5`를 사용하여 사용자 지정 도메인 이름을 간접적으로 호출합니다. ``` curl "https://api.example.com/orders/v2/items/categories/5 ``` 1. 다음 [filter-log-events](https://docs.aws.amazon.com/cli/latest/reference/logs/filter-log-events.html) 명령을 사용하여 라우팅 규칙 ID `abc123`이 포함된 로그 그룹 `access-log-group-orders`에서 로그 이벤트를 가져옵니다. ``` aws logs filter-log-events --log-group-name access-log-group-orders --filter-pattern abc123 ``` 이렇게 하면 API Gateway가 라우팅 규칙을 사용하여 API로 트래픽을 전송하는지 확인할 수 있습니다. ------ # 라우팅 규칙 문제 해결 다음 문제 해결 지침은 라우팅 규칙에 대한 리소스 문제를 해결하는 데 도움이 될 수 있습니다. ## API Gateway가 내 API로 트래픽을 어떻게 전송했는지 알 수 없음 REST API 스테이지에 대한 액세스 로그를 사용하여 라우팅 규칙을 로깅하고 문제를 해결할 수 있습니다. `$context.customDomain.routingRuleIdMatched` 변수를 사용하여 API Gateway가 API로 트래픽을 전송하는 데 사용한 라우팅 규칙 ID를 볼 수 있습니다. API Gateway가 API로 트래픽을 전송하는 데 사용한 API 매핑을 보려면 `$context.customDomain.basePathMatched` 변수를 사용합니다. 라우팅 규칙을 로깅하려면 계정에 [적합한 CloudWatch Logs 역할](set-up-logging.md#set-up-access-logging-permissions) ARN을 구성하고 로그 그룹을 만들어야 합니다. 다음 예제 액세스 로그 그룹은 라우팅 규칙 및 API 매핑 문제 해결과 관련된 정보를 검색할 수 있습니다. API Gateway는 사용한 라우팅 메커니즘의 컨텍스트 변수만 채웁니다. 그렇지 않으면 컨텍스트 변수는 `-`입니다. ------ #### [ CLF ] ``` $context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.requestId $context.extendedRequestId ``` ------ #### [ JSON ] ``` {"requestPath": "$context.path", "routingRuleId" : "$context.customDomain.routingRuleIdMatched", "API mapping" : "$context.customDomain.basePathMatched", "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId"} ``` ------ #### [ XML ] ``` $context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.extendedRequestId ``` ------ #### [ CSV ] ``` $context.path,$context.customDomain.routingRuleIdMatched,$context.customDomain.basePathMatched,$context.requestId,$context.extendedRequestId ``` ------ 또한 사용자 지정 도메인 이름의 라우팅 모드를 확인하는 것이 좋습니다. 자세한 내용은 [사용자 지정 도메인 이름의 라우팅 모드 설정](set-routing-mode.md) 섹션을 참조하세요. ## 사용자 지정 도메인 이름에서 라우팅 규칙을 활성화할 수 없음 API Gateway에서 다음 오류가 발생할 수 있습니다. ``` Your account doesn’t have permission to use RoutingRules. This might be caused by an IAM policy in your account with a deny statement on BasePathMapping or ApiMapping. To grant permission for this account to use RoutingRules, use the UpdateAccount API. This will impact any existing IAM policies that deny access to BasePathMapping or ApiMapping. See API Gateway documentation for further details. ``` [BasePathMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagement.html#amazonapigatewaymanagement-resources-for-iam-policies) 또는 [ApiMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagementv2.html#amazonapigatewaymanagementv2-resources-for-iam-policies)에 대한 액세스를 거부하는 IAM 정책이 현재 또는 과거에 있었던 경우 오류가 발생합니다. 사용자 지정 도메인 이름에 대해 라우팅 규칙을 활성화하면 정책이 `BasePathMapping` 또는 `ApiMapping`에 대한 액세스를 계속 거부하지만 동일한 정책을 사용하여 `RoutingRule`에 액세스할 수 있습니다. 이렇게 하면 사용자가 사용자 지정 도메인 이름의 라우팅 동작을 변경할 수 있습니다. 예를 들어 다음과 같은 정책이 있는 경우: ``` { "Sid": "DenyCreatingApiMappings", "Effect": "Deny", "Action": "apigateway:POST", "Resource": [ "arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings" ] } ``` `example.com`에 대한 라우팅 규칙을 활성화하면 이 정책은 `ApiMapping` 만들기에 대한 액세스를 계속 거부하지만 `RoutingRule` 만들기에 대한 액세스는 거부하지 않습니다. 계정의 IAM 정책을 감사하는 것이 좋습니다. 다음 예제 정책은 `ApiMapping`, `BasePathMapping` 및 `RoutingRule` 만들기에 대한 액세스를 거부합니다. ``` { "Sid": "DenyCreatingBasePathMappingsApiMappings", "Effect": "Deny", "Action": "apigateway:POST", "Resource": [ "arn:aws:apigateway:us-west-2::/domainnames/example.com/basepathmappings", "arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings" ] }, { "Sid": "DenyCreatingRoutingRules", "Effect": "Deny", "Action": "apigateway:CreateRoutingRule", "Resource": [ "arn:aws:apigateway:us-west-2:111122223333:/domainnames/example.com/routingrules/*" ] } ``` 모든 정책이 업데이트되었는지 확인한 후 API의 계정 수준 설정을 업데이트하여 리전에 대한 라우팅 규칙을 활성화할 수 있습니다. 다음 [update-account](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html) 명령을 사용하여 특정 리전의 API의 계정 수준 설정을 업데이트합니다. ``` aws apigateway update-account --patch-operations 'op=remove,path=/features,value=BlockedForRoutingRules' --region us-west-2 ``` API의 계정 수준 설정을 업데이트한 후 사용자 지정 도메인 이름의 라우팅 모드를 변경할 수 있습니다. IAM 정책을 계속 사용하여 `RoutingRules`, `ApiMapping` 또는 `BasePathMapping`에 대한 액세스를 거부할 수도 있습니다.