프라이빗 연결(AWS PrivateLink)

중요

AmiVoice API의 AWS PrivateLink 연결을 이용하시려면 미리 신청이 필요합니다. 먼저 문의 양식(Inquiry Form) (영어)을 통해 연락해 주세요.

신청 후, 당사에서 고객님의 AWS 계정에 대한 연결 허가를 설정하고 엔드포인트 서비스명을 안내해 드립니다. 본 섹션에서는 그 후에 고객님의 VPC에서 수행하는 인터페이스 엔드포인트 생성부터, 당사에 의한 연결 승인, 프라이빗 DNS 활성화, 연결 확인까지의 절차에 대해 설명합니다.

개요

AWS PrivateLink는 AWS 상의 시스템에서 외부 서비스로의 통신을 인터넷에 공개하지 않고 AWS 네트워크 내에서 연결할 수 있는 서비스입니다. 인터넷 게이트웨이나 NAT Gateway, 퍼블릭 IP 주소를 준비할 필요가 없어 네트워크 구성을 간단하게 할 수 있습니다. 통신이 인터넷을 경유하지 않으므로 외부에서 접근 가능한 경로를 제공하지 않으며, 안전하게 이용할 수 있습니다.

AmiVoice API는 고객 VPC 내에 생성한 인터페이스 엔드포인트를 통해 연결됩니다. 고객님의 애플리케이션은 기존과 동일한 API key를 사용하여 AmiVoice API를 호출할 수 있습니다.

본 기능은 AmiVoice API Private의 전용 기능이 아닙니다. 일반 버전에서도 이용 조건을 충족하는 경우에 이용하실 수 있습니다.

대상이 되는 인터페이스 / API와 연결 대상

PrivateLink 연결은 AmiVoice API 중 다음 API를 이용할 수 있습니다.

• 음성 인식(동기 HTTP/WebSocket/비동기 HTTP)
• 사용자 사전 관리 (사용자 사전 등록/단어 등록 클래스명 목록 가져오기)
• API Key 발급

연결 대상은 동기 HTTP/WebSocket 등에서 이용하는 연결 대상과 비동기 HTTP의 연결 대상 2가지로 나뉩니다.

이용하는 인터페이스 / API	기존 호스트 이름	PrivateLink 연결 시의 호스트 이름
・동기 HTTP / WebSocket ・사용자 사전 관리 ・API Key 발급	acp-api.amivoice.com	acp-api-private.amivoice.com
・비동기 HTTP	acp-api-async.amivoice.com	acp-api-async-private.amivoice.com

동기 HTTP/WebSocket과 비동기 HTTP를 모두 이용하는 경우에는 각각에 대응하는 VPC 인터페이스 엔드포인트를 생성해 주세요.

마이페이지 등, 상기 이외의 서비스는 계속해서 인터넷을 경유하여 이용하게 됩니다.

연결 가이드

1. 사전 준비

항목	내용
리전	ap-northeast-1(Tokyo)
소스 VPC	엔드포인트를 생성할 VPC
서브넷	엔드포인트를 배치하는 서브넷(복수 AZ 권장)
보안 그룹	엔드포인트용(인바운드 TCP 443을 허가)
VPC의 DNS 설정	DNS 해결 (DNS Resolution)과 DNS 호스트 이름 (DNS hostnames)을 활성화해 둠

VPC의 DNS 설정이 비활성화되어 있으면 후술하는 프라이빗 DNS 이름을 확인할 수 없습니다.

2. 사전 신청

연결 허가를 위해 아래 사항을 당사로 연락해 주세요.

• 고객님의 AWS 계정 ID(12자리)
• 이용하고자 하는 인터페이스 / API
  • 동기 HTTP/WebSocket, 사용자 사전 관리 (사용자 사전 등록/단어 등록 클래스명 목록 가져오기), API Key 발급
  • 비동기 HTTP API

당사에서 허가 설정을 한 후, 사용하시는 인터페이스별로 엔드포인트 서비스 이름을 안내해 드립니다. 이름은 다음 형식입니다.

• com.amazonaws.vpce.ap-northeast-1.vpce-svc-XXXXXXXXXXXX

