프로그래밍 방식으로 REST API 사용
문서 번역은 Azure AI 번역기 서비스의 클라우드 기반 기능입니다. 문서 번역 API를 사용하여 원본 문서 구조와 텍스트 서식을 유지하면서 지원되는 언어와 다양한 파일 형식으로 전체 문서를 비동기식으로 번역할 수 있습니다. 이 사용 방법 가이드에서는 선택한 프로그래밍 언어 및 HTTP REST API와 함께 문서 번역 API를 사용하는 방법을 알아봅니다.
필수 조건
참고 항목
문서 번역은 S1 표준 서비스 플랜(종량제) 및 C2, C3, C4, D3 볼륨 할인 플랜에서 지원됩니다. Azure AI 서비스 가격 책정 - 번역기를 참조하세요.
시작하려면 다음이 필요합니다.
활성 Azure 계정. 계정이 없는 경우 무료 계정을 만들 수 있습니다.
Azure Blob Storage 계정 또한 원본 및 대상 파일에 대한 Azure Blob Storage 계정에 컨테이너를 생성해야 합니다.
- 원본 컨테이너. 이 컨테이너는 번역을 위해 파일을 업로드하는 위치입니다(필수).
- 대상 컨테이너. 이 컨테이너는 번역된 파일이 저장되는 곳입니다(필수).
-
다음과 같이 Translator 프로젝트 및 인스턴스 세부 정보 필드를 완료합니다.
구독. 사용 가능한 Azure 구독 중 하나를 선택합니다.
리소스 그룹. 새 리소스 그룹을 만들거나 동일한 수명 주기, 권한 및 정책을 공유하는 기존 리소스 그룹에 리소스를 추가할 수 있습니다.
리소스 지역. 비즈니스 또는 애플리케이션에서 특정 지역을 요구하지 않는 한 전체를 선택합니다. 인증에 시스템 할당 관리 ID를 사용하려는 경우 미국 서부와 같은 지리적 지역을 선택합니다.
이름. 리소스에 대해 선택한 이름을 입력합니다. 선택하는 이름이 Azure 내에서 고유해야 합니다.
참고 항목
문서 번역에는 사용자 지정 도메인 엔드포인트가 필요합니다. 이름 필드에 입력하는 값은 엔드포인트에 대한 사용자 지정 도메인 이름 매개 변수가 됩니다.
가격 책정 계층. 무료 계층에서는 문서 번역이 지원되지 않습니다. 서비스를 사용해 보려면 Standard S1을 선택합니다.
검토 + 생성를 선택합니다.
서비스 약관을 검토하고 만들기를 선택하여 리소스를 배포합니다.
리소스가 성공적으로 배포되면 리소스로 이동을 선택하여 키와 엔드포인트를 검색합니다.
키 및 사용자 지정 도메인 엔드포인트 검색
- Translator 서비스에 대한 요청에는 액세스를 인증하기 위해 읽기 전용 키와 사용자 지정 엔드포인트가 필요합니다. 사용자 지정 도메인 엔드포인트는 리소스 이름, 호스트 이름 및 Translator 하위 디렉터리로 형식이 지정된 URL이며 Azure Portal에서 사용할 수 있습니다.
새 리소스를 만든 경우 배포한 후 리소스로 이동을 선택합니다. 기존 문서 번역 리소스가 있는 경우 리소스 페이지로 직접 이동합니다.
왼쪽 레일의 리소스 관리에서 키 및 엔드포인트를 선택합니다.
Microsoft 메모장과 같은 편리한 위치에
key및document translation endpoint를 복사하여 붙여넣으세요. API 호출을 수행하는 데는 키가 하나만 필요합니다.문서 번역 서비스에 대한 요청을 인증하기 위해 코드 샘플에
key및document translation endpoint를 붙여넣습니다.
키 가져오기
Translator 서비스에 대한 요청에는 액세스 인증을 위한 읽기 전용 키가 필요합니다.
- 새 리소스를 만든 경우 배포한 후 리소스로 이동을 선택합니다. 기존 문서 번역 리소스가 있는 경우 리소스 페이지로 직접 이동합니다.
- 왼쪽 레일의 리소스 관리에서 키 및 엔드포인트를 선택합니다.
- Microsoft 메모장과 같은 편리한 위치에 키를 복사하여 붙여넣습니다.
- 코드 샘플에 붙여넣어 문서 번역 서비스에 대한 요청을 인증합니다.
Azure Blob Storage 컨테이너 만들기
원본 및 대상 파일에 대한 Azure Blob Storage 계정에서 컨테이너를 생성해야 합니다.
- 원본 컨테이너. 이 컨테이너는 번역을 위해 파일을 업로드하는 위치입니다(필수).
- 대상 컨테이너. 이 컨테이너는 번역된 파일이 저장되는 곳입니다(필수).
참고 항목
문서 번역은 대상 컨테이너에서 용어집을 Blob으로서 지원합니다(별도 용어집 컨테이너 아님). 사용자 지정 용어집을 포함하려면 대상 컨테이너에 추가하고 요청에 glossaryUrl을 포함합니다. 용어집에 번역 언어 쌍이 없으면 적용되지 않습니다. 사용자 지정 용어집을 사용하여 문서 번역 참조
문서 번역을 위한 SAS 토큰 생성
sourceUrl, targetUrl 및 선택적 glossaryUrl에는 쿼리 문자열로 추가된 SAS(공유 액세스 서명) 토큰이 포함되어야 합니다. 토큰은 컨테이너 또는 특정 Blob에 할당될 수 있습니다. 문서 번역을 위한 SAS 토큰 생성 프로세스를 참조하세요.
- 원본 컨테이너 또는 Blob에는 읽기 및 나열 액세스가 지정되어 있어야 합니다.
- 대상 컨테이너 또는 Blob에는 쓰기 및 나열 액세스가 지정되어 있어야 합니다.
- 용어집 컨테이너 또는 Blob에는 읽기 및 나열 액세스가 지정되어 있어야 합니다.
팁
- 작업에서 여러 파일(Blob)을 번역하는 경우 컨테이너 수준에서 SAS 액세스 권한을 위임합니다.
- 작업에서 단일 파일(Blob)을 번역하는 경우 Blob 수준에서 SAS 액세스 권한을 위임합니다.
- SAS 토큰 대신 시스템이 할당한 관리 ID를 인증에 사용할 수 있습니다.
HTTP 요청
비동기 일괄 처리 번역 요청은 POST 요청을 통해 Translator 서비스 엔드포인트에 제출됩니다. 성공하면 POST 메서드는 202 Accepted 응답 코드를 반환하고 서비스는 일괄 처리 요청을 만듭니다. 번역된 문서가 대상 컨테이너에 나열됩니다.
Azure AI 번역기 서비스 요청 제한에 대한 자세한 내용은 문서 번역 요청 제한을 참조하세요.
HTTP 헤더
각 Document Translation API 요청에는 다음 헤더가 포함됩니다.
| HTTP 헤더 | 설명 |
|---|---|
| Ocp-Apim-Subscription-Key | 필수: 값은 번역기 또는 Azure AI 서비스 리소스에 대한 Azure 키입니다. |
| 콘텐츠-형식 | 필수: 페이로드의 콘텐츠 형식을 지정합니다. 허용되는 값은 application/json 또는 charset=UTF-8입니다. |
POST 요청 본문 속성
- POST 요청 URL이 POST
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches입니다. - POST 요청 본문은
inputs라는 JSON 객체입니다. inputs개체는 원본 및 대상 언어 쌍에 대한sourceURL및targetURL컨테이너 주소를 모두 포함합니다.prefix및suffix는 번역을 위해 원본 경로의 문서를 필터링하는 대/소문자를 구분하는 문자열입니다.prefix필드는 번역을 위해 하위 폴더를 나타내는 데 자주 사용됩니다.suffix필드는 파일 확장 프로그램에 가장 자주 사용됩니다.glossaries필드(선택 사항)의 값은 문서가 번역될 때 적용됩니다.- 각 대상 언어의
targetUrl은 고유해야 합니다.
참고 항목
이름이 같은 파일이 대상에 이미 있으면 작업이 실패합니다.
컨테이너의 모든 문서 번역
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "fr"
}
]
}
]
}
컨테이너의 특정 문서 번역
"storageType": "File"을 지정합니다.- 인증에 시스템이 할당한 관리 ID를 사용하지 않는 경우 컨테이너가 아닌 특정 Blob/문서에 대한 원본 URL 및 SAS 토큰을 만들었는지 확인합니다.
- SAS 토큰은 컨테이너용이지만 대상 파일 이름을 대상 URL의 일부로 지정했는지 확인합니다.
- 이 샘플 요청은 두 개의 대상 언어로 번역된 단일 문서를 반환합니다.
{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es"
},
{
"targetUrl": "{targetSASUrl}",
"language": "de"
}
]
}
]
}
사용자 지정 용어집을 사용하여 문서 번역
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es",
"glossaries": [
{
"glossaryUrl": "{glossaryUrl/en-es.xlf}",
"format": "xliff"
}
]
}
]
}
]
}
🆕 문서 내 이미지에 포함된 텍스트 번역
참고 항목
- 이 기능은 선택 사항이며 각 번역 요청에 대해 사용하도록 설정해야 합니다.
- 이 기능을 사용하도록 설정하면 사용량에 따라 추가 비용이 발생합니다. 자세한 내용은 Azure AI Vision 가격 책정을 참조하세요.
- 이 기능은 현재 Batch 문서 번역 API에서만 사용할 수 있습니다.
- 지원되는 파일 형식은 입니다
.docx. - 이 기능을 사용하려면 Azure AI Services 리소스(독립 실행형 Translator 리소스가 아님)가 필요합니다.
구성 요청
필드에서 선택적
translateTextWithinImage매개 변수options사용- 데이터 형식: 부울(
true또는false) - 기본 부울 설정은
false. 이미지 텍스트 번역을true사용하도록 설정하는 옵션을 설정합니다.
- 데이터 형식: 부울(
응답 세부 정보입니다. 기능을 사용하도록 설정하면 추가된 이미지 처리 정보가 응답에 포함됩니다.
totalImageScansSucceeded. 성공적으로 번역된 이미지 검사 수입니다.totalImageScansFailed. 처리에 실패한 이미지 검사 수입니다.
코드를 사용하여 문서 번역 요청 제출
코딩 플랫폼 설정
- 새 프로젝트를 만듭니다.
- Program.cs를 C# 코드 샘플로 바꿉니다.
- Program.cs에서 엔드포인트, 키 및 컨테이너 URL 값을 설정합니다.
- JSON 데이터 처리를 위해 .NET CLI를 사용하는 Newtonsoft.Json 패키지를 추가합니다.
- 프로젝트 디렉터리에서 프로그램을 실행합니다.
Important
코드 샘플의 경우 표시된 곳에 SAS(공유 액세스 서명) URL을 하드 코딩합니다. 완료되면 코드에서 SAS URL을 제거하고 공개적으로 게시하지 마세요. 프로덕션의 경우 Azure 관리 ID와 같은 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용합니다. 자세한 내용은 Azure Storage 보안을 참조하세요.
작업에 따라 다음 필드를 업데이트해야 할 수 있습니다.
endpointbasePathkeysourceURLtargetURLglossaryURLid(작업 ID)
id 값 찾기
- POST
start-batch-translation메서드 응답 헤더Operation-LocationURL 값에서 작업id를 찾을 수 있습니다./document/매개 변수 다음의 영숫자 문자열은 작업의 작업id입니다.
| 응답 헤더 | 응답 URL |
|---|---|
| Operation-Location | {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date} |
- 또한 get-translations-status 요청을 사용하여 번역 작업 및 해당
id목록을 검색할 수도 있습니다.
비동기식 일괄 처리 번역 시작
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
class Program
{
static readonly string route = "?api-version={date}";
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";
private static readonly string key = "{your-api-key}";
static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");
static async Task Main(string[] args)
{
using HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
StringContent content = new StringContent(json, Encoding.UTF8, "application/json");
request.Method = HttpMethod.Post;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
request.Content = content;
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
if (response.IsSuccessStatusCode)
{
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine();
Console.WriteLine($"Response Headers:");
Console.WriteLine(response.Headers);
}
else
Console.Write("Error");
}
}
}
지원되는 문서 형식 가져오기
지원되는 파일 형식 목록을 검색합니다. 성공한 경우 이 메서드는 200 OK 응답 코드를 반환합니다.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/formats";
static readonly string route = "?api-version={date}&type=document";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
번역 작업의 상태 가져오기
단일 작업의 현재 상태와 문서 번역 요청의 모든 작업 요약을 가져옵니다. 성공한 경우 이 메서드는 200 OK 응답 코드를 반환합니다.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
}
특정 문서의 상태 가져오기
간략한 개요
문서 번역 요청에서 특정 문서의 상태를 검색합니다. 성공한 경우 이 메서드는 200 OK 응답 코드를 반환합니다.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
작업 삭제
간략한 개요
현재 처리 중이거나 대기 중인 작업을 취소합니다. 번역이 시작되지 않은 문서만 취소됩니다.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Delete;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
일반 HTTP 상태 코드
| HTTP 상태 코드 | 설명 | 가능한 원인 |
|---|---|---|
| 200 | OK | 요청에 성공했습니다. |
| 400 | Bad Request | 필수 매개 변수가 없거나 비어 있거나 null입니다. 또는 필수 또는 선택적 매개 변수에 전달된 값이 올바르지 않습니다. 일반적인 문제는 헤더가 너무 긴 경우입니다. |
| 401 | Unauthorized | 요청에 부여된 권한이 없습니다. 키 또는 토큰이 유효하고 올바른 영역에 있는지 확인하세요. |
| 429 | 요청이 너무 많음 | 구독에 허용되는 요청의 할당량 또는 속도가 초과되었습니다. |
| 502 | 잘못된 게이트웨이 | 네트워크 또는 서버 쪽 문제입니다. 잘못된 헤더를 나타낼 수도 있습니다. |