Speech API 인증Authenticate to the Speech API

Speech Service에서 인증을 지원하기 위해 사용하는 항목은 다음과 같습니다.Speech Service supports authentication by using:

  • 구독 키A subscription key.
  • 권한 부여 토큰An authorization token.

구독 키 사용Use a subscription key

Speech Service를 사용하려면 먼저 Cognitive Services(이전의 Project Oxford)의 일부인 Speech API를 구독해야 합니다.To use Speech Service, you must first subscribe to the Speech API that's part of Cognitive Services (previously Project Oxford). Cognitive Services 구독 페이지에서 평가판 구독 키를 가져올 수 있습니다.You can get free trial subscription keys from the Cognitive Services subscription page. Speech API를 선택한 후에 API 키 가져오기를 선택하여 키를 가져옵니다.After you select the Speech API, select Get API Key to get the key. 기본 및 보조 키를 반환합니다.It returns a primary and secondary key. 두 키는 모두 동일한 할당량에 연결되므로 두 키 중 하나를 사용할 수 있습니다.Both keys are tied to the same quota, so you can use either key.

장기간 사용하거나 할당량을 늘리려면 Azure 계정에 등록합니다.For long-term use or an increased quota, sign up for an Azure account.

Speech REST API를 사용하려면 요청 헤더의 Ocp-Apim-Subscription-Key 필드에 구독 키를 전달해야 합니다.To use the Speech REST API, you need to pass the subscription key in the Ocp-Apim-Subscription-Key field in the request header.

NameName 형식Format 설명Description
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key ASCIIASCII YOUR_SUBSCRIPTION_KEYYOUR_SUBSCRIPTION_KEY

요청 헤더의 예제는 다음과 같습니다.The following is an example of a request header:

POST https://speech.platform.bing.com/speech/recognition/interactive/cognitiveservices/v1?language=en-US&format=detailed HTTP/1.1
Accept: application/json;text/xml
Content-Type: audio/wav; codec=audio/pcm; samplerate=16000
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: speech.platform.bing.com
Transfer-Encoding: chunked
Expect: 100-continue

중요

응용 프로그램에서 클라이언트 라이브러리를 사용하는 경우 다음 섹션에서 설명한 대로 구독 키가 있는 권한 부여 토큰을 가져올 수 있는지 확인합니다.If you use client libraries in your application, verify that you can get the authorization token with your subscription key, as described in the following section. 클라이언트 라이브러리는 구독 키를 사용하여 권한 부여 토큰을 가져온 다음, 이 토큰을 인증에 사용합니다.The client libraries use the subscription key to get an authorization token and then use the token for authentication.

권한 부여 토큰 사용Use an authorization token

또는 인증에서 권한 부여 토큰을 인증/권한 부여의 증명으로 사용할 수 있습니다.Alternatively, you can use an authorization token for authentication as proof of authentication/authorization. 이 토큰을 가져오려면 먼저 앞 섹션에서 설명한 대로 Speech API에서 구독 키를 획득해야 합니다.To get this token, you must first obtain a subscription key from the Speech API, as described in the preceding section.

권한 부여 토큰 가져오기Get an authorization token

유효한 구독 키를 받은 후에 Cognitive Services의 토큰 서비스에 POST 요청을 보냅니다.After you have a valid subscription key, send a POST request to the token service of Cognitive Services. 응답에서 권한 부여 토큰을 JWT(JSON Web Token)로 받습니다.In the response, you receive the authorization token as a JSON Web Token (JWT).

참고

토큰의 만료 기간은 10분입니다.The token has an expiration of 10 minutes. 토큰을 갱신하려면 다음 섹션을 참조하세요.To renew the token, see the following section.

토큰 서비스 URI의 위치는 다음과 같습니다.The token service URI is located here:

https://api.cognitive.microsoft.com/sts/v1.0/issueToken

다음 코드 샘플에서는 액세스 토큰을 가져오는 방법을 보여 줍니다.The following code sample shows how to get an access token. YOUR_SUBSCRIPTION_KEY를 사용자 고유의 구독 키로 바꾸세요.Replace YOUR_SUBSCRIPTION_KEY with your own subscription key:

$FetchTokenHeader = @{
  'Content-type'='application/x-www-form-urlencoded';
  'Content-Length'= '0';
  'Ocp-Apim-Subscription-Key' = 'YOUR_SUBSCRIPTION_KEY'
}

$OAuthToken = Invoke-RestMethod -Method POST -Uri https://api.cognitive.microsoft.com/sts/v1.0/issueToken -Headers $FetchTokenHeader

# show the token received
$OAuthToken

POST 요청 샘플은 다음과 같습니다.The following is a sample POST request:

POST https://api.cognitive.microsoft.com/sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: api.cognitive.microsoft.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0
Connection: Keep-Alive