동기와 비동기를 모두 사용하시는 경우에는 서비스 이름도 2개를 안내해 드립니다.

3. 인터페이스 엔드포인트 생성

안내해 드린 엔드포인트 서비스 이름별로 이 절차를 수행합니다. 동기와 비동기를 모두 사용하시는 경우에는 엔드포인트를 2개 생성하게 됩니다.

주의

생성 시에는 「프라이빗 DNS 이름 활성화」를 활성화하지 마세요. 본 서비스는 연결의 수동 승인이 필요하므로, 승인 전에 프라이빗 DNS를 활성화하려고 하면 다음 오류로 인해 생성에 실패합니다.

Private DNS can only be enabled after the endpoint connection is accepted by the owner ...

프라이빗 DNS는 4. 연결 승인(당사 측) 완료 후에 5. 프라이빗 DNS 이름 활성화의 절차로 활성화합니다.

AWS Management Console의 경우

1. VPC 콘솔 → 엔드포인트 → 엔드포인트 생성
2. 유형: 「NLB와 GWLB를 사용하는 엔드포인트 서비스」를 선택
3. 서비스명에 당사에서 안내한 서비스명을 입력하고 「서비스 검증」을 클릭
   • "서비스명을 찾을 수 없습니다"가 되는 경우 당사 측의 허가 설정이 미완료일 가능성이 있습니다(→ 2. 사전 신청을 확인해 주세요)
4. VPC를 선택
5. 「프라이빗 DNS 이름을 활성화」는 OFF 상태로 유지합니다(체크하지 않음)
6. 엔드포인트를 배치하는 AZ와 서브넷을 선택
7. 보안 그룹을 선택(인바운드 TCP 443을 허가)
8. 엔드포인트 생성

생성 직후에는 연결 상태가「승인 대기 중(Pending acceptance)」이 됩니다.

AWS CLI의 경우

aws ec2 create-vpc-endpoint \
  --vpc-endpoint-type Interface \
  --service-name com.amazonaws.vpce.ap-northeast-1.vpce-svc-XXXXXXXXXXXX \
  --vpc-id <CUSTOMER_VPC_ID> \
  --subnet-ids <subnet-id-1> [<subnet-id-2> ...] \
  --security-group-ids <sg-id> \
  --no-private-dns-enabled \
  --region ap-northeast-1 \
  --tag-specifications 'ResourceType=vpc-endpoint,Tags=[{Key=Name,Value=acp-api-private-ep}]'

엔드포인트를 2개 생성하는 경우, Name 태그를 인터페이스별로 바꿔 두면 나중에 구분하기 쉬워집니다.

4. 연결 승인(당사 측)

고객님이 엔드포인트를 생성하면, 당사 측에서 연결 요청을 받습니다. 당사에서 내용을 확인한 후 승인합니다. 승인 후, 엔드포인트의 상태가 「사용 가능(Available)」으로 변경 됩니다.

노트

승인 과정에는 당사의 확인 작업이 포함되므로 다소 시간이 소요될 수 있습니다. 엔드포인트를 생성한 후 당사에 알려 주시면 보다 원활하게 진행할 수 있습니다.

5. 프라이빗 DNS 이름 활성화

당사에 의한 승인이 완료되고 엔드포인트가「사용 가능(Available)」이 되면 프라이빗 DNS를 활성화합니다. 이를 통해 고객님의 VPC 내에서 PrivateLink 연결 시의 호스트 이름이 생성한 엔드포인트로 자동으로 이름 확인됩니다. 고객님 측에서 Route 53 등의 추가 DNS 설정은 불필요합니다.

엔드포인트를 2개 생성한 경우에는 각각 활성화해 주세요.

AWS Management Console의 경우

1. VPC 콘솔 → 엔드포인트 → 대상 엔드포인트를 선택
2. 작업 → 프라이빗 DNS 이름 변경
3. 「이 엔드포인트에서 프라이빗 DNS 이름을 활성화」를 ON → 저장

AWS CLI의 경우

aws ec2 modify-vpc-endpoint \
  --vpc-endpoint-id <vpce-id> \
  --private-dns-enabled \
  --region ap-northeast-1

노트

