고유의 CloudFront 배포를 사용하여 API Gateway를 설정하려면 어떻게 해야 하나요?

7분 분량

Amazon API Gateway에서의 엣지 최적화 API 엔드포인트를 원하지만, Amazon CloudFront 배포에 대하여 더 많은 제어가 필요합니다. 고유의 배포를 생성하여 사용하려면 어떻게 해야 하나요?

간략한 설명

API 클라이언트가 지리적으로 분산된 경우 API Gateway에서 엣지 최적화 API 엔드포인트 사용을 고려하세요. 이 유형의 엔드포인트는 AWS 관리형 CloudFront 웹 배포가 있는 리전 엔드포인트 역할을 하여 클라이언트 연결 시간을 개선합니다.

글로벌 CloudFront 콘텐츠 전송 네트워크를 사용하고 배포에 대하여 더 많은 제어를 유지하려면 사용자 지정 CloudFront 웹 배포와 함께 리전 API를 사용하세요.

해결 방법

API Gateway에서 리전 API를 생성합니다. 이어서, 다음 작업을 수행합니다.

API에 대한 GET 메서드 설정

1. API Gateway 콘솔에서 새 리전 API의 이름을 선택합니다.

2. [리소스(Resources)] 창에서 [작업(Actions)]을 선택합니다. 그런 다음, [메서드 생성(Create Method)]을 선택합니다. / resource 노드 하위에 목록이 나타납니다.

3. 목록에서 [GET] 선택합니다. 그런 다음, 확인 표시 아이콘을 선택합니다.

4. / - GET - Setup에서 [통합 유형(Integration type)]으로 [모의(Mock)]를 선택합니다. 이어서 [저장(Save)]을 선택합니다.
참고: 모의(Mock) 통합은 도달하는 모든 요청에 응답하며, 테스트에서 유용합니다.

API 배포 및 API의 호출 URL 식별

1. API를 단계에 배포합니다.

2. [단계 편집기(Stage Editor)] 창 상단에서 [호출 URL(Invoke URL)]을 클립보드에 복사합니다.

API Gateway API 호출 URL 예시

https://restApiId.execute-api.region.amazonaws.com/stageName.

귀하의 API에 대한 200 OK 응답 테스트

귀하의 API가 200 OK 응답을 반환하는지 확인하려면 API Gateway 콘솔, Postman 앱 또는 curl을 사용하여 API의 호출 URL을 테스트합니다.

curl을 사용하여 귀하의 API에 대한 200 OK 응답을 테스트하려면

운영 체제에 따라 다음 중 하나의 명령을 실행하세요.

참고: 다음 명령 중 하나를 실행하기 전에 https://restApiId.execute-api.region.amazonaws.com/stageName을 API의 호출 URL로 바꿉니다.

Linux의 경우, 다음 명령을 실행합니다.

curl -IX GET https://restApiId.execute-api.region.amazonaws.com/stageName

Windows PowerShell의 경우, 다음 명령을 실행합니다.

curl https://restApiId.execute-api.region.amazonaws.com/stageName

참고: 200 OK 응답 이외의 상태 코드를 받으면 콘솔을 체크하여 다음을 확인하세요.
API가 단계에 배포되었습니다.
단계가 호출 URL에 지정되어 있습니다.

CloudFront 웹 배포 생성

1. CloudFront 콘솔에서 **Create Distribution(배포 생성)**을 선택합니다.

2. [콘텐츠 제공 방법 선택(Select a delivery method for your content)] 페이지의 [웹(Web)] 아래에서 [시작하기(Get Started)]를 선택합니다.

3. [배포 생성(Create Distribution)] 페이지의 [오리진 도메인 이름(Origin Domain Name)]에 API의 호출 URL을 붙여 넣습니다. 그런 다음, 단계 이름을 삭제합니다.

오리진 도메인 이름 예시

https://1a2bc3d456.execute-api.us-east-1.amazonaws.com

4. [오리진 경로(Origin Path)]에 API의 단계 이름을 앞에 슬래시를 붙여(/stageName) 입력합니다. 또는 URL을 호출할 때 단계 이름을 직접 입력하려는 경우 **오리진 경로(Origin Path)**를 입력해선 안됩니다.
참고: CloudFront 배포를 호출할 때 오리진 경로에 잘못된 단계 이름을 입력하면 오류가 발생하는 경우가 있습니다. 예: “인증 토큰 누락(Missing Authentication Token)” 메시지와 403 Forbidden 응답 코드를 반환하는 무단 요청 오류.

5. **최소 오리진 SSL 프로토콜(Minimum Origin SSL Protocol)**에는 TLSv1.2를 선택하는 것이 좋습니다. SSLv3은 선택하지 마세요. API Gateway는 SSLv3 프로토콜을 지원하지 않습니다.

