Amazon API Gateway
개발자 안내서

API Gateway의 API에 대한 사용자 지정 도메인 이름 설정

참고

이제 귀하의 API가 지원하는 최소 TLS 버전을 선택할 수 있습니다. REST API의 경우 TLS 1.2 또는 TLS 1.0을 선택할 수 있습니다. WebSocket API의 경우 TLS 1.2만 선택할 수 있습니다.

REST 또는 WebSocket API를 배포한 후 사용자 및 사용자 고객은 다음 형식의 기본 URL을 사용하여 API를 호출할 수 있습니다.

https://api-id.execute-api.region.amazonaws.com/stage

여기에서 api-id는 API Gateway로 생성되고 region은 API를 생성할 때 사용자가 지정하며 stage는 API를 배포할 때 사용자가 지정합니다.

참고

사용자 지정 도메인은 REST API 또는 Websocket API와 연결할 수 있지만 둘 다 연결할 수는 없습니다.

사용자 지정 도메인 이름은 프라이빗 API에 사용할 수 없습니다.

URL의 호스트 이름 부분(즉 api-id.execute-api.region.amazonaws.com)은 API 엔드포인트를 가리키는데, 이 엔드포인트는 엣지 최적화 또는 리전 엔드포인트일 수 있습니다. 기본 API 엔드포인트는 기억하기가 어려우며 사용자에게 친숙하지 않을 수 있습니다. API 사용자에게 더 단순하고 직관적인 URL을 제공하기 위해 사용자 지정 도메인 이름(예: api.example.com)을 API의 호스트 이름으로 설정하고 기본 경로(예: myservice)를 선택하여 이 API에 대체 URL을 매핑할 수 있습니다. 더 사용자 친화적인 API 기본 URL은 이제 다음과 같습니다.

https://api.example.com/myservice