• 이 조작을 활성화할 수 있는 것은 당사 측의 도메인 검증이 완료된 경우에만
• VPC의 DNS 해결 (DNS Resolution)과 DNS 호스트 이름 (DNS hostnames)이 활성화되어 있을 것(1. 사전 준비)

6. 연결(Connection) 확인

프라이빗 DNS를 활성화하면 고객님 VPC 내의 인스턴스에서 확인합니다. 엔드포인트를 2개 생성한 경우에는 각각 확인해 주세요.

이름 해결(Name Resolution) 확인

# For Synchronous HTTP and WebSocket
dig +short acp-api-private.amivoice.com

# For Asynchronous HTTP
dig +short acp-api-async-private.amivoice.com

# → 172.x.x.x 등 private IP가 반환되면 OK

음성 인식 API 소통 확인

가지고 계신 음성 파일(예 sample.wav)과 AmiVoice API의 API key를 이용하여 확인합니다. 다음은 동기 HTTP 인터페이스의 예입니다.

curl https://acp-api-private.amivoice.com/v1/recognize \
  -F u={API_KEY} \
  -F d="grammarFileNames=-a-general" \
  -F a=@sample.wav

인식 결과의 JSON(text 필드 등)이 반환되면, 연결은 정상입니다.

비동기 HTTP 인터페이스의 경우에는 호스트 이름을 acp-api-async-private.amivoice.com으로 바꿔 주세요. 절차는 비동기 HTTP 인터페이스를 참조해 주세요.

7. 애플리케이션에서의 이용

연결 확인이 되면 애플리케이션의 AmiVoice API 연결 대상 호스트를 PrivateLink 연결 시의 호스트 이름으로 변경해 주세요. 동기 HTTP와 WebSocket은 acp-api-private.amivoice.com, 비동기 HTTP는 acp-api-async-private.amivoice.com

문제 해결

증상	주요 원인	대처
생성 시에 Private DNS can only be enabled after the endpoint connection is accepted ... 오류	승인 전에 프라이빗 DNS를 활성화하려고 했음	프라이빗 DNS를 OFF로 생성 → 승인 후에 5. 프라이빗 DNS 이름 활성화의 절차로 활성화
「서비스 검증」에서 찾을 수 없음	당사 측의 허가 설정이 미완료	고객님의 AWS 계정 ID를 당사로 연락
연결이 타임아웃됨	엔드포인트의 보안 그룹이 443을 허가하지 않았음	SG의 인바운드에 TCP 443을 추가
프라이빗 DNS 이름을 활성화할 수 없음	당사 측의 도메인 검증이 미완료, 또는 VPC의 DNS 설정이 비활성화	당사로 연락/VPC의 DNS 해결(DNS Resolution)・DNS 호스트명(DNS hostnames)을 활성화
PrivateLink용 호스트명을 확인할 수 없음	프라이빗 DNS 이름이 미활성화, 또는 VPC DNS 설정이 비활성화	5. 프라이빗 DNS 이름 활성화에서 프라이빗 DNS를 활성화/VPC DNS 설정을 확인
상태가 「승인 대기 중(Pending acceptance)」이 지속됨	당사의 승인 대기	당사로 연락
비동기 HTTP만 연결되지 않음	비동기용 엔드포인트를 생성하지 않았음	대상이 되는 인터페이스와 연결 대상을 확인하고 비동기용 엔드포인트도 생성
TLS 인증서 오류	호스트명 이외(IP 직접 지정 등)로 연결하고 있음	반드시 PrivateLink용 호스트명으로 연결

보충 설명

• AWS 측의 VPC 엔드포인트 이용 요금(시간 단위 과금 및 데이터 처리 요금)은 AWS의 요금 체계에 기반하여 고객의 AWS 계정에 과금 됩니다. 인터넷 연결을 위해 NAT Gateway 등을 준비하고 있는 경우에는 해당 비용과 함께 검토가 필요합니다.
• 복수 AZ에 엔드포인트를 배치함으로써 가용성이 향상됩니다.
• 본 구성에서는 API에 접속하는 애플리케이션의 출발지 IP 주소를 AmiVoice API 측에서 관리하지 않고, API key를 통해 고객을 식별합니다.

궁금하신 사항은 당사 지원 창구로 문의 바랍니다.