6. [오리진 프로토콜 정책(Origin Protocol Policy)]에서 [HTTPS만(HTTPS Only)]을 선택합니다.
참고: API Gateway는 암호화되지 않은(HTTP) 엔드포인트를 지원하지 않습니다. 자세한 내용은 Amazon API Gateway FAQ를 참조하십시오.

7. (선택 사항) 사용자 지정 헤더를 오리진에 전달하려면 [오리진 사용자 지정 헤더(Origin Custom Headers)]에 하나 이상의 사용자 지정 헤더를 입력합니다.
참고: CloudFront가 오리진에 전달할 수 없는 몇 가지 사용자 지정 헤더가 있습니다.

8. API에 IAM 인증을 사용하고 있거나 배포에 사용자 지정 도메인 이름을 사용하는 경우 섹션의 지침을 따릅니다(해당하는 경우).

9. (선택 사항) [배포 설정(Distribution Settings)]에서 사용자 지정할 추가 설정을 구성합니다.

10. [배포 생성(Create Distribution)]을 선택합니다.

11. 배포가 완료될 때까지 기다립니다. 이 작업에는 15~20분이 소요됩니다 콘솔에서 **상태(Status)**가 **배포 완료(Deployed)**로 나타나면 배포가 준비된 것입니다.

자세한 내용은 배포 생성을 참조하세요.

CloudFront 웹 배포 테스트

1. CloudFront 콘솔에서 배포의 도메인 이름을 클립보드에 복사합니다.

비사용자 지정 도메인 이름 예시

a222222bcdefg5.cloudfront.net.

2. API 테스트 섹션에서 앞서 언급한 명령 중 하나를 사용하여 도메인 이름에 대한 200 OK 응답을 테스트합니다. 500 서버 오류 코드를 받는 경우 배포가 완료되지 않은 것일 수 있습니다. 응답을 받지 못한 경우 CloudFront DNS 레코드가 아직 전파되지 않은 것일 수 있습니다. 두 경우 모두, 배포 생성 후 15~20분이 경과했는지 확인합니다. 그런 다음, 절차를 다시 시도하세요.

중요: 특정 API 리소스에 대한 메서드에서 AWS Identity and Access Management(IAM) 인증을 활성화한 경우 API를 호출할 때 배포 도메인 이름의 끝에 리소스 이름을 추가해야 합니다. 전체 호출 URL(리소스 이름 포함)은 다음 예시 중 하나와 유사합니다. 출력은 배포를 만들 때 오리진 경로를 입력했는지 여부에 따라 달라집니다.

오리진 경로가 있는 API Gateway API 호출 URL 예시

https://distributionDomainName/stageName/resourceName

오리진 경로가 없는 API Gateway API 호출 URL 예시

https://distributionDomainName/resourceName

테스트에 대한 자세한 내용은 API Gateway API에 대한 IAM 인증을 활성화하려면 어떻게 해야 합니까?를 참조하세요.

이제 API는 생성한 웹 배포를 사용합니다. 리소스는 API CloudFront URL에서 액세스할 수 있습니다.

API에 IAM 인증을 사용하거나 CloudFront 웹 배포에 사용자 지정 도메인 이름을 사용하는 경우

기본적으로 CloudFront는 수신 Authorization 헤더를 오리진에 전달하지 않습니다 (이 사용 사례의 경우 API Gateway). API에 IAM 인증을 사용하거나 배포에 사용자 지정 도메인 이름을 사용하는 경우 다음 중 하나를 수행해야 합니다.

(IAM 인증의 경우) CloudFront 허용 목록에 권한 부여 헤더를 추가합니다.

1. 앞에서 완료하지 않은 경우 이 문서의 CloudFront 웹 배포 생성 섹션에 있는 1~7단계를 따릅니다.

2. [배포 생성(Create Distribution)] 페이지의 [캐시 및 오리진 요청 설정(Cache and origin request settings)]에서 [캐시 정책 및 오리진 요청 정책 사용(Use a cache policy and origin request policy)]을 선택합니다. 그런 다음 [캐시 정책(Cache Policy)]에서 기존 캐시 정책을 선택하거나 CloudFront 허용 목록에 Authorization 헤더를 추가하는 새 캐시 정책을 생성합니다.

3. 기존 캐시 정책을 사용하는 경우 [선택한 요청 헤더 기반의 캐시(Cache Based on Selected Request Headers)]에서 [화이트리스트(Whitelist)]를 선택합니다. [화이트리스트 헤더(Whitelist Headers)]에서 [Authorization]을 허용 헤더 목록에 추가합니다.