사용자 지정 도메인 이름으로 기본 매핑을 설정하지 않는 경우 그 결과로 얻는 API의 기본 URL은 사용자 지정 도메인(예: https://api.example.com)과 동일합니다. 이 경우 사용자 지정 도메인 이름은 API를 하나 이상은 지원할 수 없습니다.

엣지 최적화 API를 배포하면 API Gateway는 Amazon CloudFront 배포 및 DNS 레코드를 설정하여 API 도메인 이름을 CloudFront 배포 도메인 이름으로 매핑합니다. 그러면 API에 대한 요청은 매핑된 CloudFront 배포를 통해 API Gateway로 라우팅됩니다.

엣지 최적화 API에 대해 사용자 지정 도메인 이름을 생성하면 API Gateway는 CloudFront 배포를 설정합니다. 그러나 매핑된 CloudFront 배포를 통해 API Gateway로 라우팅될 사용자 지정 도메인 이름이 목적지인 API 요청에 대한 CloudFront 배포 도메인 이름으로 사용자 지정 도메인 이름을 매핑하도록 DNS 레코드를 설정해야 합니다. 또한 사용자 지정 도메인 이름에 대한 인증서를 제출해야 합니다.

리전 API에 대해 사용자 지정 도메인 이름을 생성하면 API Gateway는 해당 API에 대해 리전 도메인 이름을 생성합니다. 매핑된 리전 API 엔드포인트를 통해 API Gateway로 라우팅될 사용자 지정 도메인 이름이 목적지인 API 요청에 대한 리전 도메인 이름으로 사용자 지정 도메인 이름을 매핑하도록 DNS 레코드를 설정해야 합니다. 또한 사용자 지정 도메인 이름에 대한 인증서를 제출해야 합니다.

참고

API Gateway에서 생성한 CloudFront 배포는 API Gateway와 연결된 리전별 계정에서 소유합니다. CloudWatch 로그의 CloudFront 배포 같이 생성 및 업데이트할 작업을 추적할 때 이 API Gateway 계정 ID를 사용해야 합니다. 자세한 내용은 CloudTrail에서 사용자 지정 도메인 이름 생성 로그 단원을 참조하십시오.

엣지 최적화 사용자 지정 도메인 이름을 설정하거나 해당 인증서를 업데이트하려면 CloudFront 배포를 업데이트할 수 있는 권한이 있어야 합니다. 다음 IAM 정책 명령문을 계정의 IAM 사용자, 그룹 또는 역할에 연결하여 이를 수행할 수 있습니다.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCloudFrontUpdateDistribution", "Effect": "Allow", "Action": [ "cloudfront:updateDistribution" ], "Resource": [ "*" ] } ] }

API Gateway는 CloudFront 배포에서 SNI(Server Name Indication)를 활용하여 엣지 최적화 사용자 지정 도메인 이름을 지원합니다. 인증서 키 길이의 필수 인증서 형식 및 최대 크기를 포함하여 CloudFront 배포에서 사용자 지정 도메인 이름 사용에 대한 자세한 내용은 Amazon CloudFront 개발자 안내서 대체 도메인 이름 및 HTTPS 사용 단원을 참조하십시오.

사용자 지정 도메인 이름을 API의 호스트 이름으로 설정하려면 API 소유자인 사용자가 사용자 지정 도메인 이름에 대한 SSL/TLS 인증서를 제공해야 합니다.

엣지 최적화 사용자 지정 도메인 이름에 대한 인증서를 제출하기 위해 AWS Certificate Manager(ACM)에게 ACM에서 새 인증서를 생성하거나 us-east-1 리전(북부 버지니아)의 타사 인증 기관에서 발행한 인증서를 ACM로 가져오도록 요청할 수 있습니다.

ACM을 지원하는 리전에서 리전 사용자 지정 도메인 이름에 대한 인증서를 제출하려면 ACM에 인증서를 요청해야 합니다. ACM을 지원하지 않는 리전에서 리전 사용자 지정 도메인 이름에 대한 인증서를 제출하려면 그 리전의 API Gateway로 인증서를 가져와야 합니다.

SSL/TLS 인증서를 가져오려면 PEM 형식의 SSL/TLS 인증서 본문, 해당하는 프라이빗 키 및 사용자 지정 도메인 이름에 대한 인증서 체인을 제공해야 합니다. ACM에 저장된 각 인증서는 ARN으로 식별됩니다. 도메인 이름에 대해 AWS에서 관리하는 인증서를 사용하려면 해당 ARN을 참조해야 합니다.

ACM은 API에 대한 사용자 지정 도메인 이름을 쉽게 설정 및 사용할 수 있게 해줍니다. 즉 지정된 도메인 이름에 대한 인증서를 ACM에서 생성하거나 가져오고, ACM에서 제공한 인증서의 ARN을 사용하여 API Gateway에서 도메인 이름을 설정하며, 사용자 지정 도메인 이름 아래의 기본 경로를 API의 배포된 단계로 매핑합니다. ACM에서 발행한 인증서를 사용하면 프라이빗 키 같은 민감한 인증서 세부 정보의 공개를 걱정할 필요가 없습니다.

API에 대한 사용자 지정 도메인 이름을 설정하려면 등록된 인터넷 도메인 이름이 있어야 합니다. 필요한 경우 Amazon Route 53을 사용하거나 사용자가 선택한 타사 도메인 등록부를 사용하여 인터넷 도메인을 등록할 수 있습니다. API의 사용자 지정 도메인 이름은 하위 도메인의 이름이거나 등록된 인터넷 도메인의 하위 도메인(즉 zone apex)일 수 있습니다.

API Gateway에서 사용자 지정 도메인 이름이 생성된 후 DNS(도메인 이름 서비스) 제공자의 리소스 레코드를 생성 또는 업데이트하여 엣지 최적화 사용자 지정 도메인 이름을 해당CloudFront 배포 도메인 이름에 매핑하거나 리전 사용자 지정 도메인 이름을 해당 리전 API 엔드포인트에 매핑해야 합니다. 이렇게 매핑하지 않으면 사용자 지정 도메인 이름이 목적지인 API 요청은 API Gateway에 도달할 수 없습니다.

참고

엣지 최적화 사용자 지정 도메인 이름은 특정 리전에서 생성되고 특정 AWS 계정이 소유합니다. 리전 또는 AWS 계정 간에 그러한 사용자 지정 도메인 이름을 이동하는 데는 기존 CloudFront 배포를 삭제하고 새 배포를 생성하는 작업이 수반됩니다. 새 사용자 지정 도메인 이름을 사용할 수 있게 될 때까지 프로세스는 약 30분 정도 걸릴 수 있습니다. 자세한 정보는 CloudFront 배포 업데이트 단원을 참조하십시오.

다음 페이지에서는 ACM을 사용하여 사용자 지정 도메인 이름에 대한 SSL/TLS 인증서를 생성하고, API에 대한 사용자 지정 도메인 이름을 설정하고, 특정 API를 사용자 지정 도메인 이름의 기본 경로에 연결하며, 사용자 지정 도메인 이름에 대해 ACM으로 가져온 만료 인증서를 갱신(즉, 교체)하는 방법을 설명합니다.