인증 및 권한 부여

Azure AI 서비스에 대한 각 요청에는 인증 헤더가 포함되어야 합니다. 이 헤더는 서비스 또는 서비스 그룹에 대한 구독을 확인하는 데 사용되는 리소스 키 또는 인증 토큰을 전달합니다. 이 문서에서는 요청을 인증하는 방법과 각 요청의 요구 사항을 살펴볼 수 있습니다.

• 단일 서비스 또는 다중 서비스 리소스 키를 사용하여 인증합니다.
• 전달자 토큰을 사용하여 인증합니다.
• Microsoft Entra ID를 사용하여 인증합니다.

헤더

Azure AI 서비스에서 Translator 또는 다중 서비스를 구독하고 키(Azure Portal에서 사용 가능)를 사용하여 인증합니다.

구독을 인증하는 데 사용할 수 있는 세 가지 헤더가 있습니다. 이 표에서는 각 사용 방법을 설명합니다.

비밀 키

첫 번째 옵션은 헤더를 사용하여 인증하는 것입니다 Ocp-Apim-Subscription-Key . Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> 요청에 헤더를 추가합니다.

전역 리소스를 사용하여 인증

전역 번역기 리소스를 사용하는 경우 Translator를 호출하기 위해 하나의 헤더를 포함해야 합니다.

다음은 전역 번역기 리소스를 사용하여 Translator를 호출하는 예제 요청입니다.

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
    -H "Ocp-Apim-Subscription-Key:<your-key>" \
    -H "Content-Type: application/json" \
    -d "[{'Text':'Hello, what is your name?'}]"

지역 리소스를 사용하여 인증

지역 번역기 리소스를 사용하는 경우 Translator를 호출해야 하는 두 개의 헤더가 있습니다.

다음은 지역 번역기 리소스를 사용하여 Translator를 호출하는 예제 요청입니다.

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
    -H "Ocp-Apim-Subscription-Key:<your-key>" \
    -H "Ocp-Apim-Subscription-Region:<your-region>" \
    -H "Content-Type: application/json" \
    -d "[{'Text':'Hello, what is your name?'}]"

다중 서비스 리소스를 사용하여 인증

다중 서비스 리소스를 사용하면 단일 API 키를 사용하여 여러 서비스에 대한 요청을 인증할 수 있습니다.

다중 서비스 비밀 키를 사용하는 경우 요청에 두 개의 인증 헤더를 포함해야 합니다. Translator를 호출해야 하는 두 개의 헤더가 있습니다.

다중 서비스 텍스트 API 구독에는 지역이 필요합니다. 선택한 지역은 다중 서비스 키를 사용할 때 텍스트 번역에 사용할 수 있는 유일한 지역입니다. Azure Portal을 통해 다중 서비스 구독에 등록할 때 선택한 지역과 동일해야 합니다.

매개 변수를 사용하여 쿼리 문자열의 비밀 키를 전달하는 경우 쿼리 매개 변수Subscription-KeySubscription-Region를 사용하여 지역을 지정해야 합니다.

액세스 토큰을 사용하여 인증

또는 비밀 키를 액세스 토큰으로 교환할 수 있습니다. 이 토큰은 각 요청에 헤더로 Authorization 포함됩니다. 권한 부여 토큰 POST 을 가져오려면 다음 URL을 요청합니다.

전역 리소스에 대한 비밀 키가 지정된 토큰을 가져오기 위한 요청 예제는 다음과 같습니다.

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

다음은 미국 중부에 있는 지역 리소스에 대한 비밀 키가 지정된 토큰을 가져오는 예제 요청입니다.

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

성공적인 요청은 인코딩된 액세스 토큰을 응답 본문에 일반 텍스트로 반환합니다. 유효한 토큰은 Authorization에서 전달자 토큰으로 Translator 서비스에 전달됩니다.

Authorization: Bearer <Base64-access_token>

인증 토큰은 10분 동안 유효합니다. Translator를 여러 차례 호출할 때 토큰을 다시 사용해야 합니다. 그러나 프로그램이 장기간 Translator에 요청을 하는 경우 프로그램은 정기적으로(예: 8분마다) 새 액세스 토큰을 요청해야 합니다.

Microsoft Entra ID 인증

Translator v3.0은 Microsoft의 클라우드 기반 ID 및 액세스 관리 솔루션인 Microsoft Entra 인증을 지원합니다. 권한 부여 헤더를 사용하면 Translator 서비스에서 요청 클라이언트가 리소스를 사용하고 요청을 완료할 권한이 있는지 확인할 수 있습니다.

사전 요구 사항

• Microsoft Entra ID를 사용하여 인증하는 방법을 간략하게 이해합니다.

• 관리 ID에 대한 액세스 권한을 부여하는 방법을 간략하게 이해합니다.

Microsoft Entra ID 헤더

Translator 속성 페이지 - Azure Portal

예제

전역 엔드포인트 사용

// Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Ocp-Apim-ResourceId: <Resource ID>" \
    -H "Ocp-Apim-Subscription-Region: <your-region>" \
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

사용자 지정 엔드포인트 사용

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-___domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

관리 ID를 사용하는 예제

Translator v3.0은 관리 ID에 대한 액세스 권한 부여도 지원합니다. 번역기 리소스에 대해 관리 ID를 사용하는 경우 요청 헤더에서 관리 ID에 의해 생성된 전달자 토큰을 전달할 수 있습니다.

전역 엔드포인트를 사용하여

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Ocp-Apim-ResourceId: <Resource ID>" \
    -H "Ocp-Apim-Subscription-Region: <your-region>" \
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

사용자 지정 엔드포인트를 사용하여

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-___domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

Virtual Network 지원

이제 Translator 서비스는 Azure 퍼블릭 클라우드의 모든 지역에서 Virtual Network(VNET) 기능을 사용할 수 있습니다. Virtual Network를 사용하도록 설정하려면 Azure AI 서비스 가상 네트워크 구성을참조하세요.

이 기능을 켜면 사용자 지정 엔드포인트를 사용하여 Translator를 호출해야 합니다. 전역 번역기 엔드포인트("api.cognitive.microsofttranslator.com")를 사용할 수 없으며 액세스 토큰으로 인증할 수 없습니다.

Translator 리소스를 만들고 선택한 네트워크 및 프라이빗 엔드포인트에서 액세스를 허용한 후 사용자 지정 엔드포인트를 찾을 수 있습니다.

1. Azure Portal에서 Translator 리소스로 이동합니다.

2. 리소스 관리 섹션에서 네트워킹을 선택합니다.

3. 방화벽 및 가상 네트워크 탭에서 선택한 네트워크 및 프라이빗 엔드포인트를 선택합니다.

   

4. 저장을 선택하여 변경 내용을 적용합니다.

5. 리소스 관리 섹션에서 키 및 엔드포인트를 선택합니다.

6. Virtual Network 탭을 선택합니다.

7. 텍스트 번역 및 문서 번역에 대한 엔드포인트가 나열되어 있습니다.

   

다음은 사용자 지정 엔드포인트를 사용하여 Translator를 호출하는 예제 요청입니다.

// Pass secret key and region using headers
curl -X POST "https://<your-custom-___domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
    -H "Ocp-Apim-Subscription-Key:<your-key>" \
    -H "Ocp-Apim-Subscription-Region:<your-region>" \
    -H "Content-Type: application/json" \
    -d "[{'Text':'Hello, what is your name?'}]"