일괄 처리 번역 시작
참조
기능: Azure AI 번역기 → 문서 번역
API 버전: 2024-05-01
HTTP 메서드: POST
- 메서드를
Start Translation사용하여 비동기 일괄 처리 변환 요청을 실행합니다. - 이 방법을 사용하려면 원본 및 번역된 문서에 대한 스토리지 컨테이너가 있는 Azure Blob Storage 계정이 필요합니다.
팁
이 메서드는 get-translation-상태, get-documents-상태, get-document-상태 및 cancel-translation 요청 쿼리 문자열에 대한 작업 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=2024-05-01 |
- get-translations-상태 요청을 사용하여 번역 작업 및 해당 목록을 검색할 수도 있습니다
id.
요청 URL
Important
문서 번역 기능에 대한 모든 API 요청에는 Azure Portal의 리소스 개요 페이지에 있는 사용자 지정 do기본 엔드포인트가 필요합니다.
curl -i -X POST "{document-translation-endpoint}/translator/document/batches?api-version={date}"
요청 헤더
요청 헤더는 다음과 같습니다.
| 헤더 | 설명 | 조건 |
|---|---|---|
| Ocp-Apim-Subscription-Key | Azure Portal의 번역기 서비스 API 키입니다. | Required |
| Ocp-Apim-Subscription-Region | 리소스를 만든 지역입니다. | • 미국 서부와 같은 지역(지리적) 리소스를 사용할 때 필요합니다. 글머리 기호입니다. |
| Content-Type | 페이로드의 콘텐츠 형식입니다. 허용되는 값은 application/json 또는 charset=UTF-8입니다. | • 필수 |
BatchRequest(본문)
개별 요청에 여러 문서가 포함될 수 있으며 각 문서에 대한 원본 및 대상 컨테이너가 포함되어야 합니다. 원본 미디어 유형:
application/json,text/json,application/*+json.접두사 및 접미사 필터(제공된 경우)는 폴더를 필터링하는 데 사용됩니다. 접두사는 컨테이너 이름 뒤의 하위 경로에 적용됩니다.
요청에 용어집을 포함할 수 있습니다. 용어집이 잘못되었거나 번역 중에 연결할 수 없는 경우 문서 상태에 오류가 표시됩니다.
이름이 같은 파일이 대상 대상에 이미 있으면 작업이 실패합니다.
각 대상 언어에 대한 targetUrl은 고유해야 합니다.
{
"inputs": [
{
"source": {
"sourceUrl": "https://myblob.blob.core.windows.net/Container/",
"filter": {
"prefix": "FolderA",
"suffix": ".txt"
},
"language": "en",
"storageSource": "AzureBlob"
},
"targets": [
{
"targetUrl": "https://myblob.blob.core.windows.net/TargetUrl/",
"category": "general",
"language": "fr",
"glossaries": [
{
"glossaryUrl": "https://myblob.blob.core.windows.net/Container/myglossary.tsv",
"format": "XLIFF",
"version": "2.0",
"storageSource": "AzureBlob"
}
],
"storageSource": "AzureBlob"
}
],
"storageType": "Folder"
}
],
"options": {
"experimental": true
}
}
입력
입력 일괄 처리 변환 요청에 대한 정의입니다.
| 키 매개 변수 | Type | Required | 요청 매개 변수 | 설명 |
|---|---|---|---|---|
| 입력 | array |
True | • source(개체) • targets(배열) • storageType(문자열) |
입력 원본 데이터입니다. |
inputs.source
원본 데이터에 대한 정의입니다.
| 키 매개 변수 | Type | Required | 요청 매개 변수 | 설명 |
|---|---|---|---|---|
| inputs.source | object |
True | • sourceUrl(문자열) • filter(개체) • language(문자열) • storageSource(문자열) |
입력 문서에 대한 원본 데이터입니다. |
| inputs.source.sourceUrl | string |
True | • string | 원본 파일 또는 폴더의 컨테이너 위치입니다. |
| inputs.source.filter | object |
False | • prefix(문자열) • suffix(문자열) |
원본 경로에서 문서를 필터링하기 위한 대/소문자 구분 문자열입니다. |
| inputs.source.filter.prefix | string |
False | • string | 번역을 위해 원본 경로의 문서를 필터링하며 대/소문자를 구분하는 접두사 문자열입니다. 번역을 위해 하위 폴더를 지정하는 데 자주 사용됩니다. 예: "FolderA". |
| inputs.source.filter.suffix | string |
False | • string | 번역을 위해 원본 경로의 문서를 필터링하며 대/소문자를 구분하는 접미사 문자열입니다. 대부분 파일 확장명에 사용됩니다. 예: ".txt" |
| inputs.source.language | string |
False | • string | 원본 문서의 언어 코드입니다. 지정하지 않으면 자동 검색이 구현됩니다. |
| inputs.source.storageSource | string |
False | • string | 입력에 대한 스토리지 원본입니다. 기본값은 AzureBlob입니다. |
inputs.targets
대상 및 용어집 데이터에 대한 정의입니다.
| 키 매개 변수 | Type | Required | 요청 매개 변수 | 설명 |
|---|---|---|---|---|
| inputs.targets | array |
True | • targetUrl(문자열) • category(문자열) • language(문자열) • glossaries(배열) • storageSource(문자열) |
번역된 문서의 대상 및 용어집 데이터입니다. |
| inputs.targets.targetUrl | string |
True | • string | 번역된 문서에 대한 컨테이너 위치입니다. |
| inputs.targets.category | string |
False | • string | 번역 요청에 대한 분류 또는 범주입니다. 예: 일반. |
| inputs.targets.language | string |
True | • string | 대상 언어 코드입니다. 예: "fr". |
| inputs.targets.glossaries | array |
False | • glossaryUrl(문자열) • format(문자열) • version(문자열) • storageSource(문자열) |
참조 항목: 용어집 만들기 및 사용 |
| inputs.targets.glossaries.glossaryUrl | string |
True(용어집을 사용할 경우) | • string | 용어집의 위치입니다. 서식 매개 변수가 제공되지 않으면 파일 확장명을 사용하여 서식을 추출합니다. 번역 언어 쌍이 용어집에 없으면 적용되지 않습니다. |
| inputs.targets.glossaries.format | string |
False | • string | 용어집에 지정된 파일 형식입니다. 파일 형식이 지원되는지 확인하려면 용어집 형식 가져오기를 참조하세요. |
| inputs.targets.glossaries.version | string |
False | • string | 버전 표시기입니다. 예: "2.0". |
| inputs.targets.glossaries.storageSource | string |
False | • string | 용어집에 대한 스토리지 원본입니다. 기본값은 _AzureBlob_입니다. |
| inputs.targets.storageSource | string |
False | • string | targets.defaults에 대한 스토리지 원본을 _AzureBlob_. |
inputs.storageType
입력 문서에 대한 스토리지 엔터티의 정의입니다.
| 키 매개 변수 | Type | Required | 요청 매개 변수 | 설명 |
|---|---|---|---|---|
| inputs.storageType | string |
False | •Folder• File |
입력 문서 원본 문자열의 스토리지 형식입니다. “Folder” 또는 “File”만 유효한 값입니다. |
옵션
입력 일괄 처리 변환 요청에 대한 정의입니다.
| 키 매개 변수 | Type | Required | 요청 매개 변수 | 설명 |
|---|---|---|---|---|
| options | object |
False | 입력 문서에 대한 원본 정보입니다. | |
| options.experimental | boolean |
False | •true• false |
요청에 실험적 기능이 포함되어 있는지 여부를 나타냅니다(해당하는 경우). 부울 true 또는 false만 유효한 값입니다. |
예제 요청
다음은 일괄 처리 요청의 예입니다.
참고 항목
다음 예제에서는 SAS(공유 액세스 서명) 토큰을 사용하여 Azure Storage 컨테이너의 콘텐츠에 제한된 액세스 권한을 부여했습니다.
컨테이너의 모든 문서 번역
{
"inputs": [
{
"source": {
"sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
},
"targets": [
{
"targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
"language": "fr"
}
]
}
]
}
용어집을 적용하는 컨테이너의 모든 문서 번역
{
"inputs": [
{
"source": {
"sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
},
"targets": [
{
"targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
"language": "fr",
"glossaries": [
{
"glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?{SAS-token-query-string}",
"format": "xliff",
"version": "1.2"
}
]
}
]
}
]
}
컨테이너의 특정 폴더 번역
폴더 이름(대/소문자 구분)을 필터의 접두사로 지정해야 합니다.
{
"inputs": [
{
"source": {
"sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}",
"filter": {
"prefix": "MyFolder/"
}
},
"targets": [
{
"targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
"language": "fr"
}
]
}
]
}
컨테이너에서 특정 문서 번역
- "storageType"을 지정합니다
File. - 특정 Blob/문서에 대한 원본 URL 및 SAS 토큰을 만듭니다.
- SAS 토큰은 컨테이너용이지만 대상 파일 이름을 대상 URL의 일부로 지정합니다.
이 샘플 요청은 두 개의 대상 언어로 번역된 단일 문서를 보여 줍니다.
{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?{SAS-token-query-string}"
},
"targets": [
{
"targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?{SAS-token-query-string}",
"language": "es"
},
{
"targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?{SAS-token-query-string}",
"language": "de"
}
]
}
]
}
응답 상태 코드
요청을 반환하는 가능한 HTTP 상태 코드는 다음과 같습니다.
| 상태 코드 | 설명 |
|---|---|
| 202 | 허용. 성공적인 요청 및 일괄 처리 요청이 만들어졌습니다. 헤더 Operation-Location은 작업 ID.HeadersOperation-Location: string을 통해 상태 URL을 나타냅니다. |
| 400 | 잘못된 요청. 잘못된 요청입니다. 입력 매개 변수를 확인하세요. |
| 401 | 권한이 없습니다. 자격 증명을 확인합니다. |
| 429 | 요청 속도가 너무 높습니다. |
| 500 | 내부 서버 오류. |
| 503 | 현재 서비스를 사용할 수 없습니다. 나중에 다시 시도하세요. |
| 기타 상태 코드 | • 요청이 너무 많습니다. 서버를 일시적으로 사용할 수 없음 |
오류 응답
| 키 매개 변수 | Type | 설명 |
|---|---|---|
| 코드 | string |
상위 수준 오류 코드를 포함하는 열거형입니다. 가능한 값:</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • 권한 없음 |
| message | string |
상위 수준 오류 메시지를 가져옵니다. |
| innerError | InnerTranslationError | Azure AI 서비스 API 지침을 준수하는 새로운 내부 오류 형식입니다. 이 오류 메시지에는 ErrorCode, 메시지 및 선택적 속성 대상, 세부 정보(키 값 쌍) 및 내부 오류(중첩될 수 있음)와 같은 필수 속성이 포함됩니다. |
| inner.Errorcode | string |
코드 오류 문자열을 가져옵니다. |
| innerError.message | string |
상위 수준 오류 메시지를 가져옵니다. |
| innerError.target | string |
오류의 원인을 가져옵니다. 예를 들어, 문서가 유효하지 않으면 documents 또는 document id가 됩니다. |
오류 응답 예
{
"error": {
"code": "ServiceUnavailable",
"message": "Service is temporary unavailable",
"innerError": {
"code": "ServiceTemporaryUnavailable",
"message": "Service is currently unavailable. Please try again later"
}
}
}
다음 단계
빠른 시작에 따라 문서 번역 및 클라이언트 라이브러리 사용에 대해 자세히 알아보세요.