Translator v3.0
새로운 기능
Translator 버전 3.0은 최신 JSON 기반 Web API를 제공합니다. 기존 기능을 더 적은 수의 작업으로 통합하여 유용성과 성능을 향상시키고 새로운 기능을 제공합니다.
- 한 언어의 텍스트를 한 스크립트에서 다른 스크립트로 변환하는 음역입니다.
- 한 요청에서 여러 언어로 번역.
- 한 요청의 언어 감지, 번역 및 음역입니다.
- 용어의 대체 번역을 조회하고, 컨텍스트에서 사용된 용어를 보여 주는 예와 역방향 번역을 찾기 위한 사전
- 더 많은 정보 언어 감지 결과.
기본 URL
Translator에 대한 요청은 대부분 요청이 시작된 위치와 가장 가까운 데이터 센터에서 처리됩니다. 글로벌 엔드포인트를 사용할 때 데이터 센터 오류가 발생하면 요청이 지리 외부로 라우팅될 수 있습니다.
특정 지리 내에서 요청을 강제로 처리하려면 원하는 지리적 엔드포인트를 사용합니다. 모든 요청은 지리 내의 데이터 센터 간에 처리됩니다.
Geography | 기준 URL(지리적 엔드포인트) | 데이터 센터 |
---|---|---|
전체(non-regional ) |
api.cognitive.microsofttranslator.com | 사용 가능한 가장 가까운 데이터 센터 |
아시아 태평양 | api-apc.cognitive.microsofttranslator.com | 한국 남부, 일본 동부, 동남아시아 및 오스트레일리아 동부 |
유럽 | api-eur.cognitive.microsofttranslator.com | 북유럽, 서유럽 |
미국 | api-nam.cognitive.microsofttranslator.com | 미국 동부, 미국 중남부, 미국 중서부 및 미국 서부 2 |
1
스위스 북부 또는 스위스 서부에 리소스가 있는 고객은 텍스트 API 요청이 스위스 내에서 제공되도록 할 수 있습니다. 스위스에서 요청을 처리하려면 번역기 리소스를 만들거나 Switzerland West
API 요청에서 Resource region
Switzerland North
리소스의 사용자 지정 엔드포인트를 사용합니다.
예를 들어 Azure Portal에서 리소스 이름이 있는 번역기 리소스를 Resource region
만드는 경우 사용자 지정 엔드포인트는 다음과 같습니다https​://my-swiss-n.cognitiveservices.azure.com
.Switzerland North
my-swiss-n
그리고 번역할 샘플 요청은 다음과 같습니다.
// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v
2
사용자 지정 번역기 현재 스위스에서 사용할 수 없습니다.
인증
Azure AI 서비스의 Translator 또는 다중 서비스를 구독하고 키(Azure Portal에서 확인할 수 있음)를 사용하여 인증합니다.
구독을 인증하는 데 사용할 수 있는 세 가지 헤더가 있습니다. 이 표에는 각 사용 방법이 설명되어 있습니다.
헤더 | 설명 |
---|---|
Ocp-Apim-Subscription-Key | 비밀 키를 전달하는 경우 Azure AI 서비스 구독에 사용합니다. 값은 번역기 구독에 대한 Azure 비밀 키입니다. |
권한 부여 | 인증 토큰을 전달하는 경우 Azure AI 서비스 구독에 사용합니다. 값은 전달자 토큰 Bearer <token> 입니다. |
Ocp-Apim-Subscription-Region | 다중 서비스 및 지역 번역기 리소스와 함께 사용합니다. 값은 다중 서비스 또는 지역 번역기 리소스의 지역입니다. 이 값은 전역 번역기 리소스를 사용하는 경우 선택 사항입니다. |
비밀 키
첫 번째 옵션은 헤더를 사용하여 인증하는 것입니다 Ocp-Apim-Subscription-Key
. Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY>
요청에 헤더를 추가합니다.
전역 리소스를 사용하여 인증
전역 번역기 리소스를 사용하는 경우 번역기 호출하는 헤더를 하나 포함해야 합니다.
헤더 | 설명 |
---|---|
Ocp-Apim-Subscription-Key | 값은 번역기 구독에 대한 Azure 비밀 키입니다. |
다음은 전역 번역기 리소스를 사용하여 번역기 호출하는 예제 요청입니다.
// 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?'}]"
지역 리소스를 사용한 인증
지역별 번역기 리소스를 사용하는 경우 번역기를 호출하는 데 필요한 두 개의 헤더가 있습니다.
헤더 | 설명 |
---|---|
Ocp-Apim-Subscription-Key | 값은 번역기 구독에 대한 Azure 비밀 키입니다. |
Ocp-Apim-Subscription-Region | 값은 번역기 리소스의 지역입니다. |
다음은 지역 번역기 리소스를 사용하여 번역기 호출하는 예제 요청입니다.
// 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를 호출하는 데는 두 개의 헤더가 필요합니다.
헤더 | 설명 |
---|---|
Ocp-Apim-Subscription-Key | 값은 다중 서비스 리소스에 대한 Azure 비밀 키입니다. |
Ocp-Apim-Subscription-Region | 값은 다중 서비스 리소스의 지역입니다. |
다중 서비스 텍스트 API 구독에는 지역이 필요합니다. 선택한 지역은 다중 서비스 키를 사용할 때 텍스트 번역에 사용할 수 있는 유일한 지역입니다. Azure Portal을 통해 다중 서비스 구독에 가입할 때 선택한 것과 동일한 지역이어야 합니다.
매개 변수를 사용하여 쿼리 문자열의 비밀 키를 전달하는 경우 쿼리 매개 변수Subscription-Key
Subscription-Region
를 사용하여 지역을 지정해야 합니다.
액세스 토큰을 사용하여 인증
또는 비밀 키를 액세스 토큰으로 교환할 수 있습니다. 이 토큰은 각 요청에 헤더로 Authorization
포함됩니다. 인증 토큰을 받으려면 다음 URL에 대해 POST
요청을 수행합니다.
리소스 종류 | 인증 서비스 URL |
---|---|
전역 | https://api.cognitive.microsoft.com/sts/v1.0/issueToken |
지역 또는 다중 서비스 | https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken |
다음은 글로벌 리소스에 대해 비밀 키가 제공된 경우 토큰을 얻기 위한 예제 요청입니다.
// 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>"
성공적인 요청은 인코딩된 액세스 토큰을 응답 본문에 일반 텍스트로 반환합니다. 유효한 토큰이 인증의 전달자 토큰으로 Translator 서비스에 전달됩니다.
Authorization: Bearer <Base64-access_token>
인증 토큰은 10분 동안 유효합니다. 토큰은 번역기 여러 번의 호출을 할 때 다시 사용해야 합니다. 그러나 프로그램이 확장된 기간 동안 Translator에 대한 요청을 수행하는 경우 프로그램은 일정한 간격(예: 8분마다)으로 새 액세스 토큰을 요청해야 합니다.
Microsoft Entra ID를 사용한 인증
번역기 v3.0은 Microsoft의 클라우드 기반 ID 및 액세스 관리 솔루션인 Microsoft Entra 인증을 지원합니다. 권한 부여 헤더를 사용하면 Translator 서비스에서 요청하는 클라이언트가 리소스를 사용하고 요청을 완료할 수 있는 권한이 있는지 확인할 수 있습니다.
필수 조건
Microsoft Entra ID를 사용하여 인증하는 방법을 간략하게 이해합니다.
관리 ID에 대한 액세스 권한을 부여하는 방법을 간략하게 설명합니다.
헤더
헤더 | 값 |
---|---|
권한 부여 | 값은 Azure AD에서 생성된 액세스 전달자 토큰입니다.
|
Ocp-Apim-Subscription-Region | 값은 번역기 리소스의 지역입니다.
|
Ocp-Apim-ResourceId | 값은 Translator 리소스 인스턴스에 대한 리소스 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 지원
이제 azure 퍼블릭 클라우드의 모든 지역에서 VNET(Virtual Network) 기능을 사용하여 번역기 서비스를 사용할 수 있습니다. 가상 네트워크를 사용하려면 Azure AI 서비스 가상 네트워크 구성을 참조하세요.
이 기능을 켜면 사용자 지정 엔드포인트를 사용하여 번역기 호출해야 합니다. 전역 번역기 엔드포인트("api.cognitive.microsofttranslator.com")를 사용할 수 없으며 액세스 토큰을 사용하여 인증할 수 없습니다.
Translator 리소스를 만들고 선택한 네트워크 및 프라이빗 엔드포인트에서 액세스를 허용한 후 사용자 지정 엔드포인트를 찾을 수 있습니다.
Azure Portal에서 Translator 리소스로 이동합니다.
리소스 관리 섹션에서 네트워킹을 선택합니다.
방화벽 및 가상 네트워크 탭에서 선택한 네트워크 및 프라이빗 엔드포인트를 선택합니다.
저장을 선택하여 변경 내용을 적용합니다.
리소스 관리 섹션에서 키 및 엔드포인트를 선택합니다.
가상 네트워크 탭을 선택합니다.
텍스트 번역 및 문서 번역에 대한 엔드포인트가 나열되어 있습니다.
헤더 | 설명 |
---|---|
Ocp-Apim-Subscription-Key | 값은 번역기 구독에 대한 Azure 비밀 키입니다. |
Ocp-Apim-Subscription-Region | 값은 번역기 리소스의 지역입니다. 이 값은 리소스가 인 경우 선택 사항입니다. global |
사용자 지정 엔드포인트를 사용하여 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?'}]"
Errors
표준 오류 응답은 이름/값 쌍이 포함된 JSON 개체 error
입니다. 값은 속성이 있는 JSON 개체이기도 합니다.
code
: 서버 정의 오류 코드입니다.message
: 사람이 읽을 수 있는 오류를 나타내는 문자열입니다.
예를 들어 평가판 구독을 사용하는 고객은 무료 할당량이 소진되면 다음 오류를 받게 됩니다.
{
"error": {
"code":403001,
"message":"The operation isn't allowed because the subscription has exceeded its free quota."
}
}
오류 코드는 오류를 더 범주화하도록 뒤에 3자리 숫자가 오는 3자리 HTTP 상태 코드로 결합된 6자리 숫자입니다. 일반적인 오류 코드는 다음과 같습니다.
코드 | Description |
---|---|
400000 | 요청 입력 중 하나가 올바르지 않습니다. |
400001 | "scope" 매개 변수가 올바르지 않습니다. |
400002 | "category" 매개 변수가 올바르지 않습니다. |
400003 | 언어 지정자 누락되었거나 올바르지 않습니다. |
400004 | 대상 스크립트 지정자("To script")가 누락되었거나 올바르지 않습니다. |
400005 | 입력 텍스트가 누락되었거나 올바르지 않습니다. |
400006 | 언어 및 스크립트의 조합이 올바르지 않습니다. |
400018 | 원본 스크립트 지정자("From script")가 누락되었거나 올바르지 않습니다. |
400019 | 지정된 언어 중 하나가 지원되지 않습니다. |
400020 | 입력 텍스트의 배열에서 요소 중 하나가 올바르지 않습니다. |
400021 | API 버전 매개 변수가 누락되었거나 올바르지 않습니다. |
400023 | 지정된 언어 쌍 중 하나가 올바르지 않습니다. |
400035 | 원본 언어("From" 필드)가 올바르지 않습니다. |
400036 | 대상 언어("To" 필드)가 누락되었거나 올바르지 않습니다. |
400042 | 지정된 옵션("Options" 필드) 중 하나가 올바르지 않습니다. |
400043 | 클라이언트 추적 ID(ClientTraceId 필드 또는 X-ClientTranceId 헤더)가 누락되었거나 올바르지 않습니다. |
400050 | 입력 텍스트가 너무 깁니다. 요청 제한 보기. |
400064 | "translation" 매개 변수가 누락되었거나 올바르지 않습니다. |
400070 | 대상 스크립트(ToScript 매개 변수)의 수가 대상 언어(To parameter)의 수와 일치하지 않습니다. |
400071 | 값이 TextType에 적합하지 않습니다. |
400072 | 입력 텍스트의 배열에 요소가 너무 많습니다. |
400073 | 스크립트 매개 변수가 올바르지 않습니다. |
400074 | 요청 분문이 유효한 JSON이 아닙니다. |
400075 | 언어 쌍 및 범주 조합이 올바르지 않습니다. |
400077 | 최대 요청 크기를 초과했습니다. 요청 제한 보기. |
400079 | 언어 간 번역을 요청한 사용자 지정 시스템이 존재하지 않습니다. |
400080 | 언어 또는 스크립트에는 음역이 지원되지 않습니다. |
401000 | 자격 증명이 누락되었거나 올바르지 않으므로 요청에 권한이 없습니다. |
401015 | "제공된 자격 증명은 Speech API에 대한 것입니다. 이 요청에는 Text API에 대한 자격 증명이 필요합니다. Translator에 대한 구독을 사용하세요. |
403000 | 작업이 허용되지 않습니다. |
403001 | 구독이 무료 할당량을 초과했기 때문에 작업이 허용되지 않습니다. |
405000 | 요청 메서드가 요청된 리소스에 대해 지원되지 않습니다. |
408001 | 요청된 번역 시스템이 준비되고 있습니다. 잠시 후에 다시 시도합니다. |
408002 | 들어오는 스트림을 기다리는 동안 요청 시간이 초과되었습니다. 서버가 대기하도록 준비된 시간 내에 클라이언트가 요청을 생성하지 않았습니다. 클라이언트는 나중에 수정하지 않고 요청을 반복할 수 있습니다. |
415000 | Content-Type 헤더가 누락되었거나 올바르지 않습니다. |
429000, 429001, 429002 | 클라이언트가 요청 한도를 초과했기 때문에 서버가 요청을 거부했습니다. |
500000 | 예기치 않은 오류가 발생했습니다. 이 오류가 계속 발생하는 경우 오류의 날짜/시간, 응답 헤더 X-RequestId의 요청 식별자 및 요청 헤더 X-ClientTraceId의 클라이언트 식별자를 사용하여 보고합니다. |
503000 | 서비스를 일시적으로 사용할 수 없습니다. 다시 시도하십시오. 이 오류가 계속 발생하는 경우 오류의 날짜/시간, 응답 헤더 X-RequestId의 요청 식별자 및 요청 헤더 X-ClientTraceId의 클라이언트 식별자를 사용하여 보고합니다. |
메트릭
메트릭을 사용하면 아래 스크린샷과 같이 메트릭 섹션에서 Azure Portal 번역기 사용량 및 가용성 정보를 볼 수 있습니다. 자세한 내용은 데이터 및 플랫폼 메트릭을 참조 하세요.
이 표에는 번역 API 호출을 모니터링하는 데 사용되는 방법에 대한 설명과 함께 사용 가능한 메트릭이 나와 있습니다.
메트릭 | 설명 |
---|---|
TotalCalls | 총 API 호출 수입니다. |
TotalTokenCalls | 인증 토큰을 사용하는 토큰 서비스를 통한 총 API 호출 수입니다. |
SuccessfulCalls | 성공한 호출 수입니다. |
TotalErrors | 오류 응답이 있는 호출 수입니다. |
BlockedCalls | 요금 또는 할당량 한도를 초과한 호출 수입니다. |
ServerErrors | 서버 내부 오류(5XX)가 있는 호출 수입니다. |
ClientErrors | 클라이언트 쪽 오류(4XX)가 있는 호출 수입니다. |
대기 시간 | 요청을 완료하는 기간(밀리초)입니다. |
CharactersTranslated | 들어오는 텍스트 요청에 있는 문자의 총 수입니다. |