Translator v3.0

아티클
09/02/2024

새로운 기능

Translator 버전 3.0은 최신 JSON 기반 Web API를 제공합니다. 기존 기능을 더 적은 수의 작업으로 통합하여 유용성과 성능을 향상시키고 새로운 기능을 제공합니다.

한 언어의 텍스트를 한 스크립트에서 다른 스크립트로 변환하는 음역입니다.
한 요청에서 여러 언어로 번역.
한 요청의 언어 감지, 번역 및 음역입니다.
용어의 대체 번역을 조회하고, 컨텍스트에서 사용된 용어를 보여 주는 예와 역방향 번역을 찾기 위한 사전
더 많은 정보 언어 감지 결과.

기준 URL

Translator에 대한 요청은 대부분 요청이 시작된 위치와 가장 가까운 데이터 센터에서 처리됩니다. 글로벌 엔드포인트를 사용할 때 데이터 센터 오류가 발생하면 요청이 지리 외부로 라우팅될 수 있습니다.

특정 지리 내에서 요청을 강제로 처리하려면 원하는 지리적 엔드포인트를 사용합니다. 모든 요청은 지리 내의 데이터 센터 간에 처리됩니다.

✔️ 기능: Translator Text

서비스 엔드포인트	요청 처리 데이터 센터
전역(권장): `api.cognitive.microsofttranslator.com`	가장 가까운 사용 가능한 데이터 센터입니다.
아메리카: `api-nam.cognitive.microsofttranslator.com`	미국 동부 2 • 미국 서부 2
아시아 태평양: `api-apc.cognitive.microsofttranslator.com`	일본 동부 • 동남 아시아
유럽(스위스 제외): `api-eur.cognitive.microsofttranslator.com`	프랑스 중부 • 서유럽
스위스: 자세한 내용은 스위스 서비스 엔드포인트 를 참조하세요.	스위스 북부 • 스위스 서부

스위스 서비스 엔드포인트

스위스 북부 또는 스위스 서부에 리소스가 있는 고객은 텍스트 API 요청이 스위스 내에서 처리되도록 할 수 있습니다. 요청이 스위스에서 처리되도록 하려면 Resource region Switzerland North 또는 Switzerland West에서 Translator 리소스를 만든 다음 API 요청에서 리소스의 사용자 지정 엔드포인트를 사용합니다.

예를 들어, Azure Portal에서 Resource region을 Switzerland North로 사용하여 Translator 리소스를 만들고 리소스 이름이 my-swiss-n인 경우 사용자 지정 엔드포인트는 https://my-swiss-n.cognitiveservices.azure.com입니다. 그리고 번역할 샘플 요청은 다음과 같습니다.

// 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

Custom Translator는 현재 스위스에서 사용할 수 없습니다.

인증

Azure AI 서비스의 Translator 또는 다중 서비스를 구독하고 키(Azure Portal에서 확인할 수 있음)를 사용하여 인증합니다.

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

헤더	설명
Ocp-Apim-Subscription-Key	비밀 키를 전달하는 경우 Azure AI 서비스 구독에 사용합니다. 값은 Translator 구독에 대한 Azure 비밀 키입니다.
Authorization	인증 토큰을 전달하는 경우 Azure AI 서비스 구독에 사용합니다. 값은 전달자 토큰 `Bearer <token>`입니다.
Ocp-Apim-Subscription-Region	다중 서비스 및 지역 번역기 리소스와 함께 사용합니다. 값은 다중 서비스 또는 지역 번역기 리소스의 지역입니다. 이 값은 전역 번역기 리소스를 사용하는 경우 선택 사항입니다.

비밀 키

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

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

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

헤더	설명
Ocp-Apim-Subscription-Key	값은 Translator 구독에 대한 Azure 비밀 키입니다.

다음은 전역 번역기 리소스를 사용하여 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?'}]"

지역 리소스를 사용한 인증

지역별 번역기 리소스를 사용하는 경우 번역기를 호출하는 데 필요한 두 개의 헤더가 있습니다.

헤더	설명
Ocp-Apim-Subscription-Key	값은 Translator 구독에 대한 Azure 비밀 키입니다.
Ocp-Apim-Subscription-Region	값은 번역기 리소스의 지역입니다.

다음은 지역 번역기 리소스를 사용하여 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를 호출하는 데는 두 개의 헤더가 필요합니다.