중요: [선택한 요청 헤더에 기반한 캐시(Cache Based on Selected Request Headers)] 설정을 [모두(All)]로 변경하거나 [호스트(Host)] 헤더를 허용하면 설정이 작동하지 않습니다. 자세한 내용은 요청 헤더 기반 콘텐츠 캐싱을 참조하세요.

4. (선택 사항) 설정을 테스트하려면 다음을 수행합니다.
프로그래밍 방식으로 API Gateway 엔드포인트에 필요한 Signature 버전 4 서명을 생성합니다 . 호스트 값에 API Gateway 호출 URL을 입력합니다. 엔드포인트 값에 CloudFront 웹 배포 URL을 입력합니다.

API Gateway 호출 URL 예시

<api-id>.execute.<region>.amazon.com

CloudFront 웹 배포 URL 예시

dxxxxx.cloudfront.net

참고: Postman 앱을 사용하는 경우 권한 부여(Authorization) 탭의 **유형(Type)**에서 AWS Signature를 선택합니다. 그런 다음 액세스 키(Access Key) 및 **보안 키(Secret Key)**를 입력합니다. 필요한 헤더는 입력한 보안 인증을 사용하여 Postman이 생성합니다.

그런 다음, Signature 버전 4 프로세스에서 생성된 권한 부여 (Authorization) 헤더(및 모든 SignedHeaders)를 사용하여 CloudFront 배포에 API 요청을 전송합니다.

(사용자 지정 도메인 이름 또는 IAM 인증의 경우) API Gateway에 리전 사용자 지정 도메인 이름을 설정하여 API에 액세스합니다.

1. API Gateway에서 새 리전 API를 생성하거나 엣지 최적화 API Gateway API를 리전 API로 변경합니다.

2. API에 대하여 리전 사용자 지정 도메인 이름을 설정하고 API에 대하여 API 매핑을 생성합니다.
참고: CloudFront를 통해 API에 액세스할 때 이 사용자 지정 도메인 이름을 사용하세요.

3. 한 가지 예외를 제외하고 이 문서의 CloudFront 웹 배포 생성 섹션에 있는 지침에 따라 CloudFront 웹 배포를 생성합니다. 단 한 가지 예외가 있습니다. 3단계에서 **오리진 도메인 이름(Origin Domain Name)**에 API의 호출 URL 대신 API Gateway 대상 도메인 이름을 입력합니다.
참고: API Gateway 대상 도메인 이름은 사용자 지정 도메인 세부 정보의 엔드포인트(Endpoint) 구성에서 찾으세요.

API Gateway 대상 도메인 이름 예시

d-xxxx..execute-api.<region>.amazonaws.com

4. [배포 생성(Create Distribution)] 페이지의 [캐시 및 오리진 요청 설정(Cache and origin request settings)]에서 [캐시 정책 및 오리진 요청 정책 사용(Use a cache policy and origin request policy)]을 선택합니다. 그런 다음 게시 정책에서기존 캐시 정책을 선택하거나 CloudFront 허용 목록에 [권한 부여(Authorization)] 및 [호스트(Host)] 헤더를 추가하는 새 캐시 정책을 생성합니다.

5. 기존 캐시 정책을 사용하는 경우 [선택한 요청 헤더 기반의 캐시(Cache Based on Selected Request Headers)]에서 [화이트리스트(Whitelist)]를 선택합니다. 이어서, [화이트리스트 헤더(Whitelist Headers)]에서 [Authorization(권한 부여)] 및 [호스트(Host)]를 허용 헤더 목록에 추가합니다.

6. [배포 설정(Distribution Settings)] 아래에 있는 [대체 도메인 이름(Alternate Domain Name)]에 생성된 사용자 지정 도메인 이름을 입력합니다.

7. [SSL 인증서(SSL Certificate)]에서 [사용자 지정 SSL 인증서(Custom SSL Certificate)]를 선택합니다. 그런 다음, 해당 도메인에 대한 AWS Certificate Manager(ACM) 인증서를 추가합니다.

CloudFront 웹 배포를 배포한 후 사용자 지정 도메인을 CloudFront 웹 배포에 매핑하도록 DNS 레코드를 구성합니다. 별칭 또는 CNAME 레코드를 생성하여 이 작업을 수행합니다. 자세한 내용은 대체 도메인 이름(CNAME)을 추가하여 파일에 대해 사용자 지정 URL 사용을 참조하세요.

9. (선택 사항) 설정을 테스트하려면 프로그래밍 방식으로 사용자 지정 도메인 이름에 대하여 Signature 버전 4로 서명된 요청을 생성합니다.
참고: Postman 앱을 사용하여 설정을 테스트할 수 있습니다.