API Gateway API에서 엣지 최적화 사용자 지정 도메인 이름 설정 - Amazon API Gateway
고려 사항엣지 최적화 사용자 지정 도메인 이름 생성엣지 최적화 사용자 지정 도메인 이름에 대한 DNS 레코드 생성CloudTrail에서 사용자 지정 도메인 이름 생성 로그사용자 지정 도메인 이름을 호스트 이름으로 사용하여 API의 기본 경로 매핑 구성ACM에 가져온 인증서 교체사용자 지정 도메인 이름을 사용하여 API 호출

API Gateway API에서 엣지 최적화 사용자 지정 도메인 이름 설정

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

고려 사항

다음은 엣지 최적화 사용자 지정 도메인 이름에 대한 고려 사항입니다.

  • 엣지 최적화 사용자 지정 도메인 이름을 설정하거나 해당 인증서를 업데이트하려면 CloudFront 배포를 업데이트할 수 있는 권한이 있어야 합니다.

    CloudFront 배포를 업데이트하려면 다음 권한이 필요합니다.

    {
    "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에서 사용자 지정 도메인 이름 생성 로그 단원을 참조하십시오.

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

  • 엣지 최적화 사용자 지정 도메인 이름은 사용할 수 있을 때까지 약 40분이 소요됩니다.

  • 엣지 최적화 사용자 지정 도메인 이름을 생성한 후에는 사용자 지정 도메인 이름을 CloudFront 배포 이름에 매핑하는 DNS 레코드를 생성해야 합니다.

엣지 최적화 사용자 지정 도메인 이름 생성

다음 절차에서는 API에 대한 엣지 최적화 사용자 지정 도메인 이름을 생성하는 방법을 설명합니다.

AWS Management Console

  1. https://console.aws.amazon.com/apigateway에서 API Gateway 콘솔에 로그인합니다.

  2. 기본 탐색 창에서 사용자 지정 도메인 이름을 선택합니다.

  3. 생성을 선택합니다.

  4. 도메인 이름에 도메인 이름을 입력합니다.

  5. 최소 TLS 버전에서 버전을 선택합니다.

  6. 엔드포인트 구성 아래의 API 엔드포인트 유형에서 엣지 최적화를 선택합니다.

  7. ACM 인증서에서 ACM 인증서를 선택합니다.

  8. 도메인 이름 생성을 선택합니다.

REST API

  1. domainname:create를 호출하여 사용자 지정 도메인 이름과 AWS Certificate Manager에 저장되는 인증서의 ARN을 지정합니다.

    성공적인 API 호출은 페이로드에 인증서 ARN뿐 아니라 연결된 CloudFront 배포 이름을 포함하는 201 Created 응답을 반환합니다.

  2. 출력에 표시된 CloudFront 배포 도메인 이름을 적어 둡니다. 다음 단계인 DNS에서 사용자 지정 도메인의 A 레코드 별칭 대상을 설정할 때 필요합니다.

이 REST API 호출의 코드 예는 domainname:create를 참조하세요.

엣지 최적화 사용자 지정 도메인 이름은 사용할 수 있을 때까지 약 40분이 걸리지만, 콘솔에는 연결된 CloudFront 배포 도메인 이름이 인증서 ARN과 함께 distribution-id.cloudfront.net 형식으로 즉시 표시됩니다. 그 동안 다음 단계를 진행하여 사용자 지정 도메인 이름을 연결된 CloudFront 배포 도메인 이름에 매핑하기 위한 DNS 레코드 별칭을 구성할 수 있습니다.

엣지 최적화 사용자 지정 도메인 이름에 대한 DNS 레코드 생성

엣지 최적화 사용자 지정 도메인 이름을 만들기 시작한 후 DNS 레코드 별칭을 설정합니다.

Route 53를 사용하여 사용자 지정 도메인 이름의 A 레코드 별칭을 생성하고 CloudFront 배포 도메인 이름을 별칭 대상으로 지정하는 것이 좋습니다. 다시 말해서 사용자 지정 도메인이 zone apex라고 하더라도 Route 53은 사용자 지정 도메인 이름을 라우팅할 수 있습니다. 자세한 내용은 Amazon Route 53 개발자 안내서의 별칭 및 비별칭 리소스 레코드 세트 간의 선택에서 확인할 수 있습니다.

Amazon Route 53에 대한 지침은 Amazon Route 53 개발자 안내서에서 도메인 이름을 사용하여 Amazon API Gateway API로 트래픽 라우팅을 참조하세요.

CloudTrail에서 사용자 지정 도메인 이름 생성 로그

계정에서 수행한 API Gateway 호출을 로깅하기 위해 CloudTrail을 활성화한 경우, API에 대한 사용자 지정 도메인 이름을 생성하거나 업데이트할 때 API Gateway는 연결된 CloudFront 배포 업데이트를 기록합니다. 이 로그는 us-east-1에서 사용할 수 있습니다. 이러한 CloudFront 배포는 API Gateway가 소유하므로, 이러한 각 보고된 CloudFront 배포는 API 소유자의 계정 ID 대신 다음과 같은 리전별 API Gateway 계정 ID 중 하나로 식별됩니다.

리전

계정 ID
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

사용자 지정 도메인 이름을 호스트 이름으로 사용하여 API의 기본 경로 매핑 구성

기본 경로 매핑을 사용하여 단일 사용자 지정 도메인 이름을 여러 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 스테이지를 REST API에 대한 사용자 지정 도메인 이름에 매핑 단원을 참조하십시오.

다음 절차에서는 사용자 지정 도메인 이름에서 API 스테이지로 경로를 매핑하도록 API 매핑을 설정합니다.

AWS Management Console

  1. https://console.aws.amazon.com/apigateway에서 API Gateway 콘솔에 로그인합니다.

  2. API Gateway 콘솔 기본 탐색 창에서 Custom Domain Names(사용자 지정 도메인 이름)를 선택합니다.

  3. 사용자 지정 도메인 이름을 선택합니다.

  4. API 매핑 구성을 선택합니다.

  5. Add new mapping(새 매핑 추가)을 선택합니다.

  6. 매핑에 대한 API, 스테이지, 및 경로(선택 사항)를 지정합니다.

  7. Save(저장)를 선택합니다.

REST API

요청 페이로드에서 basePath, restApiId 및 배포 stage 속성을 지정하여 특정 사용자 지정 도메인 이름에 대해 basepathmapping:create를 호출합니다.

성공적인 API 응답은 201 Created 응답을 반환합니다.

REST API 호출의 코드 예는 basepathmapping:create를 참조하세요.

ACM에 가져온 인증서 교체

ACM은 발급한 인증서의 갱신을 자동으로 처리합니다. 사용자 지정 도메인 이름에 대해 ACM이 발급한 인증서는 교체할 필요가 없습니다. CloudFront가 사용자를 대신하여 처리합니다.

하지만 인증서를 ACM에 가져와서 사용자 지정 도메인 이름에 사용할 경우 만료되기 전에 인증서를 교체해야 합니다. 여기에는 도메인 이름에 대한 새 타사 인증서를 가져오고 기존 인증서를 새 인증서로 교체하는 작업이 포함됩니다. 새로 가져온 인증서가 만료되면 이 프로세스를 반복해야 합니다. 또는 도메인 이름에 대한 새 인증서를 발급하도록 ACM에 요청하고 기존 인증서를 ACM에서 발급한 새 인증서로 교체할 수 있습니다. 이후에는 ACM과 CloudFront에서 인증서 교체를 자동으로 처리하도록 둘 수 있습니다. 새 ACM 인증서를 생성하거나 가져오려면 SSL/TLS 인증서를 생성하거나 ACM으로 가져오려면의 단계를 수행합니다.

다음 절차에서는 도메인 이름에 대한 인증서를 교체하는 방법에 대해 설명합니다.

참고

ACM으로 가져온 인증서를 교체하는 데는 약 40분이 소요됩니다.

AWS Management Console

  1. ACM에서 인증서를 요청하거나 가져옵니다.

  2. https://console.aws.amazon.com/apigateway에서 API Gateway 콘솔에 로그인합니다.

  3. API Gateway 콘솔 기본 탐색 창에서 Custom Domain Names(사용자 지정 도메인 이름)를 선택합니다.

  4. 사용자 지정 도메인 이름을 선택합니다.

  5. [Edit]를 선택합니다.

  6. ACM certificate(ACM 인증서) 드롭다운 목록에서 원하는 인증서를 선택합니다.

  7. 저장을 선택하여 사용자 지정 도메인 이름에 대한 인증서 교체를 시작합니다.

  8. 교체가 완료된 후에 ACM 인증서(ACM Certificate) 옆에 있는 양방향 화살표를 선택하여 원래 인증서로 롤백할 수 있습니다.

REST API

지정된 도메인 이름에 대한 새 ACM 인증서의 ARN을 지정하여 domainname:update 작업을 호출합니다.

사용자 지정 도메인 이름을 사용하여 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 Gateway는 SNI(Server Name Indication)를 사용하여 API에 대한 사용자 지정 도메인 이름을 지원합니다. 브라우저 또는 SNI를 지원하는 클라이언트 라이브러리를 사용하여 사용자 지정 도메인 이름이 포함된 API를 호출할 수 있습니다.

API Gateway는 CloudFront 배포에 SNI를 적용합니다. CloudFront에서 사용자 지정 도메인 이름을 사용하는 방법에 대한 자세한 내용은 Amazon CloudFront 사용자 지정 SSL을 참조하세요.