헤더	설명
Ocp-Apim-Subscription-Key	값은 다중 서비스 리소스에 대한 Azure 비밀 키입니다.
Ocp-Apim-Subscription-Region	값은 다중 서비스 리소스의 지역입니다.

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

매개 변수를 사용하여 쿼리 문자열의 비밀 키를 전달하는 경우 쿼리 매개 변수Subscription-KeySubscription-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를 여러 차례 호출할 때 토큰을 다시 사용해야 합니다. 그러나 프로그램이 확장된 기간 동안 Translator에 대한 요청을 수행하는 경우 프로그램은 일정한 간격(예: 8분마다)으로 새 액세스 토큰을 요청해야 합니다.

Microsoft Entra ID로 인증

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

필수 구성 요소

Microsoft Entra ID를 사용하여 인증하는 방법을 간략하게 이해합니다.
관리 ID에 대한 액세스 권한을 부여하는 방법을 간략하게 설명합니다.

헤더

헤더	값
Authorization	값은 Azure AD에서 생성된 액세스 전달자 토큰입니다. 전달자 토큰은 인증 증명을 제공하고 리소스를 사용하기 위한 클라이언트의 권한 부여에 대한 유효성을 검사합니다. 인증 토큰은 10분 동안 유효하며, Translator를 여러 번 호출할 때 다시 사용해야 합니다. 샘플 요청 참조: 2. 토큰 가져오기
Ocp-Apim-Subscription-Region	값은 번역기 리소스의 지역입니다. 리소스가 전역인 경우 이 값은 선택 사항입니다.
Ocp-Apim-ResourceId	값은 Translator 리소스 인스턴스에 대한 리소스 ID입니다. 리소스 ID는 Azure Portal의 Translator 리소스 → 속성에서 확인할 수 있습니다. 리소스 ID 형식: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

Translator 속성 페이지 - Azure Portal

스크린샷: Azure Portal의 번역기 속성 페이지

Important

Cognitive Services 사용자 역할을 서비스 주체에 할당합니다. 이 역할을 할당하면 서비스 주체에게 Translator 리소스에 대한 액세스 권한을 부여합니다.

예제

글로벌 엔드포인트 사용

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

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

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

Azure Portal에서 Translator 리소스로 이동합니다.
리소스 관리 섹션에서 네트워킹을 선택합니다.
방화벽 및 가상 네트워크 탭에서 선택한 네트워크 및 프라이빗 엔드포인트를 선택합니다.
저장을 선택하여 변경 내용을 적용합니다.
리소스 관리 섹션에서 키 및 엔드포인트를 선택합니다.
가상 네트워크 탭을 선택합니다.
텍스트 번역 및 문서 번역에 대한 엔드포인트가 나열되어 있습니다.

헤더	설명
Ocp-Apim-Subscription-Key	값은 Translator 구독에 대한 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-ClientTraceId 헤더)가 없거나 잘못되었습니다.
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 번역기 사용량 및 가용성 정보를 볼 수 있습니다. 자세한 내용은 데이터 및 플랫폼 메트릭을 참조 하세요.

Translator 메트릭

이 표에는 번역 API 호출을 모니터링하는 데 사용되는 방법에 대한 설명과 함께 사용 가능한 메트릭이 나와 있습니다.

메트릭	설명
TotalCalls	총 API 호출 수입니다.
TotalTokenCalls	인증 토큰을 사용하는 토큰 서비스를 통한 총 API 호출 수입니다.
SuccessfulCalls	성공한 호출 수입니다.
TotalErrors	오류 응답이 있는 호출 수입니다.
BlockedCalls	요금 또는 할당량 한도를 초과한 호출 수입니다.
ServerErrors	서버 내부 오류(5XX)가 있는 호출 수입니다.
ClientErrors	클라이언트 쪽 오류(4XX)가 있는 호출 수입니다.
대기 시간	요청을 완료하는 기간(밀리초)입니다.
CharactersTranslated	들어오는 텍스트 요청에 있는 문자의 총 수입니다.

다음을 통해 공유

Translator v3.0

새로운 기능

기준 URL

스위스 서비스 엔드포인트

인증

비밀 키

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

지역 리소스를 사용한 인증

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

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

Microsoft Entra ID로 인증

필수 구성 요소

헤더

Translator 속성 페이지 - Azure Portal

예제

글로벌 엔드포인트 사용

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

관리 ID를 사용하는 예제

글로벌 엔드포인트 사용

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

Virtual Network 지원

Errors

메트릭

피드백

추가 리소스