토큰 서비스에서 권한 부여 토큰을 가져올 수 없는 경우 구독 키가 여전히 유효한지 확인합니다.If you cannot get an authorization token from the token service, check whether your subscription key is still valid. 평가판 키를 사용하는 경우 Cognitive Services 구독 페이지로 이동하고, "로그인"을 클릭하여 평가판 키를 적용하는 데 사용한 계정으로 로그인한 다음, 구독 키가 만료되었거나 할당량을 초과하는지 여부를 확인합니다.If you are using a free trial key, go to the Cognitive Services subscription page, click on "Log in" to login using the account that you used for applying the free trial key, and check whether the subscription key is expired or exceeds the quota.

요청에 권한 부여 토큰 사용Use an authorization token in a request

Speech API를 호출할 때마다 Authorization 헤더에 권한 부여 토큰을 전달해야 합니다.Each time you call the Speech API, you need to pass the authorization token in the Authorization header. Authorization 헤더에 JWT 액세스 토큰이 있어야 합니다.The Authorization header must contain a JWT access token.

다음 예제에서는 Speech REST API를 호출할 때 권한 부여 토큰을 사용하는 방법을 보여 줍니다.The following example shows how to use an authorization token when you call the Speech REST API.

참고

YOUR_AUDIO_FILE을 미리 녹음된 오디오 파일의 경로로 바꾸고,Replace YOUR_AUDIO_FILE with the path to your prerecorded audio file. YOUR_ACCESS_TOKEN을 이전의 권한 부여 토큰 가져오기 단계에서 획득한 권한 부여 토큰으로 바꾸세요.Replace YOUR_ACCESS_TOKEN with the authorization token you got in the previous step Get an authorization token.


$SpeechServiceURI =
'https://speech.platform.bing.com/speech/recognition/interactive/cognitiveservices/v1?language=en-us&format=detailed'

# $OAuthToken is the authrization token returned by the token service.
$RecoRequestHeader = @{
  'Authorization' = 'Bearer '+ $OAuthToken;
  'Transfer-Encoding' = 'chunked'
  'Content-type' = 'audio/wav; codec=audio/pcm; samplerate=16000'
}

# Read audio into byte array
$audioBytes = [System.IO.File]::ReadAllBytes("YOUR_AUDIO_FILE")

$RecoResponse = Invoke-RestMethod -Method POST -Uri $SpeechServiceURI -Headers $RecoRequestHeader -Body $audioBytes

# Show the result
$RecoResponse

권한 부여 토큰 갱신Renew an authorization token

권한 부여 토큰은 특정 기간(현재 10분) 후에 만료됩니다.The authorization token expires after a certain time period (currently 10 minutes). 만료되기 전에 권한 부여 토큰을 갱신해야 합니다.You need to renew the authorization token before it expires.

다음 코드는 C#에서 권한 부여 토큰을 갱신하는 방법을 구현하는 예제입니다.The following code is an example implementation in C# of how to renew the authorization token:

    /*
     * This class demonstrates how to get a valid O-auth token.
     */
    public class Authentication
    {
        public static readonly string FetchTokenUri = "https://api.cognitive.microsoft.com/sts/v1.0";
        private string subscriptionKey;
        private string token;
        private Timer accessTokenRenewer;

        //Access token expires every 10 minutes. Renew it every 9 minutes.
        private const int RefreshTokenDuration = 9;

        public Authentication(string subscriptionKey)
        {
            this.subscriptionKey = subscriptionKey;
            this.token = FetchToken(FetchTokenUri, subscriptionKey).Result;

            // renew the token on set duration.
            accessTokenRenewer = new Timer(new TimerCallback(OnTokenExpiredCallback),
                                           this,
                                           TimeSpan.FromMinutes(RefreshTokenDuration),
                                           TimeSpan.FromMilliseconds(-1));
        }

        public string GetAccessToken()
        {
            return this.token;
        }

        private void RenewAccessToken()
        {
            this.token = FetchToken(FetchTokenUri, this.subscriptionKey).Result;
            Console.WriteLine("Renewed token.");
        }

        private void OnTokenExpiredCallback(object stateInfo)
        {
            try
            {
                RenewAccessToken();
            }
            catch (Exception ex)
            {
                Console.WriteLine(string.Format("Failed renewing access token. Details: {0}", ex.Message));
            }
            finally
            {
                try
                {
                    accessTokenRenewer.Change(TimeSpan.FromMinutes(RefreshTokenDuration), TimeSpan.FromMilliseconds(-1));
                }
                catch (Exception ex)
                {
                    Console.WriteLine(string.Format("Failed to reschedule the timer to renew access token. Details: {0}", ex.Message));
                }
            }
        }

        private async Task<string> FetchToken(string fetchUri, string subscriptionKey)
        {
            using (var client = new HttpClient())
            {
                client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
                UriBuilder uriBuilder = new UriBuilder(fetchUri);
                uriBuilder.Path += "/issueToken";

                var result = await client.PostAsync(uriBuilder.Uri.AbsoluteUri, null);
                Console.WriteLine("Token Uri: {0}", uriBuilder.Uri.AbsoluteUri);
                return await result.Content.ReadAsStringAsync();
            }
        }
    }