참조
기능: Azure AI Translator → 문서 번역
API 버전: 2024-05-01
HTTP 메서드: GET
이 메서드를
get translations status사용하여 사용자가 제출한 모든 번역 작업의 목록 및 상태를 요청합니다(리소스와 연결됨).$top,$skip및$maxpagesize쿼리 매개 변수를 사용하여 반환할 결과 수와 컬렉션의 오프셋을 지정할 수 있습니다.-
$top는 모든 페이지에서 반환할 총 레코드 수를 나타냅니다. -
$skip은(는) 지정된 정렬 방법에 따라 배치 목록에서 건너뛸 레코드 수를 나타냅니다. 기본적으로 레코드는 내림차순 시작 시간을 기준으로 정렬됩니다. -
$maxpagesize은 페이지에 반환된 최대 항목입니다. -
$top을 통해 추가 항목이 요청된 경우(또는$top가 지정되지 않았고 반환할 항목이 더 있는 경우)@nextLink에는 다음 페이지에 대한 링크가 포함됩니다. - 서버는 클라이언트에서 지정한 값을 준수합니다. 그러나 클라이언트는 다른 페이지 크기나 연속 토큰이 포함된 응답을 처리할 수 있도록 준비되어야 합니다.
- 둘 다
$top$skip포함되면 서버가 먼저 적용된 다음$top컬렉션에 적용됩니다$skip.
-
참고 항목
서버가 $top 및/또는 $skip를 준수할 수 없는 경우 서버는 쿼리 옵션을 무시하는 대신 이에 대해 알리는 오류를 클라이언트에 반환해야 합니다. 이 작업은 클라이언트가 반환된 데이터에 대해 가정할 위험을 줄입니다.
-
$orderBy쿼리 매개 변수를 사용하여 반환된 목록(예:$orderBy=createdDateTimeUtc asc또는$orderBy=createdDateTimeUtc desc)을 정렬할 수 있습니다.- 기본 정렬은 다음을
createdDateTimeUtc기준으로 내림차순입니다. 일부 쿼리 매개 변수를 사용하여 반환된 목록(예:status=Succeeded,Cancelled) 반환 성공 및 취소된 작업을 필터링할 수 있습니다. - 반환된
createdDateTimeUtcStart목록을 필터링할 날짜/시간 범위를 지정하기 위해 쿼리 매개 변수와createdDateTimeUtcEnd쿼리 매개 변수를 개별적으로 결합하거나 사용할 수 있습니다. - 지원되는 필터링 쿼리 매개 변수는 (
status,id,createdDateTimeUtcStart및createdDateTimeUtcEnd)입니다.
- 기본 정렬은 다음을
요청 URL
curl -i -X GET "{document-translation-endpoint}/translator/document/batches?api-version={date}"
중요합니다
문서 번역 기능에 대한 모든 API 요청에는 Azure Portal의 리소스 개요 페이지에 있는 사용자 지정 도메인 엔드포인트가 필요합니다.
요청 매개 변수
쿼리 문자열에 전달된 요청 매개 변수는 다음과 같습니다.
| 쿼리 매개 변수 | 그런 다음 | 필수 | 유형 | 설명 |
|---|---|---|---|---|
$maxpagesize |
문의 | 거짓 | 정수 int32 |
$maxpagesize은 페이지에 반환된 최대 항목입니다.
$top을 통해 추가 항목이 요청된 경우(또는 $top가 지정되지 않았고 반환할 항목이 더 있는 경우) @nextLink에는 다음 페이지에 대한 링크가 포함됩니다. 클라이언트는 $maxpagesize 기본 설정을 지정하여 특정 페이지 크기로 서버 기반 페이징을 요청할 수 있습니다. 지정된 페이지 크기가 서버의 기본 페이지 크기보다 작은 경우 서버는 이 기본 설정을 준수해야 합니다. |
$orderBy |
문의 | 거짓 | 배열 | 컬렉션에 대한 정렬 쿼리(예: CreatedDateTimeUtc asc, CreatedDateTimeUtc desc) |
$skip |
문의 | 거짓 | 정수 int32 |
$skip은(는) 지정된 정렬 방법에 따라 서버가 보유한 레코드 목록에서 건너뛸 레코드 수를 나타냅니다. 기본적으로는 시작 시간을 내림차순으로 정렬합니다. 클라이언트는 $top 및 $skip 쿼리 매개 변수를 사용하여 반환할 결과 수와 컬렉션에 대한 오프셋을 지정할 수 있습니다. 클라이언트가 $top 및 $skip를 모두 반환하는 경우 서버는 먼저 컬렉션에 $skip을(를) 적용한 다음 $top를 적용해야 합니다. 참고: 서버가 $top 및/또는 $skip를 적용할 수 없는 경우 서버는 쿼리 옵션을 무시하는 대신 이에 대해 알리는 오류를 클라이언트에 반환해야 합니다. |
$top |
문의 | 거짓 | 정수 int32 |
$top은 사용자가 모든 페이지에서 반환되기를 원하는 총 레코드 수를 나타냅니다. 클라이언트는 $top 및 $skip 쿼리 매개 변수를 사용하여 반환할 결과 수와 컬렉션에 대한 오프셋을 지정할 수 있습니다. 클라이언트가 $top 및 $skip를 모두 반환하는 경우 서버는 먼저 컬렉션에 $skip을(를) 적용한 다음 $top를 적용해야 합니다. 참고: 서버가 $top 및/또는 $skip를 적용할 수 없는 경우 서버는 쿼리 옵션을 무시하는 대신 이에 대해 알리는 오류를 클라이언트에 반환해야 합니다. |
createdDateTimeUtcEnd |
문의 | 거짓 | 문자열 날짜-시간 | 이전에 항목을 가져올 종료 날짜/시간입니다. |
createdDateTimeUtcStart |
문의 | 거짓 | 문자열 날짜-시간 | 항목을 가져올 시작 날짜/시간입니다. |
ids |
문의 | 거짓 | 배열 | 필터링에 사용할 ID입니다. |
statuses |
문의 | 거짓 | 배열 | 필터링에 사용할 상태입니다. |
요청 헤더
요청 헤더는 다음과 같습니다.
| 헤더 | 설명 | 조건 |
|---|---|---|
| Ocp-Apim-Subscription-Key | Azure Portal의 Translator Service API 키입니다. | 필수 |
| Ocp-Apim-Subscription-Region | 리소스를 만든 지역입니다. |
미국 서부와 같은 지역(지리적) 리소스를 사용할 때 필요합니다. 글머리 기호입니다. |
| 콘텐츠-타입 | 페이로드의 콘텐츠 형식입니다. 허용되는 값은 application/json 또는 charset=UTF-8입니다. | 필수 |
응답 상태 코드
요청을 반환하는 가능한 HTTP 상태 코드는 다음과 같습니다.
| 상태 코드 | 설명 |
|---|---|
| 200 | 그래. 요청이 성공하고 모든 작업의 상태를 반환합니다. HeadersRetry-After: integerETag: string |
| 400 | 잘못된 요청. 잘못된 요청입니다. 입력 매개 변수를 확인하세요. |
| 401 | 권한이 없습니다. 자격 증명을 확인합니다. |
| 500 | 내부 서버 오류. |
| 기타 상태 코드 | • 요청이 너무 많음 • 서버를 일시적으로 사용할 수 없음 |
번역 상태 응답 가져오기
성공적인 번역 가져오기 상태 응답
성공적인 응답에서 반환되는 정보는 다음과 같습니다.
| 속성 | 유형 | 설명 |
|---|---|---|
| @nextLink | 문자열 | 다음 페이지의 URL입니다. 사용 가능한 페이지가 더 이상 없으면 Null입니다. |
| 가치 | TranslationStatus[] | TranslationStatus[] 배열 |
| value.id | 문자열 | 작업의 ID입니다. |
| value.createdDateTimeUtc | 문자열 | 작업에서 만든 날짜 시간입니다. |
| value.lastActionDateTimeUtc | 문자열 | 작업 상태가 업데이트된 날짜 시간입니다. |
| value.status | 문자열 | 작업 또는 문서의 가능한 상태 목록: • 취소됨 •취소 •실패 • NotStarted •달리기 •성공 • ValidationFailed |
| value.summary | StatusSummary[] | 나열된 세부 정보가 포함된 요약입니다. |
| value.summary.total | 정수 | 총 문서 수입니다. |
| value.summary.failed | 정수 | 실패한 문서 수입니다. |
| value.summary.success | 정수 | 성공적으로 번역된 문서 수입니다. |
| value.summary.inProgress | 정수 | 진행 중인 문서 수입니다. |
| value.summary.notYetStarted | 정수 | 아직 처리를 시작하지 않은 문서 수입니다. |
| value.summary.cancelled | 정수 | 취소된 문서 수입니다. |
| value.summary.totalCharacterCharged | 정수 | 처리해야 하는 총 문자 수입니다. |
오류 응답
| 속성 | 유형 | 설명 |
|---|---|---|
| 코드 | 문자열 | 상위 수준 오류 코드를 포함하는 열거형입니다. 허용되는 값: • InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable •무단 |
| 메시지 | 문자열 | 상위 수준 오류 메시지를 가져옵니다. |
| 목표 | 문자열 | 오류의 원인을 가져옵니다. 예를 들어 잘못된 문서가 있는 경우 documents 또는 document id이(가) 됩니다. |
| 내부 오류 | InnerTranslationError | Azure AI 서비스 API 지침을 준수하는 새로운 내부 오류 형식입니다. 이 오류 메시지에는 필수 속성 ErrorCode, 메시지 및 선택적 속성 target, 세부 정보(키 값 쌍), 내부 오류(중첩 가능)가 포함되어 있습니다. |
| innerError.코드 | 문자열 | 코드 오류 문자열을 가져옵니다. |
| 내부오류.메시지 | 문자열 | 상위 수준 오류 메시지를 가져옵니다. |
| innerError.target | 문자열 | 오류의 원인을 가져옵니다. 예를 들어 잘못된 문서가 있는 경우 documents 또는 document id이(가) 됩니다. |
예제
성공적인 응답 예제
다음 JSON 개체는 성공적인 응답의 예입니다.
{
"value": [
{
"id": "36724748-f7a0-4db7-b7fd-f041ddc75033",
"createdDateTimeUtc": "2021-06-18T03:35:30.153374Z",
"lastActionDateTimeUtc": "2021-06-18T03:36:44.6155316Z",
"status": "Succeeded",
"summary": {
"total": 3,
"failed": 2,
"success": 1,
"inProgress": 0,
"notYetStarted": 0,
"cancelled": 0,
"totalCharacterCharged": 0
}
},
{
"id": "1c7399a7-6913-4f20-bb43-e2fe2ba1a67d",
"createdDateTimeUtc": "2021-05-24T17:57:43.8356624Z",
"lastActionDateTimeUtc": "2021-05-24T17:57:47.128391Z",
"status": "Failed",
"summary": {
"total": 1,
"failed": 1,
"success": 0,
"inProgress": 0,
"notYetStarted": 0,
"cancelled": 0,
"totalCharacterCharged": 0
}
},
{
"id": "daa2a646-4237-4f5f-9a48-d515c2d9af3c",
"createdDateTimeUtc": "2021-04-14T19:49:26.988272Z",
"lastActionDateTimeUtc": "2021-04-14T19:49:43.9818634Z",
"status": "Succeeded",
"summary": {
"total": 2,
"failed": 0,
"success": 2,
"inProgress": 0,
"notYetStarted": 0,
"cancelled": 0,
"totalCharacterCharged": 21899
}
}
],
""@nextLink": "https://westus.cognitiveservices.azure.com/translator/text/batch/v1.1/operations/727BF148-F327-47A0-9481-ABAE6362F11E/documents?`$top`=5&`$skip`=15"
}
오류 응답 예
다음 JSON 객체는 오류 응답의 예입니다. 다른 오류 코드에 대한 스키마는 동일합니다.
상태 코드: 500
{
"error": {
"code": "InternalServerError",
"message": "Internal Server Error",
"target": "Operation",
"innerError": {
"code": "InternalServerError",
"message": "Unexpected internal server error has occurred"
}
}
}
다음 단계
빠른 시작에 따라 문서 번역 및 클라이언트 라이브러리 사용에 대해 자세히 알아보세요.