원타임 APPKEY

APPKEY의 안전한 취급

APPKEY는 애플리케이션이 AmiVoice API를 이용할 때의 '서비스 인증 키 문자열'로, 유출될 경우 악용될 우려가 있습니다. APPKEY를 애플리케이션에 내장하면 악의적인 제3자에 의해 애플리케이션에서 APPKEY가 추출될 가능성이 있습니다. 일반적으로 자신이 소유한 APPKEY를 애플리케이션 사용자의 기기로 전송하지 마십시오. 대신 유출되어도 영향 범위를 최소화할 수 있도록 유효 기간이 있는 원타임 APPKEY를 사용하십시오.

노트

원타임 APPKEY는 마이페이지에 기재된 APPKEY와 동일한 기능을 가진 '서비스 인증 키 문자열'이지만, '발행 일시와 유효 시간'에 기반하여 '유효 기간 일시'가 설정되어 있다는 점이 다릅니다. 또한, 접속 IP 주소에 제한을 둘 수 있습니다.
원타임 APPKEY의 발행 수에는 제한이 없습니다.

주의

특히 웹 애플리케이션의 경우, HTML이나 JavaScript에 APPKEY를 기재하면 웹사이트 사용자가 볼 수 있으므로 피해주십시오.
APPKEY를 애플리케이션에 내장하는 것을 피할 수 없는 경우에는 APPKEY를 난독화, 암호화해주십시오. 난독화, 암호화를 통해 애플리케이션에서 APPKEY를 추출하기 어렵게 만들 수 있습니다.
APPKEY는 변경할 수 없습니다. 변경하려면 탈퇴 후 새로운 계정을 만들어야 합니다.
무기한으로 발행한 원타임 APPKEY는 마이페이지의 APPKEY와 마찬가지로 변경이나 무효화가 불가능하므로 발행 시 충분한 검토 후 사용해주십시오.

원타임 APPKEY 사용하기

원타임 APPKEY를 사용할 경우, 다음과 같은 구현 방법을 고려할 수 있습니다.

애플리케이션 사용자를 어떤 방법으로든 인증합니다
인증에 성공한 후, 서버 측에서 유효 기간을 설정한 원타임 APPKEY를 발행하여 애플리케이션으로 전송합니다
애플리케이션에서는 원타임 APPKEY를 사용하여 AmiVoice API를 이용합니다

다음은 원타임 APPKEY 발행 API의 사용 방법을 설명합니다.

요청

원타임 APPKEY 발행 API를 사용하려면 서비스 ID(쿼리 파라미터 이름은 sid)와 서비스 비밀번호(spw)의 설정이 필요합니다. 마이페이지의 '접속 정보'의 '공통 접속 정보'에 기재된 [서비스 ID]와 [서비스 비밀번호]를 설정해주십시오.

노트

서비스 비밀번호와 마이페이지 로그인용 비밀번호는 다릅니다.

유효 시간(쿼리 파라미터 이름은 epi)은 임의로 설정할 수 있습니다. epi에 숫자로 설정하는 경우 밀리초 단위가 됩니다. 기타 설정 방법은 참조를 확인해주십시오. epi를 생략한 경우 기본값으로 30000(30초)이 설정됩니다. 원타임 APPKEY를 발행한 후 실제로 AmiVoice API 요청을 전송할 때까지의 시간을 예상하여 설정해주십시오. ipa에 APPKEY를 사용할 수 있는 IP 주소를 지정할 수 있습니다.

curl 명령어를 사용하여 원타임 APPKEY를 발행해보겠습니다.

예시1

IP 주소 203.0.113.253에서의 접속만 제한하고, 유효 기간을 발행으로부터 30초 후로 설정합니다.

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={서비스ID} \
     -d spw={서비스비밀번호} \
     -d epi=30000 \
     -d ipa=203.0.113.253

예시2

IP 주소를 범위로 지정하여 허용하고 싶은 경우, CIDR로 지정할 수 있습니다.

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={서비스ID} \
     -d spw={서비스비밀번호} \
     -d epi=30000 \
     -d ipa=203.0.113.0/24

예시3

IP 주소나 그 범위는 쉼표로 구분하여 여러 개 지정할 수도 있습니다.

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={서비스ID} \
     -d spw={서비스비밀번호} \
     -d epi=30000 \
     -d ipa=203.0.113.0/24,198.51.100.0/24

응답

응답은 일반 텍스트로, 원타임 APPKEY를 반환합니다. 그대로 요청 파라미터의 authorization 키로 설정할 수 있습니다.

오류 시 대처 방법

원타임 APPKEY로 인한 연결 인증 실패 사례

지연(기간 만료)으로 인한 인증 오류

authorization 키에 의한 인증 요청을 받는 시점이 원타임 APPKEY에 설정된 유효 기간 일시를 지난 경우, 음성 인식 서비스는 다음과 같은 오류를 반환하므로 다시 원타임 APPKEY를 취득하여 재시도해주십시오.

HTTP 인터페이스의 오류 응답

{
    "code":"-"
    "message":"received illegal service authorization"
}

WebSocket 인터페이스의 오류 응답

s service authorization has expired: 20XX/XX/XX XX:XX:XX.000 +0000 (-21s)

s 응답에 포함된 20XX/XX/XX XX:XX:XX.000은 원타임 APPKEY의 유효 기간 일시, -21s는 유효 기간으로부터의 지연 시간입니다.

s 명령 응답 패킷에서는 오류가 발생하지 않은 경우에도 첫 번째 p 패킷 전송까지 시간이 경과하여 유효 기간 일시를 지나버린 경우에는 첫 번째 p 패킷 전송 직후에 다음과 같은 오류 응답이 반환됩니다.

p can't feed audio data to recognizer server

p 패킷 전송 시작이 성공한 후에는 중간에 유효 기간이 만료되지 않습니다.

잘못된 ID로 인한 인증 오류

원타임 APPKEY 발행 API에 지정하는 서비스 ID・서비스 비밀번호가 잘못된 경우에도 원타임 APPKEY는 발행됩니다. AmiVoice API 요청 시 잘못된 서비스 ID, 비밀번호로 생성된 부적절한 원타임 APPKEY를 지정하면 다음과 같은 인증 오류를 반환합니다.

HTTP 인터페이스의 오류 응답

{
    "code":"-"
    "message":"received illegal service authorization"
}

WebSocket 인터페이스의 오류 응답

s can't verify service authorization

이 경우에는 원타임 APPKEY 발행 요청 시 지정하는 서비스 ID(sid), 서비스 비밀번호(spw)가 올바른 값인지 확인해주십시오.

원타임 APPKEY 발행 API의 자세한 내용은 참조의 원타임 APPKEY 발행 API를 참조해주십시오.

비동기 HTTP 인터페이스에서 원타임 APPKEY를 사용하는 경우

비동기 HTTP 인터페이스에서 원타임 APPKEY를 사용하는 경우에는 유효 기간을 충분히 길게 설정해주십시오. 일반적으로 음성 인식 시작까지 몇 분의 시간이 소요됩니다. 또한, 혼잡 시에는 매우 드물게 일단 중지했다가 재개하는 경우도 있어 인식 중에도 인증이 필요할 수 있습니다.

APPKEY의 안전한 취급​

원타임 APPKEY 사용하기​

요청​

응답​

오류 시 대처 방법​

원타임 APPKEY로 인한 연결 인증 실패 사례​

지연(기간 만료)으로 인한 인증 오류​

잘못된 ID로 인한 인증 오류​

비동기 HTTP 인터페이스에서 원타임 APPKEY를 사용하는 경우​