# API Gateway의 퍼블릭 REST API에 대한 사용자 지정 도메인 이름
*사용자 지정 도메인 이름*은 API 사용자에게 제공할 수 있는 더 간단하고 직관적인 URL입니다.
API를 배포한 후 사용자 및 사용자 고객은 다음 형식의 기본 URL을 사용하여 API를 호출할 수 있습니다.
```
https://api-id.execute-api.region.amazonaws.com/stage
```
여기서 *api-id*는 API Gateway에서 생성되고 *region*은 AWS 리전이며 *stage*는 API를 배포할 때 사용자가 지정합니다.
URL의 호스트 이름 부분(즉, `api-id.execute-api.region.amazonaws.com`)은 API 엔드포인트를 가리킵니다. 기본 API 엔드포인트는 임의로 생성되므로 기억하기가 어려우며 사용자 친화적이지 않습니다.
사용자 지정 도메인 이름을 사용하면 API의 호스트 이름을 설정하고 기본 경로(예: `myservice`)를 선택하여 대체 URL을 API에 매핑할 수 있습니다. 예를 들어, 더 사용자 친화적인 API 기본 URL은 다음과 같습니다.
```
https://api.example.com/myservice
```
**참고**
프라이빗 API의 사용자 지정 도메인 이름에 대한 자세한 내용은 [API Gateway의 프라이빗 API에 대한 사용자 지정 도메인 이름](apigateway-private-custom-domains.md) 섹션을 참조하세요.
## 고려 사항
다음 고려 사항은 사용자 지정 도메인 이름 사용에 영향을 미칠 수 있습니다.
+ API의 기본 엔드포인트를 비활성화할 수 있습니다. 클라이언트는 여전히 기본 엔드포인트에 연결할 수 있지만 `403 Forbidden` 상태 코드를 받게 됩니다.
+ 리전 사용자 지정 도메인 이름은 REST API 및 HTTP API와 연결될 수 있습니다. [API Gateway 버전 2 API](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/api-reference.html)를 사용하여 REST API에 대한 리전 사용자 지정 도메인 이름을 생성하고 관리할 수 있습니다.
+ 사용자 지정 도메인 이름은 모든 AWS 계정에 걸쳐 한 리전 내에서 고유해야 합니다.
+ 엣지 최적화 엔드포인트와 리전 엔드포인트 간에 사용자 지정 도메인 이름을 마이그레이션할 수 있지만 퍼블릭 사용자 지정 도메인을 프라이빗 사용자 지정 도메인 이름으로 마이그레이션할 수는 없습니다.
+ DNS 공급자의 리소스 레코드를 생성하거나 업데이트하여 API 엔드포인트에 매핑해야 합니다. 이렇게 매핑하지 않으면 사용자 지정 도메인 이름이 목적지인 API 요청은 API Gateway에 도달할 수 없습니다.
+ 와일드카드 인증서를 사용하면 기본 할당량을 초과하지 않고 거의 무제한 수의 도메인 이름을 지원할 수 있습니다. 자세한 내용은 [와일드카드 사용자 정의 도메인 이름](#wildcard-custom-domain-names) 섹션을 참조하세요.
+ 사용자 지정 도메인에 대한 보안 정책을 선택할 수 있습니다. 자세한 내용은 [API Gateway에서 사용자 지정 도메인에 대한 보안 정책 선택](apigateway-custom-domain-tls-version.md) 섹션을 참조하세요.
+ 여러 수준으로 API 매핑을 구성하려면 리전 사용자 지정 도메인 이름과 TLS 1.2 보안 정책을 사용해야 합니다.
## 사용자 지정 도메인 이름에 대한 사전 조건
퍼블릭 또는 프라이빗 사용자 지정 도메인 이름을 생성하기 위한 사전 요구 사항은 다음과 같습니다. 프라이빗 API의 사용자 지정 도메인 이름에 대한 자세한 내용은 [API Gateway의 프라이빗 API에 대한 사용자 지정 도메인 이름](apigateway-private-custom-domains.md) 섹션을 참조하세요.
### 도메인 이름 등록
API에 대한 사용자 지정 도메인 이름을 설정하려면 등록된 인터넷 도메인 이름이 있어야 합니다. [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/)를 사용하거나 사용자가 선택한 서드 파티 도메인 등록자를 사용하여 인터넷 도메인을 등록할 수 있습니다. 사용자 지정 도메인 이름은 하위 도메인의 이름이거나 등록된 인터넷 도메인의 루트 도메인("zone apex"라고도 함) 이름일 수 있습니다.
도메인 이름은 [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) 사양을 따라야 하며 라벨당 최대 63옥텟, 총 255옥텝을 포함할 수 있습니다.
### 사용자 지정 도메인 이름에 대한 인증서를 지정합니다.
API에 대한 사용자 지정 도메인 이름을 설정하기 전에 ACM에서 SSL/TLS 인증서를 준비해야 합니다. 사용자 지정 도메인 이름을 생성하는 AWS 리전에서 ACM을 사용할 수 없는 경우 해당 리전의 API Gateway로 인증서를 가져와야 합니다.
SSL/TLS 인증서를 가져오려면 PEM 형식의 SSL/TLS 인증서 본문, 해당하는 프라이빗 키 및 사용자 지정 도메인 이름에 대한 인증서 체인을 제공해야 합니다.
ACM에 저장된 각 인증서는 ARN으로 식별됩니다. ACM에서 발행한 인증서를 사용하면 프라이빗 키 같은 민감한 인증서 세부 정보의 공개를 걱정할 필요가 없습니다. 해당 ARN을 참조하기만 하면 도메인 이름에 대해 AWS에서 관리하는 인증서를 사용할 수 있습니다.
애플리케이션에서 ACM 인증서를 고정하기 위해 인증서 고정(SSL 고정)을 사용하는 경우, AWS가 인증서를 갱신한 후 애플리케이션이 도메인에 연결하지 못하게 될 수 있습니다. 자세한 내용은 *AWS Certificate Manager 사용 설명서*의 [인증서 고정 문제](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html)를 참조하세요.
## 와일드카드 사용자 정의 도메인 이름
와일드카드 사용자 지정 도메인 이름을 사용하면 [기본 할당량](limits.md)을 초과하지 않고 거의 무제한 수의 도메인 이름을 지원할 수 있습니다. 예를 들어 각 고객에게 고유한 도메인 이름인 `customername.example.com`을 제공할 수 있습니다.
와일드카드 사용자 지정 도메인 이름을 생성하려면, 와일드카드(`*`)를 루트 도메인의 가능한 모든 하위 도메인을 나타내는 사용자 지정 도메인의 첫 번째 하위 도메인으로 지정할 수 있습니다.
예를 들어 `*.example.com`을 와일드카드 사용자 지정 도메인 이름으로 사용하면 `a.example.com`, `b.example.com` 및 `c.example.com` 등이 하위 도메인이 됩니다. 와일드카드 사용자 지정 도메인 이름을 만들면 모든 하위 도메인이 와일드카드 도메인 이름의 라우팅 모드로 라우팅됩니다. 하위 도메인을 다른 API로 라우팅하려면 다음 중 하나를 수행할 수 있습니다.
+ 라우팅 규칙을 사용하여 수신 요청을 `*.example.com`으로 라우팅한 후 `Host` 헤더를 사용하여 다른 대상 REST API로 다시 라우팅합니다. 자세한 내용은 [예제 4: 와일드카드 도메인 이름에 대한 라우팅 규칙](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-for-wildcard-domains) 섹션을 참조하세요.
+ 다른 엔드포인트로 라우팅하려는 모든 하위 도메인의 도메인 이름을 만듭니다. 단일 AWS 계정에서 `*.example.com` 및 `a.example.com`을 모두 가질 수 있습니다.
`$context.domainName` 및 `$context.domainPrefix` 컨텍스트 변수를 사용하여 클라이언트가 API를 호출하는 데 사용한 도메인 이름을 확인할 수 있습니다. 컨텍스트 변수에 대해 자세히 알아보려면 [API Gateway의 데이터 변환을 위한 변수](api-gateway-mapping-template-reference.md) 단원을 참조하세요.
와일드카드 사용자 지정 도메인 이름을 생성하려면 DNS 또는 이메일 검증 방법을 사용하여 검증한 ACM에서 발급한 인증서를 제공해야 합니다.
**참고**
다른 AWS 계정에서 와일드카드 사용자 지정 도메인 이름과 충돌하는 사용자 지정 도메인 이름을 만든 경우에는 와일드카드 사용자 지정 도메인 이름을 생성할 수 없습니다. 예를 들어 계정 A에서 `a.example.com`가 생성된 경우, 계정 B는 와일드카드 사용자 지정 도메인 이름 `*.example.com`을 생성할 수 없습니다.
계정 A와 계정 B가 한 소유자를 공유하는 경우 [AWS 지원 센터](https://console.aws.amazon.com/support/home#/)에 문의하여 예외를 요청할 수 있습니다.
## 사용자 지정 도메인 이름에 대한 다음 단계
사용자 지정 도메인 이름에 대한 다음 단계는 다음과 같습니다.
**다음 단계**
+ SSL/TLS 인증서를 설정하는 방법을 알아보려면 [AWS Certificate Manager에서 인증서 준비](how-to-specify-certificate-for-custom-domain-name.md) 단원을 참조하세요.
+ 리전 사용자 지정 도메인 이름을 생성하는 방법을 알아보려면 [API Gateway에서 리전 사용자 지정 도메인 이름 설정](apigateway-regional-api-custom-domain-create.md) 단원을 참조하세요.
+ 엣지 최적화 사용자 지정 도메인 이름을 생성하는 방법을 알아보려면 [API Gateway API에서 엣지 최적화 사용자 지정 도메인 이름 설정](how-to-edge-optimized-custom-domain-name.md) 단원을 참조하세요.
+ 리전 사용자 지정 도메인 이름과 엣지 최적화 사용자 지정 도메인 이름 간에 마이그레이션하는 방법을 알아보려면 [API Gateway에서 사용자 지정 도메인 이름을 다른 API 엔드포인트 유형으로 마이그레이션](apigateway-regional-api-custom-domain-migrate.md) 단원을 참조하세요.
+ API 스테이지를 사용자 지정 도메인 이름에 연결하는 방법을 알아보려면 [API Gateway에서 사용자 지정 도메인 이름을 통해 API로 트래픽을 전송합니다.](rest-api-routing-mode.md) 단원을 참조하세요.
+ 사용자 지정 도메인 이름에 대한 보안 정책을 선택하는 방법을 알아보려면 [API Gateway에서 사용자 지정 도메인에 대한 보안 정책 선택](apigateway-custom-domain-tls-version.md) 단원을 참조하세요.
+ 사용자 지정 도메인 이름의 기본 엔드포인트를 비활성화하는 방법을 알아보려면 [REST API의 기본 엔드포인트 비활성화](rest-api-disable-default-endpoint.md) 단원을 참조하세요.
+ Route 53 상태 확인을 사용하여 API Gateway API의 DNS 장애 조치를 제어하는 방법을 알아보려면 [API Gateway API에 DNS 장애 조치에 대한 사용자 지정 상태 확인 구성](dns-failover.md) 단원을 참조하세요.
사용자 지정 도메인 이름을 처음 생성하는 경우 먼저 [AWS Certificate Manager에서 인증서 준비](how-to-specify-certificate-for-custom-domain-name.md)으로 시작하여 인증서를 지정한 다음 [API Gateway에서 리전 사용자 지정 도메인 이름 설정](apigateway-regional-api-custom-domain-create.md)로 리전 사용자 지정 도메인 이름을 생성하는 것이 좋습니다.
# AWS Certificate Manager에서 인증서 준비
API에 대한 사용자 지정 도메인 이름을 설정하기 전에 에서 SSL/TLS 인증서를 준비해야 합니다AWS Certificate Manager 자세한 내용은 [AWS Certificate Manager 사용 설명서](https://docs.aws.amazon.com/acm/latest/userguide/)를 참조하세요.
## 고려 사항
다음은 SSL/TLS 인증서에 대한 고려 사항입니다.
+ 엣지 최적화 사용자 지정 도메인 이름을 생성한 경우 API Gateway는 CloudFront를 활용하여 사용자 지정 도메인 이름에 대한 인증서를 지원합니다. 그렇기 때문에 사용자 지정 도메인 이름의 SSL/TLS 인증서에 대한 요구 사항과 제약 조건이 [CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html)에서 지정됩니다. 예를 들어, 퍼블릭 키의 최대 크기는 2048이고 프라이빗 키 크기는 1024, 2048 및 4096입니다. 퍼블릭 키 크기는 이용하는 인증 기관에서 정합니다. 이용하는 인증 기관에 기본 설정 길이와 다른 크기의 키를 반환하도록 요청합니다. 자세한 내용은 [객체에 대한 액세스 보안](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https.html) 및 [서명된 URL 및 서명된 쿠키 생성](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html)을 참조하세요.
+ 리전 사용자 지정 도메인 이름을 생성하는 경우 퍼블릭 키의 최대 크기는 2048입니다.
+ 리전 사용자 지정 도메인 이름이 포함된 ACM 인증서를 사용하려면 API와 동일한 리전에서 인증서를 요청하거나 가져와야 합니다. 인증서는 사용자 지정 도메인 이름을 포함해야 합니다.
+ 엣지 최적화 사용자 지정 도메인 이름이 포함된 ACM 인증서를 사용하려면 미국 동부(버지니아 북부) – `us-east-1` 리전에서 인증서를 요청하거나 가져와야 합니다.
+ 등록된 도메인 이름(예:`example.com`)이 있어야 합니다. [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) 또는 서드 파티 인증 도메인 등록자를 사용할 수 있습니다. 그러한 등록 대행자의 목록은 ICANN 웹 사이트에서 [Accredited Registrar Directory](https://www.icann.org/en/accredited-registrars)를 참조하세요.
## SSL/TLS 인증서를 생성하거나 ACM으로 가져오려면
다음 절차는 도메인 이름에 대한 SSL/TLS 인증서를 생성하거나 가져오는 방법을 보여 줍니다.
------
#### [ To request a certificate provided by ACM for a domain name ]
1. [AWS Certificate Manager 콘솔](https://console.aws.amazon.com/acm)에 로그인합니다.
1. **인증서 요청**을 선택합니다.
1. **인증서 유형**에서 **퍼블릭 인증서 요청**을 선택합니다.
1. **다음**을 선택합니다.
1. **정규화된 도메인 이름**에 API에 대한 사용자 지정 도메인 이름(예: `api.example.com`)을 입력합니다.
1. 필요에 따라 **이 인증서에 다른 이름 추가**를 선택할 수도 있습니다.
1. **검증 방법**에서 도메인 소유권을 검증하는 방법을 선택합니다.
1. **키 알고리즘**에서 암호화 알고리즘을 선택합니다.
1. **요청**을 선택합니다.
1. 요청이 유효하려면 ACM이 인증서를 발급하기 전에 인터넷 도메인의 등록 소유자가 요청에 동의해야 합니다. Route 53를 사용하여 퍼블릭 DNS 레코드를 관리하는 경우 ACM 콘솔을 통해 레코드를 직접 업데이트할 수 있습니다.
------
#### [ To import into ACM a certificate for a domain name ]
1. 인증 기관으로부터 여러분의 사용자 지정 도메인 이름에 대한 PEM 인코딩 SSL/TLS 인증서를 취득합니다. 이러한 CA의 일부 목록은 [Mozilla 포함 CA 목록](https://ccadb.my.salesforce-sites.com/mozilla/IncludedCACertificateReport)을 참조하세요.
1. OpenSSL 웹 사이트에 있는 [OpenSSL](https://www.openssl.org) 도구 키트를 사용하여 인증서의 프라이빗 키를 생성하고 파일에 생성된 결과물을 저장합니다.
```
openssl genrsa -out private-key-file 2048
```
1. OpenSSL을 사용하여 이전에 생성된 프라이빗 키로 인증서 서명 요청(CSR) 생성:
```
openssl req -new -sha256 -key private-key-file -out CSR-file
```
1. CSR을 인증 기관에 제출하고 그 결과 얻은 인증서를 저장합니다.
1. 인증 기관으로부터 인증서 체인을 다운로드합니다.
**참고**
다른 방법으로 프라이빗 키를 얻고 키가 암호화된 경우, 사용자 지정 도메인 이름을 설정하기 위해 키를 API Gateway에 제출하기 전에 다음 명령을 사용하여 키를 암호 해독할 수 있습니다.
```
openssl pkcs8 -topk8 -inform pem -in MyEncryptedKey.pem -outform pem -nocrypt -out MyDecryptedKey.pem
```
1. 인증서를 AWS Certificate Manager로 업로드합니다.
1. [AWS Certificate Manager 콘솔](https://console.aws.amazon.com/acm)에 로그인합니다.
1. [**Import a certificate**]을 선택합니다.
1. **인증서 본문**에 인증 기관으로부터 받은 PEM 형식의 서버 인증서 본문을 입력합니다. 다음은 그와 같은 인증서의 축약된 예입니다.
```
-----BEGIN CERTIFICATE-----
EXAMPLECA+KgAwIBAgIQJ1XxJ8Pl++gOfQtj0IBoqDANBgkqhkiG9w0BAQUFADBB
...
az8Cg1aicxLBQ7EaWIhhgEXAMPLE
-----END CERTIFICATE-----
```
1. **인증서 프라이빗 키**에 PEM 형식 인증서의 프라이빗 키를 입력합니다. 다음은 그와 같은 키의 축약된 예입니다.
```
-----BEGIN RSA PRIVATE KEY-----
EXAMPLEBAAKCAQEA2Qb3LDHD7StY7Wj6U2/opV6Xu37qUCCkeDWhwpZMYJ9/nETO
...
1qGvJ3u04vdnzaYN5WoyN5LFckrlA71+CszD1CGSqbVDWEXAMPLE
-----END RSA PRIVATE KEY-----
```
1. **인증서 체인**에 PEM 형식의 중간 인증서와 루트 인증서(선택 사항)를 빈 줄 없이 서로 이어서 입력합니다. 루트 인증서를 포함하는 경우 인증서 체인은 중간 인증서로 시작하고 루트 인증서를 끝나야 한다. 인증 기관에서 제공한 중간 인증서를 사용합니다. 신뢰 경로 체인에 없는 중간 인증서를 포함시키지 마세요. 다음은 축약된 예입니다.
```
-----BEGIN CERTIFICATE-----
EXAMPLECA4ugAwIBAgIQWrYdrB5NogYUx1U9Pamy3DANBgkqhkiG9w0BAQUFADCB
...
8/ifBlIK3se2e4/hEfcEejX/arxbx1BJCHBvlEPNnsdw8EXAMPLE
-----END CERTIFICATE-----
```
다음은 또 다른 예입니다.
```
-----BEGIN CERTIFICATE-----
Intermediate certificate 2
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Intermediate certificate 1
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Optional: Root certificate
-----END CERTIFICATE-----
```
1. **다음**을 선택한 후 다시 **다음**을 선택합니다.
------
인증서를 성공적으로 생성하거나 가져온 후에 인증서 ARN을 기록해 둡니다. 사용자 지정 도메인 이름을 설정할 때 필요합니다.
# API Gateway에서 리전 사용자 지정 도메인 이름 설정
리전 사용자 지정 도메인 이름을 사용하여 사용자 친화적인 API 기본 URL을 생성합니다. 리전 사용자 지정 도메인 이름을 사용하면 HTTP 및 REST API 스테이지를 동일한 사용자 지정 도메인 이름에 매핑하고 상호 TLS 인증을 사용할 수 있습니다.
## 고려 사항
다음은 리전 사용자 지정 도메인 이름에 대한 고려 사항입니다.
+ 리전별 ACM 인증서를 제공해야 합니다. 인증서는 API와 동일한 리전에 있어야 합니다. 사용자 지정 도메인 이름 인증서 생성 또는 업로드에 대한 자세한 내용은 [AWS Certificate Manager에서 인증서 준비](how-to-specify-certificate-for-custom-domain-name.md)를 참조하세요.
+ ACM 인증서로 리전 사용자 지정 도메인 이름을 생성(또는 마이그레이션)하면 API Gateway는 해당 계정에 서비스 연결 역할을 생성합니다. 서비스 연결 역할은 ACM 인증서를 해당 리전 엔드포인트에 연결하는 데 필요합니다. 그 역할의 이름은 **AWSServiceRoleForAPIGateway**이고 이 역할에는 **APIGatewayServiceRolePolicy** 관리형 정책이 연결됩니다. 서비스 연결 역할을 사용하는 방법에 대한 자세한 내용은 [서비스 연결 역할 사용](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)을 참조하세요.
+ 리전 사용자 지정 도메인 이름을 생성한 후에는 DNS 레코드를 생성하여 사용자 지정 도메인 이름을 리전 도메인에 연결해야 합니다. 이렇게 하면 목적지가 사용자 지정 도메인 이름인 트래픽이 API의 리전 호스트 이름으로 라우팅됩니다.
DNS 레코드는 CNAME 또는 A 별칭 레코드일 수 있습니다. Route 53을 DNS 공급자로 사용하는 경우 A 별칭 레코드를 생성합니다. 타사 DNS 공급자를 사용하는 경우 CNAME 레코드를 사용합니다. CNAME 레코드를 사용하고 프라이빗 API에 대해 프라이빗 DNS가 활성화된 API Gateway 인터페이스 VPC 엔드포인트를 생성하는 경우 프라이빗 API를 호스팅하는 VPC 내에서 사용자 지정 도메인 이름을 확인할 수 없습니다.
## 리전 사용자 지정 도메인 이름 생성
다음 절차는 리전 사용자 지정 도메인 이름을 생성하는 방법을 보여 줍니다. 이 절차를 완료한 후 API의 스테이지를 사용자 지정 도메인 이름에 라우팅하는 라우팅 규칙을 만듭니다.
------
#### [ AWS Management Console ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 기본 탐색 창에서 **사용자 지정 도메인 이름**을 선택합니다.
1. **생성**을 선택합니다.
1. **도메인 이름**에 도메인 이름을 입력합니다.
1. **라우팅 모드**에서 **라우팅 규칙만**을 선택합니다.
이 라우팅 모드에서는 라우팅 규칙을 사용하여 사용자 지정 도메인 이름의 트래픽을 API로 전송할 수만 있습니다. 자세한 내용은 [API Gateway에서 사용자 지정 도메인 이름을 통해 API로 트래픽을 전송합니다.](rest-api-routing-mode.md) 섹션을 참조하세요.
1. **최소 TLS 버전**에서 버전을 선택합니다.
1. **엔드포인트 구성** 아래의 **API 엔드포인트 유형**에서 **리전**을 선택합니다.
1. ACM 인증서를 선택합니다. 인증서는 API와 동일한 리전에 있어야 합니다.
1. **생성(Create)**을 선택합니다.
------
#### [ AWS CLI ]
다음 [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html) 명령은 사용자 지정 도메인 이름을 생성합니다.
```
aws apigatewayv2 create-domain-name \
--domain-name 'regional.example.com' \
--domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
--routing-mode ROUTING_RULE_ONLY
```
출력은 다음과 같습니다.
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "regional.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"SecurityPolicy": "TLS_1_2"
}
"RoutingMode": "ROUTING_RULE_ONLY"
]
}
```
`DomainNameConfigurations` 속성 값은 리전 API의 호스트 이름을 반환합니다. DNS 레코드를 생성하여 사용자 지정 도메인 이름이 이 리전 도메인 이름을 가리키도록 해야 합니다. 이렇게 하면 목적지가 사용자 지정 도메인 이름인 트래픽이 이 리전 API의 호스트 이름으로 라우팅됩니다.
------
## 리전 사용자 지정 도메인 이름에 대한 라우팅 규칙 만들기
사용자 지정 도메인 이름을 만든 후 사용자 지정 도메인 이름에서 API로 트래픽이 라우팅되는 방법을 구성합니다. 라우팅 모드를 `ROUTING_RULE_ONLY`로 설정했으므로 라우팅 규칙을 사용하여 수신 요청을 사용자 지정 도메인 이름으로 라우팅한 다음, API로 다시 라우팅합니다.
이 예제에서는 모든 수신 요청을 사용자 지정 도메인 이름으로 라우팅한 다음 API의 한 스테이지로 다시 라우팅하는 catch-all 규칙을 만듭니다. 다른 헤더 및 경로 조건에 따라 라우팅 규칙을 구성할 수도 있습니다. 자세한 내용은 [API 스테이지를 REST API의 사용자 지정 도메인 이름에 연결하는 라우팅 규칙](rest-api-routing-rules.md) 섹션을 참조하세요.
------
#### [ AWS Management Console ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 사용자 지정 도메인 이름을 선택합니다.
1. **라우팅 세부 정보** 탭에서 **라우팅 규칙 추가**를 선택합니다.
1. **새 조건 추가**를 선택하여 새 조건을 추가합니다.
1. 이 규칙을 조건 없이 유지합니다. 이렇게 하면 모든 요청이 사용자 지정 도메인 이름으로 라우팅된 다음 대상 API 및 대상 스테이지로 다시 라우팅됩니다.
1. **작업**에서 드롭다운을 사용하여 대상 API와 대상 스테이지를 선택합니다.
1. **다음**을 선택합니다.
1. 우선순위 필드에 **100**을 입력합니다.
API Gateway는 규칙을 가장 낮은 값에서 가장 높은 값에 이르기까지 우선순위에 따라 평가합니다. 이는 catch-all 규칙이므로 사용자가 생성하는 추가 규칙을 API Gateway가 먼저 일치시킬 수 있도록 높은 우선순위를 사용합니다.
1. **라우팅 규칙 생성**을 선택합니다.
------
#### [ AWS CLI ]
다음 `create-routing-rule` 명령은 catch-all 라우팅 규칙을 만듭니다.
```
aws apigatewayv2 create-routing-rule \
--domain-name 'regional.example.com' \
--priority 100 \
--conditions \
--actions '[{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}]'
```
------
언제든지 라우팅 모드를 변경하고 새 규칙을 만들 수 있습니다. 자세한 내용은 [API Gateway에서 사용자 지정 도메인 이름을 통해 API로 트래픽을 전송합니다.](rest-api-routing-mode.md) 섹션을 참조하세요.
## 리전 사용자 지정 도메인 이름에 대한 DNS 레코드 생성
사용자 지정 도메인 이름을 생성하고 기본 경로 매핑을 생성한 후 DNS 레코드를 생성하여 사용자 지정 도메인 이름을 새로 만든 리전 도메인 이름에 연결합니다.
------
#### [ AWS Management Console ]
AWS Management Console을 사용하려면 Route 53 설명서에 따라 [트래픽을 API Gateway로 라우팅하도록 Route 53를 구성](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)합니다.
------
#### [ AWS CLI ]
리전 사용자 지정 도메인 이름을 지정된 호스팅 영역 ID의 호스트 이름으로 매핑하도록 DNS 레코드를 구성하려면 먼저 리전 도메인 이름에 대해 DNS 레코드를 설정하기 위한 구성을 포함하는 JSON 파일을 생성합니다.
다음 `setup-dns-record.json`에서는 DNS `A` 레코드를 생성하여 사용자 지정 도메인 이름을 생성하는 과정에서 프로비저닝된 리전 호스트 이름(`d-numh1z56v6.execute-api.us-west-2.amazonaws.com`)에 리전 사용자 지정 도메인 이름(`regional.example.com`)을 매핑하는 방법을 보여 줍니다. `DNSName`의 `HostedZoneId` 및 `AliasTarget` 속성은 사용자 지정 도메인 이름의 `regionalDomainName` 및 `regionalHostedZoneId` 값을 가져올 수 있습니다. 또한 [Amazon API Gateway 엔드포인트 및 할당량](https://docs.aws.amazon.com/general/latest/gr/apigateway.html)에서 리전 Route 53 호스팅 영역 ID를 가져올 수 있습니다.
```
{
"Changes": [
{
"Action": "CREATE",
"ResourceRecordSet": {
"Name": "regional.example.com",
"Type": "A",
"AliasTarget": {
"DNSName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"EvaluateTargetHealth": false
}
}
}
]
}
```
다음 [change-resource-record-sets](https://docs.aws.amazon.com/cli/latest/reference/route53/change-resource-record-sets.html) 명령은 리전 사용자 지정 도메인 이름에 대한 DNS 레코드를 생성합니다.
```
aws route53 change-resource-record-sets \
--hosted-zone-id Z2OJLYMUO9EFXC \
--change-batch file://path/to/your/setup-dns-record.json
```
`hosted-zone-id`를 계정에 설정된 DNS 레코드의 Route 53 호스팅 영역 ID로 교체합니다. `change-batch` 파라미터 값은 폴더(*path/to/your*)의 JSON 파일(*setup-dns-record.json*)을 가리킵니다.
------
# API Gateway API에서 엣지 최적화 사용자 지정 도메인 이름 설정
엣지 최적화 API에 대한 사용자 지정 도메인 이름을 생성하면 API Gateway는 CloudFront 배포와 DNS 레코드를 설정하여 API 도메인 이름을 CloudFront 배포 도메인 이름에 매핑합니다. 그러면 API에 대한 요청은 매핑된 CloudFront 배포를 통해 API Gateway로 라우팅됩니다. 이 매핑은 매핑된 CloudFront 배포를 통해 API Gateway에 라우팅될 사용자 지정 도메인 이름에 바인딩된 API 요청에 사용됩니다.
## 고려 사항
다음은 엣지 최적화 사용자 지정 도메인 이름에 대한 고려 사항입니다.
+ 엣지 최적화 사용자 지정 도메인 이름을 설정하거나 해당 인증서를 업데이트하려면 CloudFront 배포를 업데이트할 수 있는 권한이 있어야 합니다.
CloudFront 배포를 업데이트하려면 다음 권한이 필요합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowCloudFrontUpdateDistribution",
"Effect": "Allow",
"Action": [
"cloudfront:updateDistribution"
],
"Resource": [
"*"
]
}
]
}
```
------
+ 미국 동부(버지니아 북부) – `us-east-1` 리전에서 엣지 최적화 사용자 지정 도메인 이름에 대한 인증서를 요청하거나 가져와야 합니다.
+ API Gateway가 생성한 CloudFront 배포는 API Gateway와 연계된 리전별 계정이 소유합니다. CloudTrail에서 이러한 CloudFront 배포를 생성하고 업데이트하는 작업을 추적할 때는 이 API Gateway 계정 ID를 사용해야 합니다. 자세한 내용은 [CloudTrail에서 사용자 지정 도메인 이름 생성 로그](#how-to-custom-domain-log-cloudfront-distribution-update-in-cloudtrail) 섹션을 참조하세요.
+ API Gateway는 CloudFront 배포에서 SNI(Server Name Indication)를 활용하여 엣지 최적화 사용자 지정 도메인 이름을 지원합니다. 필요한 인증서 형식 및 인증서 키 길이의 최대 크기를 포함하여 CloudFront 배포에서 사용자 지정 도메인 이름을 사용하는 방법에 대한 자세한 내용은 Amazon CloudFront 개발자 안내서**의 [대체 도메인 이름 및 HTTPS 사용](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https-alternate-domain-names.html)을 참조하세요.
+ 엣지 최적화 사용자 지정 도메인 이름은 사용할 수 있을 때까지 약 40분이 소요됩니다.
+ 엣지 최적화 사용자 지정 도메인 이름을 생성한 후에는 사용자 지정 도메인 이름을 CloudFront 배포 이름에 매핑하는 DNS 레코드를 생성해야 합니다.
## 엣지 최적화 사용자 지정 도메인 이름 생성
다음 절차에서는 API에 대한 엣지 최적화 사용자 지정 도메인 이름을 생성하는 방법을 설명합니다.
------
#### [ AWS Management Console ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 기본 탐색 창에서 **사용자 지정 도메인 이름**을 선택합니다.
1. **도메인 이름 추가**를 선택합니다.
1. **도메인 이름(Domain name)**에 도메인 이름을 입력합니다.
1. **라우팅 모드**에서 **API\$1MAPPING\$1ONLY**를 선택합니다.
1. **API 엔드포인트 유형**에서 **엣지 최적화**를 선택합니다.
1. 최소 TLS 버전을 선택합니다.
1. ACM 인증서를 선택합니다.
1. **도메인 이름 추가**를 선택합니다.
------
#### [ REST API ]
1. [domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html)를 호출하여 사용자 지정 도메인 이름과 AWS Certificate Manager에 저장되는 인증서의 ARN을 지정합니다.
성공적인 API 호출은 페이로드에 인증서 ARN뿐 아니라 연결된 CloudFront 배포 이름을 포함하는 `201 Created` 응답을 반환합니다.
1. 출력에 표시된 CloudFront 배포 도메인 이름을 적어 둡니다. 다음 단계인 DNS에서 사용자 지정 도메인의 A 레코드 별칭 대상을 설정할 때 필요합니다.
이 REST API 호출의 코드 예는 [domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html)를 참조하세요.
------
엣지 최적화 사용자 지정 도메인 이름은 사용할 수 있을 때까지 약 40분이 걸리지만, 콘솔에는 연결된 CloudFront 배포 도메인 이름이 인증서 ARN과 함께 `distribution-id.cloudfront.net` 형식으로 즉시 표시됩니다. 그동안 기본 경로 매핑 또는 라우팅 규칙을 생성한 다음, 사용자 지정 도메인 이름을 연결된 CloudFront 배포 도메인 이름에 매핑하기 위한 DNS 레코드 별칭을 구성할 수 있습니다.
## 사용자 지정 도메인 이름을 호스트 이름으로 사용하여 API의 기본 경로 매핑 구성
라우팅 모드를 `API_MAPPING_ONLY`로 설정했으므로 기본 경로 매핑을 사용하여 단일 사용자 지정 도메인 이름을 여러 API의 호스트 이름으로 사용할 수 있습니다. 이렇게 하면 사용자 지정 도메인 이름 및 연결된 기본 경로의 결합을 통해 API에 액세스할 수 있습니다.
예를 들어, API 게이트웨이에서 `PetStore`라는 API와 `Dogs`라는 다른 API를 생성하고 `api.example.com`이라는 사용자 지정 도메인 이름을 설정한 경우 `PetStore` API의 URL을 `https://api.example.com`으로 설정할 수 있습니다.
이렇게 하면 `PetStore` API가 빈 문자열의 기본 경로와 연결됩니다. `PetStore` API의 URL을 `https://api.example.com/PetStore`로 설정하면 `PetStore` API가 `PetStore`의 기본 경로와 연결됩니다. `Dogs` API에 대해 `MyDogList`의 기본 경로를 할당할 수 있습니다. `https://api.example.com/MyDogList`의 URL은 `Dogs` API의 루트 URL입니다.
여러 수준에서 API 매핑을 구성하려면 지역 사용자 지정 도메인 이름만 사용할 수 있습니다. 엣지 최적화 사용자 지정 도메인 이름은 사용할 수 없습니다. 자세한 내용은 [API 매핑을 사용하여 API 스테이지를 REST API에 대한 사용자 지정 도메인 이름에 연결합니다.](rest-api-mappings.md) 섹션을 참조하세요.
다음 절차에서는 사용자 지정 도메인 이름에서 API 스테이지로 경로를 매핑하도록 API 매핑을 설정합니다.
------
#### [ AWS Management Console ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. API Gateway 콘솔 기본 탐색 창에서 **Custom Domain Names(사용자 지정 도메인 이름)**를 선택합니다.
1. 사용자 지정 도메인 이름을 선택합니다.
1. **API 매핑 구성**을 선택합니다.
1. **Add new mapping(새 매핑 추가)**을 선택합니다.
1. 매핑에 대한 **API**, **스테이지**, 및 **경로**(선택 사항)를 지정합니다.
1. **저장**을 선택합니다.
------
#### [ REST API ]
요청 페이로드에서 `basePath`, `restApiId` 및 배포 `stage` 속성을 지정하여 특정 사용자 지정 도메인 이름에 대해 [basepathmapping:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html)를 호출합니다.
성공적인 API 응답은 `201 Created` 응답을 반환합니다.
REST API 호출의 코드 예는 [basepathmapping:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html)를 참조하세요.
------
API로 트래픽을 라우팅하는 방법에 대한 유연성을 높이기 위해 라우팅 모드를 `ROUTING_RULE_ONLY` 또는 `ROUTING_RULE_THEN_API_MAPPING`으로 변경하고 라우팅 규칙을 만들 수 있습니다. 자세한 내용은 [API Gateway에서 사용자 지정 도메인 이름을 통해 API로 트래픽을 전송합니다.](rest-api-routing-mode.md) 섹션을 참조하세요.
## 엣지 최적화 사용자 지정 도메인 이름에 대한 DNS 레코드 생성
엣지 최적화 사용자 지정 도메인 이름을 만들기 시작한 후 DNS 레코드 별칭을 설정합니다.
Route 53를 사용하여 사용자 지정 도메인 이름의 A 레코드 별칭을 생성하고 CloudFront 배포 도메인 이름을 별칭 대상으로 지정하는 것이 좋습니다. 다시 말해서 사용자 지정 도메인이 zone apex라고 하더라도 Route 53은 사용자 지정 도메인 이름을 라우팅할 수 있습니다. 자세한 내용은 *Amazon Route 53 개발자 안내서*의 [별칭 및 비별칭 리소스 레코드 세트 간의 선택](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-choosing-alias-non-alias.html)에서 확인할 수 있습니다.
Amazon Route 53에 대한 지침은 *Amazon Route 53 개발자 안내서*에서 [도메인 이름을 사용하여 Amazon API Gateway API로 트래픽 라우팅](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)을 참조하세요.
## CloudTrail에서 사용자 지정 도메인 이름 생성 로그
계정에서 수행한 API Gateway 호출을 로깅하기 위해 CloudTrail을 활성화한 경우, API에 대한 사용자 지정 도메인 이름을 생성하거나 업데이트할 때 API Gateway는 연결된 CloudFront 배포 업데이트를 기록합니다. 이 로그는 `us-east-1`에서 사용할 수 있습니다. 이러한 CloudFront 배포는 API Gateway가 소유하므로, 이러한 각 보고된 CloudFront 배포는 API 소유자의 계정 ID 대신 다음과 같은 리전별 API Gateway 계정 ID 중 하나로 식별됩니다.
| **리전** | **계정 ID**\$1 |
| --- | --- |
| us-east-1 | 392220576650 |
| us-east-2 | 718770453195 |
| us-west-1 | 968246515281 |
| us-west-2 | 109351309407 |
| ca-central-1 | 796887884028 |
| eu-west-1 | 631144002099 |
| eu-west-2 | 544388816663 |
| eu-west-3 | 061510835048 |
| eu-central-1 | 474240146802 |
| eu-central-2 | 166639821150 |
| eu-north-1 | 394634713161 |
| eu-south-1 | 753362059629 |
| eu-south-2 | 359345898052 |
| ap-northeast-1 | 969236854626 |
| ap-northeast-2 | 020402002396 |
| ap-northeast-3 | 360671645888 |
| ap-southeast-1 | 195145609632 |
| ap-southeast-2 | 798376113853 |
| ap-southeast-3 | 652364314486 |
| ap-southeast-4 | 849137399833 |
| ap-south-1 | 507069717855 |
| ap-south-2 | 644042651268 |
| ap-east-1 | 174803364771 |
| sa-east-1 | 287228555773 |
| me-south-1 | 855739686837 |
| me-central-1 | 614065512851 |
## ACM에 가져온 인증서 교체
ACM은 발급한 인증서의 갱신을 자동으로 처리합니다. 사용자 지정 도메인 이름에 대해 ACM이 발급한 인증서는 교체할 필요가 없습니다. CloudFront가 사용자를 대신하여 처리합니다.
하지만 인증서를 ACM에 가져와서 사용자 지정 도메인 이름에 사용할 경우 만료되기 전에 인증서를 교체해야 합니다. 여기에는 도메인 이름에 대한 새 타사 인증서를 가져오고 기존 인증서를 새 인증서로 교체하는 작업이 포함됩니다. 새로 가져온 인증서가 만료되면 이 프로세스를 반복해야 합니다. 또는 도메인 이름에 대한 새 인증서를 발급하도록 ACM에 요청하고 기존 인증서를 ACM에서 발급한 새 인증서로 교체할 수 있습니다. 이후에는 ACM과 CloudFront에서 인증서 교체를 자동으로 처리하도록 둘 수 있습니다. 새 ACM 인증서를 생성하거나 가져오려면 [SSL/TLS 인증서를 생성하거나 ACM으로 가져오려면](how-to-specify-certificate-for-custom-domain-name.md#how-to-specify-certificate-for-custom-domain-name-setup)의 단계를 수행합니다.
다음 절차에서는 도메인 이름에 대한 인증서를 교체하는 방법에 대해 설명합니다.
**참고**
ACM으로 가져온 인증서를 교체하는 데는 약 40분이 소요됩니다.
------
#### [ AWS Management Console ]
1. ACM에서 인증서를 요청하거나 가져옵니다.
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. API Gateway 콘솔 기본 탐색 창에서 **Custom Domain Names(사용자 지정 도메인 이름)**를 선택합니다.
1. 엣지 최적화 사용자 지정 도메인 이름을 선택합니다.
1. **엔드포인트 구성**에서 **편집**을 선택합니다.
1. **ACM 인증서** 드롭다운 목록에서 인증서를 선택합니다.
1. **변경 사항 저장**을 선택하여 사용자 지정 도메인 이름에 대한 인증서 교체를 시작합니다.
------
#### [ REST API ]
지정된 도메인 이름에 대한 새 ACM 인증서의 ARN을 지정하여 [domainname:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDomainName.html) 작업을 호출합니다.
------
#### [ AWS CLI ]
다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)은 엣지 최적화 도메인 이름에 대한 ACM 인증서를 업데이트합니다.
```
aws apigateway update-domain-name \
--domain-name edge.example.com \
--patch-operations "op='replace',path='/certificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"
```
다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)은 리전 도메인 이름에 대한 ACM 인증서를 업데이트합니다.
```
aws apigateway update-domain-name \
--domain-name regional.example.com \
--patch-operations "op='replace',path='/regionalCertificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"
```
------
## 기본 경로 매핑을 사용할 때 사용자 지정 도메인 이름으로 API 직접 호출
사용자 지정 도메인 이름을 사용하여 API를 호출하는 것은 올바른 URL을 사용한 경우 기본 도메인 이름을 사용하여 API를 호출하는 것과 동일합니다.
다음 예제에서는 기본 URL 세트와 지정된 리전(`udxjef`) 및 해당 사용자 지정 도메인 이름(`qf3duz`)의 두 API(`us-east-1` 및 `api.example.com`)에 해당되는 사용자 지정 URL을 비교 및 대비합니다.
| API ID | Stage | 기본 URL | 기본 경로 | 사용자 지정 URL |
| --- | --- | --- | --- | --- |
| udxjef | prod | https://udxjef.execute-api.us-east-1.amazonaws.com/prod | /petstore | https://api.example.com/petstore |
| udxjef | tst | https://udxjef.execute-api.us-east-1.amazonaws.com/tst | /petdepot | https://api.example.com/petdepot |
| qf3duz | dev | https://qf3duz.execute-api.us-east-1.amazonaws.com/dev | /bookstore | https://api.example.com/bookstore |
| qf3duz | tst | https://qf3duz.execute-api.us-east-1.amazonaws.com/tst | /bookstand | https://api.example.com/bookstand |
API로 트래픽을 라우팅하는 방법에 대한 유연성을 높이기 위해 라우팅 규칙을 생성할 수 있습니다. 자세한 내용은 [API Gateway에서 사용자 지정 도메인 이름을 통해 API로 트래픽을 전송합니다.](rest-api-routing-mode.md) 섹션을 참조하세요.
API Gateway는 [SNI(Server Name Indication)](https://en.wikipedia.org/wiki/Server_Name_Indication)를 사용하여 API에 대한 사용자 지정 도메인 이름을 지원합니다. 브라우저 또는 SNI를 지원하는 클라이언트 라이브러리를 사용하여 사용자 지정 도메인 이름이 포함된 API를 호출할 수 있습니다.
API Gateway는 CloudFront 배포에 SNI를 적용합니다. CloudFront에서 사용자 지정 도메인 이름을 사용하는 방법에 대한 자세한 내용은 [Amazon CloudFront 사용자 지정 SSL](https://aws.amazon.com/cloudfront/custom-ssl-domains/)을 참조하세요.
# API Gateway에서 사용자 지정 도메인 이름을 다른 API 엔드포인트 유형으로 마이그레이션
엣지 최적화 및 리전 엔드포인트 간에 사용자 지정 도메인 이름을 마이그레이션할 수 있습니다. 퍼블릭 사용자 지정 도메인 이름은 프라이빗 사용자 지정 도메인 이름으로 마이그레이션할 수 없습니다. 먼저 사용자 지정 도메인 이름에 대한 기존 `endpointConfiguration.types` 목록에 새로운 엔드포인트 구성 유형을 추가합니다. 그 다음에 DNS 레코드를 설정하여 사용자 지정 도메인 이름이 새로 프로비저닝된 엔드포인트를 가리키도록 합니다. 마지막으로, 더 이상 사용되지 않는 사용자 지정 도메인 이름 엔드포인트를 제거합니다.
## 고려 사항
리전 API 엔드포인트와 엣지 최적화 API 엔드포인트 간에 사용자 지정 도메인을 마이그레이션할 때 고려할 사항은 다음과 같습니다.
+ 엣지 최적화 사용자 지정 도메인 이름에는 미국 동부(버지니아 북부) – `us-east-1` 리전의 ACM에서 제공하는 인증서가 필요합니다. 이 인증서는 모든 지리적 위치에 배포됩니다.
+ 리전 사용자 지정 도메인 이름에는 API를 호스팅하는 동일한 리전의 ACM에서 제공하는 인증서가 필요합니다. API에 대해 로컬인 리전에 새로운 ACM 인증서를 요청하여 `us-east-1` 리전에 있지 않은 엣지 최적화 사용자 지정 도메인 이름을 리전 사용자 지정 도메인 이름으로 마이그레이션할 수 있습니다.
+ 엣지 최적화 사용자 지정 도메인 이름과 리전 사용자 지정 도메인 이름 간에 마이그레이션을 완료하는 데 최대 60초가 걸릴 수 있습니다. DNS 레코드를 업데이트하는 시점에 따라서도 마이그레이션 시간이 달라집니다.
+ 엔드포인트 액세스 모드가 `BASIC`으로 설정된 경우에만 엔드포인트 구성을 추가할 수 있습니다. 두 개의 엔드포인트 구성이 있으면 엔드포인트 액세스 모드를 변경할 수 없습니다. 자세한 내용은 [엔드포인트 액세스 모드](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode) 섹션을 참조하세요.
+ 사용자 지정 도메인 이름이 `SecurityPolicy_`로 시작하는 보안 정책을 사용하는 경우 새 엔드포인트 구성 유형을 추가할 때 엔드포인트 액세스 모드는 두 엔드포인트 유형에서 동일하므로 새 엔드포인트 구성 유형에 대해 `SecurityPolicy_`로 시작하는 보안 정책을 선택해야 합니다.
## 사용자 지정 도메인 이름 마이그레이션
**참고**
마이그레이션을 완료하려면 사용자 지정 도메인 이름에서 더 이상 사용되지 않는 엔드포인트를 제거해야 합니다.
엣지 최적화 사용자 지정 도메인 이름을 리전 사용자 지정 도메인 이름으로 마이그레이션하려면 다음 절차를 따르세요.
------
#### [ AWS Management Console ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 기본 탐색 창에서 **사용자 지정 도메인 이름**을 선택합니다.
1. 엣지 최적화 사용자 지정 도메인 이름을 선택합니다.
1. **엔드포인트 구성**에서 **편집**을 선택합니다.
1. **리전 엔드포인트 추가**를 선택합니다.
1. **ACM 인증서**에서 인증서를 선택합니다.
리전 인증서는 리전 API와 동일한 리전의 것이어야 합니다.
1. **변경 사항 저장**을 선택합니다.
1. 리전 사용자 지정 도메인 이름이 이 리전 호스트 이름으로 연결되도록 DNS 레코드를 설정해야 합니다. 자세한 내용은 [트래픽을 API Gateway로 라우팅하도록 Route 53 구성](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)을 참조하세요.
1. DNS 구성이 올바른 엔드포인트로 연결되는지 확인한 후 엣지 최적화 엔드포인트 구성을 삭제합니다. 사용자 지정 도메인 이름을 선택하고 **엣지 최적화 엔드포인트 구성**에서 **삭제**를 선택합니다.
1. 선택 사항을 확인하고 엔드포인트를 삭제합니다.
------
#### [ AWS CLI ]
다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 명령은 엣지 최적화 사용자 지정 도메인 이름을 리전 사용자 지정 도메인 이름으로 마이그레이션합니다.
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "REGIONAL" },
{ "op":"add", "path": "/regionalCertificateArn", "value": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149" }
]'
```
리전 인증서는 리전 API와 동일한 리전의 것이어야 합니다.
출력은 다음과 같습니다.
```
{
"certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149",
"regionalDomainName": "d-fdisjghyn6.execute-api.us-west-2.amazonaws.com"
}
```
그 결과 얻는 `regionalDomainName` 속성은 마이그레이션된 리전 사용자 지정 도메인 이름에 대해 리전 API 호스트 이름을 반환합니다. 리전 사용자 지정 도메인 이름이 이 리전 호스트 이름을 가리키도록 DNS 레코드를 설정해야 합니다. 이렇게 하면 목적지가 사용자 지정 도메인 이름인 트래픽이 리전 호스트로 라우팅됩니다.
DNS 레코드가 설정된 후에는 엣지 최적화 사용자 지정 도메인 이름을 제거할 수 있습니다. 다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 명령은 엣지 최적화 사용자 지정 도메인 이름을 제거합니다.
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", "value":"EDGE"},
{"op":"remove", "path":"certificateName"},
{"op":"remove", "path":"certificateArn"}
]'
```
------
다음 절차에서는 향상된 보안 정책을 사용하는 엣지 최적화 사용자 지정 도메인 이름을 향상된 보안 정책도 사용하는 리전 사용자 지정 도메인 이름으로 마이그레이션하는 방법을 보여 줍니다.
------
#### [ AWS Management Console ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 기본 탐색 창에서 **사용자 지정 도메인 이름**을 선택합니다.
1. 엣지 최적화 사용자 지정 도메인 이름을 선택합니다.
1. **엔드포인트 구성**에서 **편집**을 선택합니다.
1. **리전 엔드포인트 추가**를 선택합니다.
1. **ACM 인증서**에서 인증서를 선택합니다.
리전 인증서는 리전 API와 동일한 리전의 것이어야 합니다.
1. **보안 정책**의 경우 `SecurityPolicy_`로 시작하는 보안 정책을 선택합니다.
1. **엔드포인트 액세스 모드**에서 **기본**을 선택합니다.
1. **변경 사항 저장**을 선택합니다.
1. 리전 사용자 지정 도메인 이름이 이 리전 호스트 이름으로 연결되도록 DNS 레코드를 설정해야 합니다. 자세한 내용은 [트래픽을 API Gateway로 라우팅하도록 Route 53 구성](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)을 참조하세요.
1. DNS 구성이 올바른 엔드포인트로 연결되는지 확인한 후 엣지 최적화 엔드포인트 구성을 삭제합니다. 사용자 지정 도메인 이름을 선택하고 **엣지 최적화 엔드포인트 구성**에서 **삭제**를 선택합니다.
1. 선택 사항을 확인하고 엔드포인트를 삭제합니다.
------
#### [ AWS CLI ]
다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 명령은 엣지 최적화 사용자 지정 도메인 이름을 리전 사용자 지정 도메인 이름으로 마이그레이션합니다.
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "REGIONAL" },
{ "op":"replace", "path": "/securityPolicy", "value":"SecurityPolicy_TLS13_1_3_2025_09"},
{ "op":"add", "path": "/regionalCertificateArn", "value": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149" }
]'
```
리전 인증서는 리전 API와 동일한 리전의 것이어야 합니다.
출력은 다음과 같습니다.
```
{
"certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "BASIC",
"regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149",
"regionalDomainName": "d-fdisjghyn6.execute-api.us-west-2.amazonaws.com"
}
```
그 결과 얻는 `regionalDomainName` 속성은 마이그레이션된 리전 사용자 지정 도메인 이름에 대해 리전 API 호스트 이름을 반환합니다. 리전 사용자 지정 도메인 이름이 이 리전 호스트 이름을 가리키도록 DNS 레코드를 설정해야 합니다. 이렇게 하면 목적지가 사용자 지정 도메인 이름인 트래픽이 리전 호스트로 라우팅됩니다.
DNS 레코드가 설정된 후에는 엣지 최적화 사용자 지정 도메인 이름을 제거할 수 있습니다. 다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 명령은 엣지 최적화 사용자 지정 도메인 이름을 제거합니다.
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", "value":"EDGE"},
{"op":"remove", "path":"certificateName"},
{"op":"remove", "path":"certificateArn"}
]'
```
------
리전 사용자 지정 도메인 이름을 엣지 최적화 사용자 지정 도메인 이름으로 마이그레이션하려면 다음 절차를 따르세요.
------
#### [ AWS Management Console ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 기본 탐색 창에서 **사용자 지정 도메인 이름**을 선택합니다.
1. 리전 사용자 지정 도메인 이름을 선택합니다.
1. **엔드포인트 구성**에서 **편집**을 선택합니다.
1. **엣지 최적화 엔드포인트 추가**를 선택합니다.
1. **ACM 인증서**에서 인증서를 선택합니다.
엣지 최적화 도메인 인증서는 `us-east-1` 리전에 생성되어야 합니다.
1. **저장**을 선택합니다.
1. 엣지 최적화 사용자 지정 도메인 이름이 엣지 최적화 호스트 이름으로 연결되도록 DNS 레코드를 설정합니다. 자세한 내용은 [트래픽을 API Gateway로 라우팅하도록 Route 53 구성](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html)을 참조하세요.
1. DNS 구성이 올바른 엔드포인트로 연결되는지 확인한 후 리전 엔드포인트 구성을 삭제합니다. 사용자 지정 도메인 이름을 선택하고 **리전 엔드포인트 구성**에서 **삭제**를 선택합니다.
1. 선택 사항을 확인하고 엔드포인트를 삭제합니다.
------
#### [ AWS CLI ]
다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 명령은 리전 사용자 지정 도메인 이름을 엣지 최적화 사용자 지정 도메인 이름으로 마이그레이션합니다.
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "EDGE" },
{ "op":"add", "path": "/certificateName", "value": "edge-cert" },
{"op":"add", "path": "/certificateArn", "value": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a"}
]'
```
엣지 최적화 도메인 인증서는 `us-east-1` 리전에 생성되어야 합니다.
출력은 다음과 같습니다.
```
{
"certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"regionalCertificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/3d881b54-851a-478a-a887-f6502760461d",
"regionalDomainName": "d-cgkq2qwgzf.execute-api.us-east-1.amazonaws.com"
}
```
API Gateway는 지정된 사용자 지정 도메인 이름에 대해 `distributionDomainName` 속성 값으로 엣지 최적화 API 호스트 이름을 반환합니다. DNS 레코드를 설정하여 엣지 최적화 사용자 지정 도메인 이름이 이 배포 도메인 이름을 가리키도록 해야 합니다. 이렇게 하면 목적지가 엣지 최적화 사용자 지정 도메인 이름인 트래픽이 엣지 최적화 API 호스트 이름으로 라우팅됩니다.
DNS 레코드가 설정된 후에는 다음과 같이 사용자 지정 도메인 이름의 `REGION` 엔드포인트 유형을 제거할 수 있습니다. 다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 명령은 리전 엔드포인트 유형을 제거합니다.
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", value:"REGIONAL"},
{"op":"remove", "path":"regionalCertificateArn"}
]'
```
출력은 다음과 같습니다.
```
{
"certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": "EDGE"
}
}
```
------
# API Gateway에서 사용자 지정 도메인 이름을 통해 API로 트래픽을 전송합니다.
사용자 지정 도메인 이름에 대한 라우팅 모드를 구성할 때 수신 트래픽이 API로 전달되는 방식을 설정합니다. 라우팅 규칙, API 매핑 또는 라우팅 규칙 및 API 매핑 모두를 사용하여 API로 트래픽을 전송합니다. 다음 섹션에서는 라우팅 규칙을 사용해야 하는 경우, API 매핑을 사용해야 하는 경우, 사용자 지정 도메인 이름에 대해 라우팅 모드를 설정하는 방법을 설명합니다.
## 라우팅 규칙을 사용해야 하는 경우
라우팅 규칙을 사용하는 경우 특정 조건과 일치하는 수신 요청을 특정 REST API 스테이지로 전달합니다. 예를 들어, 헤더 `version:v1`과 기본 경로 `/users`가 포함된 경우 규칙은 요청을 `users` REST API의 `production` 스테이지로 라우팅할 수 있습니다. 라우팅 규칙을 사용하여 A/B 테스트 또는 API의 새 버전 사용 증가와 같은 사용 사례를 지원하는 고급 동적 라우팅 토폴로지를 생성합니다.
트래픽을 REST API로 보낼 때는 사용자 지정 도메인 이름에 대한 라우팅 규칙을 사용하는 것이 좋습니다. 라우팅 규칙을 사용하여 API 매핑을 다시 만들 수 있습니다. 자세한 내용은 [라우팅 규칙을 사용하여 API 매핑 다시 만들기](rest-api-routing-rules-recreate-api-mapping.md) 섹션을 참조하세요.
REST API 경우 라우팅 규칙과 API 매핑을 함께 사용할 수도 있습니다. 라우팅 규칙과 API 매핑을 함께 사용하는 경우 API Gateway는 API 매핑을 평가하기 전에 항상 라우팅 규칙을 평가합니다. 라우팅 규칙과 API 매핑을 함께 사용하여 현재 사용자 지정 도메인 이름을 마이그레이션하거나 라우팅 규칙을 탐색합니다.
### 라우팅 규칙에 대한 고려 사항
다음 고려 사항은 라우팅 규칙 사용에 영향을 미칠 수 있습니다.
+ WebSocket 또는 HTTP API는 라우팅 규칙의 대상 API로 지원되지 않습니다.
+ 사용자 지정 도메인 이름에 REST 및 HTTP API 모두에 대한 API 매핑이 있는 경우 라우팅 규칙이 지원되지 않습니다.
+ 프라이빗 사용자 지정 도메인을 프라이빗 REST API로 라우팅하는 규칙을 만들 수 있습니다. 퍼블릭 사용자 지정 도메인을 리전 또는 엣지 최적화 API로 라우팅하는 규칙을 만들 수 있습니다.
+ 퍼블릭 사용자 지정 도메인을 프라이빗 API로 라우팅하는 규칙을 만들 수 없습니다. 프라이빗 사용자 지정 도메인을 퍼블릭 API로 라우팅하는 규칙을 만들 수 없습니다.
## 라우팅 규칙과 API 매핑 중에서 선택
가능하면 라우팅 규칙을 사용하는 것이 좋습니다. HTTP 또는 WebSocket API로 트래픽을 전송하는 데만 API 매핑을 사용합니다.
# 사용자 지정 도메인 이름의 라우팅 모드 설정
API Gateway가 API로 트래픽을 라우팅하는 데 사용할 라우팅 모드를 선택할 수 있습니다. 자세한 내용은 [API Gateway에서 사용자 지정 도메인 이름을 통해 API로 트래픽을 전송합니다.](rest-api-routing-mode.md) 섹션을 참조하세요. 이 섹션에서는 사용자 지정 도메인 이름의 라우팅 모드에 대해 설명합니다. API로 트래픽을 라우팅하려면 사용자 지정 도메인 이름에 대한 라우팅 모드를 설정해야 합니다. 지원되는 라우팅 모드는 다음과 같습니다.
+ **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING** - 이 모드를 사용하여 라우팅 규칙과 API 매핑을 모두 사용해 API로 트래픽을 전송합니다. 이 모드에서는 모든 라우팅 규칙이 모든 API 매핑보다 우선 적용됩니다. 이 모드의 예제는 [예제 2: 라우팅 규칙 및 API 매핑](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-and-mappings) 섹션을 참조하세요.
+ **ROUTING\$1RULE\$1ONLY** - 이 모드를 사용하여 라우팅 규칙이 API로 트래픽을 전송하는 것만 허용합니다. 사용자 지정 도메인 이름이 이 모드를 사용하는 경우 API 매핑을 만들 수 없지만 [get-api-mappings](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-api-mappings.html) 명령을 사용하여 이를 볼 수 있습니다. API 직접 호출자는 API 매핑을 사용하여 이 도메인 이름에 액세스할 수 없습니다.
+ **API\$1MAPPING\$1ONLY** - 이 모드를 사용하여 API 매핑이 API로 트래픽을 전송하는 것만 허용합니다. 사용자 지정 도메인 이름이 이 모드를 사용하는 경우 라우팅 규칙을 만들 수 없지만 `list-routing-rules` 명령을 사용하여 이를 볼 수 있습니다. API 직접 호출자는 라우팅 규칙을 사용하여 이 도메인 이름에 액세스할 수 없습니다.
이는 모든 기존 도메인 이름 및 앞으로 만드는 새 도메인 이름에 대한 기본 라우팅 모드입니다.
`apigateway`를 사용하여 사용자 지정 도메인 이름을 만들면 `API_MAPPING_ONLY`를 `BASE_PATH_MAPPING_ONLY`로, `ROUTING_RULE_THEN_API_MAPPING`을 `ROUTING_RULE_THEN_BASE_PATH_MAPPING`으로 부릅니다. 이 동작은 AWS Management Console이 아닌 AWS CLI, CloudFormation 또는 SDK에 대해서만 존재합니다.
다음 절차에서는 기존 사용자 지정 도메인 이름의 라우팅 모드를 변경하는 방법을 보여줍니다. 사용자 지정 도메인 이름의 라우팅 모드를 변경하면 API 직접 호출자는 지원되지 않는 라우팅 모드를 사용하여 도메인 이름에 액세스할 수 없습니다.
------
#### [ AWS Management Console ]
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. **저장**을 선택합니다.
라우팅 모드를 `ROUTING_RULE_ONLY` 또는 `API_MAPPING_ONLY`로 변경하면 사용자가 만든 API 매핑 또는 라우팅 규칙이 콘솔의 도메인 이름 세부 정보 페이지에서 제거됩니다. 라우팅 규칙 또는 API 매핑을 지원하도록 라우팅 모드를 변경하면 이러한 리소스가 반환됩니다.
------
#### [ AWS CLI - apigatewayv2 ]
다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) 명령은 라우팅 모드 `ROUTING_RULE_THEN_API_MAPPING`을 사용하도록 도메인 이름을 업데이트합니다.
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode "ROUTING_RULE_THEN_API_MAPPING"
```
출력은 다음과 같습니다.
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "api.example.com",
"DomainNameArn": "arn:aws:apigateway:us-west-2::/domainnames/api.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcdefg.execute-api.us-west-2.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/abcdefg-123456-abcdefg",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"SecurityPolicy": "TLS_1_2"
}
],
"RoutingMode": "ROUTING_RULE_THEN_API_MAPPING",
"Tags": {}
}
```
------
#### [ AWS CLI - apigateway ]
다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 명령은 라우팅 모드 `ROUTING_RULE_THEN_BASE_PATH_MAPPING`을 사용하도록 프라이빗 사용자 지정 도메인 이름을 업데이트합니다.
```
aws apigateway update-domain-name \
--domain-name 'private.example.com' \
--patch-operations "op='replace',path='/routingMode',value='ROUTING_RULE_THEN_BASE_PATH_MAPPING'"
```
출력은 다음과 같습니다.
```
{
"domainName": "private.example.com",
"domainNameId": "abcd1234",
"domainNameArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234",
"certificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"certificateUploadDate": "2024-09-10T10:31:20-07:00",
"endpointConfiguration": {
"types": [
"PRIVATE"
],
"ipAddressType": "dualstack"
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"policy": "...",
"routingMode" : "ROUTING_RULE_THEN_BASE_PATH_MAPPING"
}
```
------
# 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`에 대한 액세스를 거부할 수도 있습니다.
# API 매핑을 사용하여 API 스테이지를 REST API에 대한 사용자 지정 도메인 이름에 연결합니다.
API 매핑을 사용하여 API 스테이지를 사용자 지정 도메인 이름에 연결합니다. 이렇게 하면 사용자 지정 도메인 이름을 통해 API로 트래픽이 전송됩니다.
API 매핑은 API, 스테이지 및 매핑에 사용할 경로(선택 사항)를 지정합니다. 예를 들어 `https://api.example.com/orders`를 API의 `production` 스테이지에 매핑할 수 있습니다.
HTTP 및 REST API 스테이지를 동일한 사용자 지정 도메인 이름에 매핑할 수 있습니다.
API 매핑을 생성하기 전에 API, 스테이지 및 사용자 지정 도메인 이름이 있어야 합니다. 사용자 지정 도메인 이름 생성에 대한 자세한 내용은 [API Gateway에서 리전 사용자 지정 도메인 이름 설정](apigateway-regional-api-custom-domain-create.md) 단원을 참조하세요.
## 사용자 지정 도메인 이름에 대한 수신 요청
사용자 지정 도메인 이름을 API의 스테이지에 매핑하면 API Gateway가 수신되는 기본 경로를 제거합니다. 이렇게 하면 API에 대한 간접 호출에서 매핑된 기본 경로가 제거됩니다. 예를 들어 기본 경로가 `https://api.example.com/orders/shop/5`에서 `test` 스테이지로 매핑되어 있고 `https://api.example.com/orders/shop/5/hats` 요청을 사용한 경우, API Gateway는 `orders/shop/5/hats` 리소스가 아닌 API `test` 스테이지의 `/hats` 리소스를 간접적으로 호출합니다.
## API 요청 매핑
다음은 API Gateway가 API 매핑을 평가하는 방법을 설명합니다.
`orders`에서 API `beta` 스테이지로의 API 매핑 및 `shipping`에서 API `alpha` 스테이지로의 API 매핑과 같은 단일 수준 매핑을 사용하여 API 매핑을 만들 수 있습니다. TLS 1.2 보안 정책을 사용하는 리전 사용자 지정 도메인 이름의 경우 API Gateway는 다단계 API 매핑을 지원합니다. `orders/v1/items`에서 API `alpha` 스테이지와 `orders/v2/items`에서 API `beta` 스테이지로의 API 매핑을 만들 수 있습니다. 여러 수준을 사용하여 매핑을 만드는 경우 API Gateway는 일치하는 경로가 가장 긴 API 매핑으로 요청을 전송합니다.
빈 경로 `(none)`에 대한 API 매핑을 만들 수 있습니다. 요청과 일치하는 경로가 없으면 API Gateway는 빈 경로 `(none)`에 요청을 보냅니다.
다음 예제에서는 사용자 지정 도메인 이름 `https://api.example.com`에 다음 API 매핑이 있습니다.
| API 매핑 | 선택한 API |
| --- | --- |
| `(none)` | API 1 |
| `orders` | API 2 |
| `orders/v1/items` | API 3 |
| `orders/v2/items` | API 4 |
| `orders/v1/items/categories` | API 5 |
다음 표는 API Gateway가 이전 API 매핑을 예제 요청에 적용하는 방법을 보여줍니다.
| 요청 | 선택한 API | 설명 |
| --- | --- | --- |
| `https://api.example.com/orders` | API 2 | 요청은 이 API 매핑과 정확히 일치합니다. |
| `https://api.example.com/orders/v1/items` | API 3 | 요청은 이 API 매핑과 정확히 일치합니다. |
| `https://api.example.com/orders/v2/items` | API 4 | 요청은 이 API 매핑과 정확히 일치합니다. |
| `https://api.example.com/orders/v1/items/123` | API 3 | API Gateway는 일치하는 경로가 가장 긴 매핑을 선택합니다. 요청 끝에 있는 `123`은(는) 선택 항목에 영향을 주지 않습니다. [사용자 지정 도메인 이름에 대한 수신 요청](#rest-api-mappings-incoming-requests)을(를) 참조하세요. |
| `https://api.example.com/orders/v2/items/categories/5` | API 5 | API Gateway는 일치하는 경로가 가장 긴 매핑을 선택합니다. |
| `https://api.example.com/customers` | API 1 | API Gateway는 빈 매핑을 캐치 올(catch-all)로 사용합니다. |
| `https://api.example.com/ordersandmore` | API 2 | API Gateway는 일치하는 접두사가 가장 긴 매핑을 선택합니다. 단일 수준 매핑으로 구성된 사용자 지정 도메인 이름(예: 단지 `https://api.example.com/orders` 및 `https://api.example.com/`)의 경우 `ordersandmore`와 일치하는 경로가 없으므로 API Gateway는 `API 1`을 선택합니다. |
## 제한 사항
+ API 매핑에서 사용자 지정 도메인 이름과 매핑된 API는 동일한 AWS 계정에 있어야 합니다.
+ API 매핑에는 문자, 숫자 및 문자 `$-_.+!*'()/`만 포함해야 합니다.
+ API 매핑에서 경로의 최대 길이는 300자입니다.
+ 각 도메인 이름에 대해 여러 수준의 API 매핑이 200개 있을 수 있습니다. 이 제한에는 `/prod`와 같은 단일 수준의 API 매핑은 포함되지 않습니다.
+ TLS 1.2 보안 정책을 사용하여 HTTP API를 리전별 사용자 지정 도메인 이름에만 매핑할 수 있습니다.
+ WebSocket API를 HTTP API 또는 REST API와 동일한 사용자 지정 도메인 이름에 매핑할 수 없습니다.
+ API 매핑을 생성한 후에는 DNS 공급자의 리소스 레코드를 생성하거나 업데이트하여 API 엔드포인트에 매핑해야 합니다.
+ 여러 레벨로 API 매핑을 생성하는 경우 API Gateway는 모든 헤더 이름을 소문자로 변환합니다.
## API 매핑 생성
API 매핑을 생성하려면 먼저 사용자 지정 도메인 이름, API 및 스테이지를 생성해야 합니다. 사용자 지정 도메인 이름에는 라우팅 모드가 `ROUTING_RULE_THEN_API_MAPPING` 또는 `API_MAPPING_ONLY`로 설정되어 있어야 합니다. 라우팅 모드를 설정하는 방법에 대한 자세한 내용은 [사용자 지정 도메인 이름의 라우팅 모드 설정](set-routing-mode.md) 섹션을 참조하세요.
예를 들어 모든 리소스를 생성하는 AWS Serverless Application Model 템플릿에 대해서는 GitHub의 [SAM 세션](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains)을 참조하세요.
------
#### [ AWS Management Console ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 기본 탐색 창에서 **사용자 지정 도메인 이름**을 선택합니다.
1. 사용자 지정 도메인 이름을 선택합니다.
1. **라우팅 세부 정보** 탭에서 **API 매핑 구성**을 선택합니다.
1. 매핑에 대한 **API**, **스테이지** 및 **경로**를 입력합니다.
1. **저장**을 선택합니다.
------
#### [ AWS CLI ]
다음 [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) 명령은 API 매핑을 생성합니다. 이 예에서 API Gateway는 지정된 API 및 스테이지로 `api.example.com/v1/orders` 요청을 보냅니다.
**참고**
여러 수준으로 API 매핑을 생성하려면 `apigatewayv2`을(를) 사용해야 합니다.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
다음 CloudFormation 예에서는 API 매핑을 생성합니다.
**참고**
여러 수준으로 API 매핑을 생성하려면 `AWS::ApiGatewayV2`을(를) 사용해야 합니다.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# API Gateway의 사용자 지정 도메인 이름에 대한 IP 주소 유형
사용자 지정 도메인 이름을 만들 때 도메인을 간접적으로 호출할 수 있는 IP 주소 유형을 지정합니다. IPv4를 선택하여 IPv4 주소가 도메인을 간접적으로 호출하도록 확인하거나, 듀얼 스택을 선택하여 IPv4 및 IPv6 주소가 모두 도메인을 간접적으로 호출하도록 허용할 수 있습니다. IP 공간 소진을 완화하기 위해 또는 보안 태세를 위해 IP 주소 유형을 듀얼 스택으로 설정하는 것이 좋습니다. 듀얼 스택 IP 주소 유형의 이점에 대한 자세한 내용은 [IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html)를 참조하세요.
도메인 이름의 엔드포인트 구성을 업데이트하여 IP 주소 유형을 변경할 수 있습니다.
## IP 주소 유형에 대한 고려 사항
다음 고려 사항은 IP 주소 유형 사용에 영향을 미칠 수 있습니다.
+ 퍼블릭 API의 API Gateway 사용자 지정 도메인 이름에 대한 기본 IP 주소 유형은 IPv4입니다.
+ 프라이빗 사용자 지정 도메인 이름은 듀얼 스택 IP 주소 유형만 가질 수 있습니다.
+ 사용자 지정 도메인 이름은 여기에 매핑된 모든 API에 대해 동일한 IP 주소 유형을 가질 필요가 없습니다. 기본 API 엔드포인트를 비활성화하면 직접 호출자가 도메인을 간접적으로 호출하는 방법에 영향을 미칠 수 있습니다.
## 사용자 지정 도메인 이름의 IP 주소 유형 변경
도메인 이름의 엔드포인트 구성을 업데이트하여 IP 주소 유형을 변경할 수 있습니다. AWS Management Console, AWS CLI, CloudFormation 또는 AWS SDK를 사용하여 엔드포인트 구성을 업데이트할 수 있습니다.
------
#### [ AWS Management Console ]
**사용자 지정 도메인 이름의 IP 주소 유형을 변경하려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 퍼블릭 사용자 지정 도메인 이름을 선택합니다.
1. **엔드포인트 구성**을 선택합니다.
1. IP 주소 유형에서 **IPv4** 또는 **듀얼 스택**을 선택합니다.
1. **저장**을 선택합니다.
------
#### [ AWS CLI ]
다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 명령은 IP 주소 유형이 듀얼 스택이 되도록 API를 업데이트합니다.
```
aws apigateway update-domain-name \
--domain-name dualstack.example.com \
--patch-operations "op='replace',path='/endpointConfiguration/ipAddressType',value='dualstack'"
```
출력은 다음과 같습니다.
```
{
"domainName": "dualstack.example.com",
"certificateUploadDate": "2025-02-04T14:46:10-08:00",
"regionalDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"regionalHostedZoneId": "Z3LQWSYCGH4ADY",
"regionalCertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"tags": {}
}
```
------
# API Gateway에서 사용자 지정 도메인에 대한 보안 정책 선택
보안 정책은 API Gateway가 제공하는 최소 TLS 버전과 암호 제품군의 사전 정의된 조합입니다.** 클라이언트가 API 또는 사용자 맞춤형 도메인 이름에 대해 TLS 핸드셰이크를 설정할 때, 보안 정책은 API Gateway가 허용하는 TLS 버전 및 암호 제품군을 강제 적용합니다. 보안 정책은 API 및 사용자 지정 도메인 이름을 클라이언트와 서버 간의 변조 및 도청과 같은 네트워크 보안 문제로부터 보호합니다.
API Gateway는 레거시 보안 정책과 향상된 보안 정책을 지원합니다. `TLS_1_0` 및 `TLS_1_2`는 레거시 보안 정책입니다. 일반화된 워크로드에 대해 이러한 보안 정책을 사용하거나 API 생성을 시작합니다. `SecurityPolicy_`로 시작하는 모든 정책은 향상된 보안 정책입니다. 규제 워크로드, 고급 거버넌스 또는 양자 내성 암호를 사용하려면 이러한 정책을 사용합니다. 향상된 보안 정책을 사용하는 경우 추가 거버넌스를 위해 엔드포인트 액세스 모드도 설정해야 합니다. 자세한 내용은 [엔드포인트 액세스 모드](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode) 섹션을 참조하세요.
## 고려 사항
API Gateway의 REST API에 대한 사용자 지정 도메인 이름에 대한 보안 정책에 대한 고려 사항은 다음과 같습니다.
+ 향상된 보안 정책을 사용하는 도메인 이름에서는 상호 TLS를 활성화할 수 없습니다.
+ 향상된 보안 정책을 사용하는 도메인 이름에는 HTTP API를 매핑할 수 없습니다.
+ 향상된 보안 정책을 사용하는 REST API에 대한 다중 수준 기본 경로 매핑을 활성화하면 동일한 도메인 이름에 대해 HTTP API에 대한 기본 경로 매핑을 생성할 수 없습니다.
+ API는 API와 보안 정책이 다른 사용자 지정 도메인 이름에 매핑할 수 있습니다. 해당 사용자 지정 도메인 이름을 간접적으로 호출하면 API Gateway는 API의 보안 정책을 사용하여 TLS 핸드셰이크를 협상합니다. 기본 API 엔드포인트를 비활성화하면 직접 호출자가 API를 간접적으로 호출하는 방법에 영향을 미칠 수 있습니다.
+ API Gateway는 모든 API에서 보안 정책을 지원합니다. 하지만 REST API에 대해서만 보안 정책을 선택할 수 있습니다. API Gateway는 HTTP 또는 WebSocket API에 대한 `TLS_1_2` 보안 정책만 지원합니다.
+ API Gateway는 여러 엔드포인트 유형이 있는 도메인 이름에 대한 보안 정책 업데이트를 지원하지 않습니다. 도메인 이름에 여러 엔드포인트 유형이 있는 경우 이 중 하나를 삭제하여 보안 정책을 업데이트합니다.
## API Gateway가 보안 정책을 적용하는 방법
다음 예제에서는 API Gateway가 보안 정책을 예로 사용하여 `SecurityPolicy_TLS13_1_3_2025_09` 보안 정책을 적용하는 방법을 보여 줍니다.
이 `SecurityPolicy_TLS13_1_3_2025_09` 보안 정책은 TLS 1.3 트래픽을 허용하고 TLS 1.2 및 TLS 1.0 트래픽은 거부합니다. TLS 1.3 트래픽의 경우 보안 정책은 다음 암호 그룹을 허용합니다.
+ `TLS_AES_128_GCM_SHA256`
+ `TLS_AES_256_GCM_SHA384`
+ `TLS_CHACHA20_POLY1305_SHA256`
API Gateway는 다른 암호 그룹을 허용하지 않습니다. 예를 들어 보안 정책은 암호 제품군을 사용하는 모든 TLS `AES128-SHA` 1.3 트래픽을 거부합니다.
API Gateway에 액세스하는 데 사용되는 TLS 프로토콜 및 암호 클라이언트를 모니터링하려면 액세스 로그에서 `$context.tlsVersion` 및 `$context.cipherSuite` 컨텍스트 변수를 사용할 수 있습니다. 자세한 내용은 [API Gateway에서 REST API 모니터링](rest-api-monitor.md) 섹션을 참조하세요.
모든 REST API와 사용자 지정 도메인 이름에 대한 기본 보안 정책을 보려면 [기본 보안 정책](apigateway-security-policies-list.md#apigateway-security-policies-default) 섹션을 참조하세요. 모든 REST API와 사용자 지정 도메인 이름에 대한 지원 보안 정책을 보려면 [지원되는 보안 정책](apigateway-security-policies-list.md) 섹션을 참조하세요.
## 사용자 지정 도메인 이름의 보안 정책 변경
보안 정책을 변경하는 경우 업데이트가 완료되는 데 약 15분이 걸립니다. 사용자 지정 도메인 이름의 `lastUpdateStatus`를 모니터링할 수 있습니다. 사용자 지정 도메인 이름이 업데이트되면 `lastUpdateStatus`는 `PENDING`이고 완료되면 `AVAILABLE`이 됩니다.
`SecurityPolicy_`로 시작하는 보안 정책을 사용하는 경우 엔드포인트 액세스 모드도 켜야 합니다. 자세한 내용은 [엔드포인트 액세스 모드](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode) 섹션을 참조하세요.
------
#### [ AWS Management Console ]
**사용자 지정 도메인 이름의 보안 정책 변경**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. 트래픽을 REST API로 전송하는 사용자 지정 도메인 이름을 선택합니다.
사용자 지정 도메인 이름과 연결된 엔드포인트 유형이 하나만 있는지 확인합니다.
1. **사용자 지정 도메인 이름 설정**을 선택한 다음 **편집**을 선택합니다.
1. **보안 정책**에서 새 정책을 선택합니다.
1. **엔드포인트 액세스 모드**에서 **엄격**을 선택합니다.
1. **변경 사항 저장**을 선택합니다.
------
#### [ AWS CLI ]
다음 [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) 명령은 `SecurityPolicy_TLS13_1_3_2025_09` 보안 정책을 사용하도록 도메인 이름을 업데이트합니다.
```
aws apigateway update-domain-name \
--domain-name example.com \
--patch-operations '[
{
"op": "replace",
"path": "/securityPolicy",
"value": "SecurityPolicy_TLS13_1_3_2025_09"
},
{
"op": "replace",
"path": "/endpointAccessMode",
"value": "STRICT"
}
]'
```
출력은 다음과 같습니다.
```
{
"domainName": "example.com",
"endpointConfiguration": {
"types": [ "REGIONAL" ],
"ipAddressType": "dualstack"
},
"regionalCertificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "STRICT"
}
```
------
## HTTP API 및 WebSocket API에 대한 정보
HTTP APIs 및 WebSocket APIs에 대한 자세한 내용은 [API Gateway의 HTTP API 보안 정책](http-api-ciphers.md) 및 [API Gateway의 WebSocket API 보안 정책](websocket-api-ciphers.md)을 참조합니다.
# REST API의 기본 엔드포인트 비활성화
기본적으로 클라이언트는 API에 대해 API Gateway가 생성하는 `execute-api` 엔드포인트를 사용하여 API를 호출할 수 있습니다. 클라이언트가 사용자 지정 도메인 이름을 사용해야만 API에 액세스할 수 있도록 하려면 기본 `execute-api` 엔드포인트를 비활성화합니다. 클라이언트는 여전히 기본 엔드포인트에 연결할 수 있지만 `403 Forbidden` 상태 코드를 받게 됩니다. 기본 엔드포인트를 비활성화하면 API의 모든 스테이지에 영향이 미칩니다. 이 설정은 스테이지에서 배포를 업데이트하는 등 스테이지의 설정을 업데이트할 때 적용됩니다.
다음 절차는 REST API의 기본 엔드포인트를 비활성화하는 방법을 보여 줍니다.
------
#### [ AWS Management Console ]
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. REST API를 선택합니다.
1. 기본 탐색 창에서 **API 설정**을 선택합니다.
1. API를 선택합니다.
1. **API 세부 정보** 탭에서 **편집**을 선택합니다.
1. **기본 엔드포인트**에서 **비활성**을 선택합니다.
1. **변경 사항 저장**을 선택합니다.
1. 기본 탐색 창에서 **리소스**를 선택합니다.
1. **Deploy API(API 배포)**를 선택합니다.
1. 업데이트를 적용하려면 API를 스테이지에 재배포하거나 스테이지의 설정을 업데이트합니다.
------
#### [ AWS CLI ]
다음 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 명령은 기본 엔드포인트를 비활성화합니다.
```
aws apigateway update-rest-api \
--rest-api-id abcdef123 \
--patch-operations op=replace,path=/disableExecuteApiEndpoint,value='True'
```
기본 엔드포인트를 비활성화한 후 변경 사항을 적용하려면 API를 배포해야 합니다.
다음 [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) 명령은 배포를 생성하고 이를 다음 스테이지와 연결합니다.
```
aws apigateway create-deployment \
--rest-api-id abcdef123 \
--stage-name dev
```
------
# API Gateway API에 DNS 장애 조치에 대한 사용자 지정 상태 확인 구성
Amazon Route 53 상태 확인을 사용하여 기본 AWS 리전의 API Gateway API에서 보조 리전에 있는 API Gateway API로의 DNS 장애 조치를 제어할 수 있습니다. 이는 리전 문제 발생 시 영향을 완화하는 데 도움이 될 수 있습니다. 사용자 지정 도메인을 사용하는 경우 클라이언트가 API 엔드포인트를 변경하지 않고도 장애 조치를 수행할 수 있습니다.
별칭 레코드로 [Evaluate Target Health](https://docs.aws.amazon.com/Route53/latest/APIReference/API_AliasTarget.html#Route53-Type-AliasTarget-EvaluateTargetHealth>Evaluate Target Health)(대상 상태 평가)를 선택하면 해당 레코드는 해당 리전에서 API Gateway 서비스를 사용할 수 없는 경우에만 실패합니다. 경우에 따라 자체 API Gateway API가 그 이전에 중단될 수 있습니다. DNS 장애 조치를 직접 제어하려면 API Gateway API에 대한 사용자 지정 Route 53 상태 확인을 구성하세요. 이 예시에서는 운영자가 DNS 장애 조치를 제어하는 데 도움이 되는 CloudWatch 경보를 사용합니다. 장애 조치 구성을 위한 더 많은 예제 및 기타 고려 사항은 [Route 53을 사용한 재해 복구 메커니즘 생성](https://aws.amazon.com/blogs/networking-and-content-delivery/creating-disaster-recovery-mechanisms-using-amazon-route-53/)과 [AWS Lambda 및 CloudWatch를 사용하여 VPC의 프라이빗 리소스에 대한 Route 53 상태 확인 수행](https://aws.amazon.com/blogs/networking-and-content-delivery/performing-route-53-health-checks-on-private-resources-in-a-vpc-with-aws-lambda-and-amazon-cloudwatch/)을 참조하세요.
**Topics**
+ [사전 조건](#dns-failover-prereqs)
+ [1단계: 리소스 설정](#dns-failover-intial-setup)
+ [2단계: 보조 리전으로의 장애 조치 시작](#dns-failover-initiate)
+ [3단계: 장애 조치 테스트](#dns-failover-test)
+ [4단계: 기본 리전으로 돌아가기](#dns-failover-return)
+ [다음 단계: 사용자 지정 및 정기적인 테스트](#dns-failover-next-steps)
## 사전 조건
이 절차를 완료하려면 다음 리소스를 만들고 구성해야 합니다.
+ 자신이 소유한 웹 도메인
+ 두 AWS 리전에 있는 해당 도메인 이름에 대한 ACM 인증서. 자세한 내용은 [사용자 지정 도메인 이름에 대한 사전 조건](how-to-custom-domains.md#how-to-custom-domains-prerequisites) 섹션을 참조하세요.
+ 도메인 이름을 위한 Route 53 호스팅 영역. 자세한 내용은 Amazon Route 53 개발자 안내서의 [호스팅 영역 작업](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html) 섹션을 참조하세요.
도메인 이름에 대한 Route 53 장애 조치 DNS 레코드를 생성하는 방법에 대한 자세한 내용은 Amazon Route 53 개발자 안내서의 [라우팅 정책 선택](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html)을 참조하세요. CloudWatch 경보를 모니터링하는 방법에 대한 자세한 내용은 Amazon Route 53 개발자 안내서의 [CloudWatch 경보 모니터링](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/health-checks-creating-values.html#health-checks-creating-values-cloudwatch)을 참조하세요.
## 1단계: 리소스 설정
이 예에서는 다음 리소스를 생성하여 도메인 이름에 대한 DNS 장애 조치를 구성합니다.
+ 두 AWS 리전에 있는 API Gateway API
+ 두 AWS 리전에 있는 이름이 같은 API Gateway 사용자 지정 도메인 이름
+ API Gateway API를 사용자 지정 도메인 이름에 연결하는 API Gateway API 매핑
+ 도메인 이름에 대한 Route 53 장애 조치 DNS 레코드
+ 보조 리전의 CloudWatch 경보
+ 보조 리전의 CloudWatch 경보를 기반으로 하는 Route 53 상태 확인
먼저 기본 및 보조 리전에 필요한 모든 리소스가 있는지 확인하세요. 보조 리전에는 알람 및 상태 확인이 포함되어야 합니다. 이렇게 하면 장애 조치를 수행하기 위해 기본 리전에 의존하지 않아도 됩니다. 이러한 리소스를 만드는 예제 CloudFormation 템플릿은 [samples/primary.zip](samples/primary.zip) 및 [samples/secondary.zip](samples/secondary.zip) 섹션을 참조하세요.
**중요**
보조 리전으로 장애 조치하기 전에 필요한 리소스를 모두 사용할 수 있는지 확인하세요. 그렇지 않으면 API가 보조 리전의 트래픽을 수용할 준비가 되지 않습니다.
## 2단계: 보조 리전으로의 장애 조치 시작
다음 예에서 대기 리전은 CloudWatch 지표를 수신하고 장애 조치를 시작합니다. 장애 조치를 시작하기 위해 운영자의 개입이 필요한 사용자 지정 메트릭을 사용합니다.
```
aws cloudwatch put-metric-data \
--metric-name Failover \
--namespace HealthCheck \
--unit Count \
--value 1 \
--region us-west-1
```
구성한 CloudWatch 경보에 해당하는 데이터로 지표 데이터를 바꿉니다.
## 3단계: 장애 조치 테스트
API를 호출하고 보조 리전으로부터 응답이 수신되는지 확인하세요. 1단계에서 예제 템플릿을 사용한 경우 장애 조치 후 응답이 `{"message": "Hello from the secondary Region!"}`에서 `{"message": "Hello from the primary Region!"}`으로 변경됩니다.
```
curl https://my-api.example.com
{"message": "Hello from the secondary Region!"}
```
## 4단계: 기본 리전으로 돌아가기
기본 리전으로 돌아가려면 상태 확인을 통과하도록 하는 CloudWatch 지표를 전송하세요.
```
aws cloudwatch put-metric-data \
--metric-name Failover \
--namespace HealthCheck \
--unit Count \
--value 0 \
--region us-west-1
```
구성한 CloudWatch 경보에 해당하는 데이터로 지표 데이터를 바꿉니다.
API를 호출하고 기본 리전으로부터 응답이 수신되는지 확인하세요. 1단계에서 예제 템플릿을 사용한 경우 응답이 `{"message": "Hello from the primary Region!"}`에서 `{"message": "Hello from the secondary Region!"}`으로 변경됩니다.
```
curl https://my-api.example.com
{"message": "Hello from the primary Region!"}
```
## 다음 단계: 사용자 지정 및 정기적인 테스트
이 예제에서는 DNS 장애 조치를 구성하는 한 가지 방법을 보여줍니다. 장애 조치를 관리하는 상태 확인에 다양한 CloudWatch 지표 또는 HTTP 엔드포인트를 사용할 수 있습니다. 장애 조치 메커니즘을 정기적으로 테스트하여 예상대로 작동하는지, 운영자가 장애 조치 절차를 잘 알고 있는지 확인하세요.