다음을 통해 공유

모든 번역 작업의 상태 가져오기

  • 아티클

참조
기능: 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) 반환 성공 및 취소된 작업을 필터링할 수 있습니다.
    • 쿼리 매개 변수와 createdDateTimeUtcEnd 쿼리 매개 변수를 createdDateTimeUtcStart 결합하거나 별도로 사용하여 반환된 목록을 필터링하는 날짜/시간 범위를 지정할 수 있습니다.
    • 지원되는 필터링 쿼리 매개 변수는 (status, id, createdDateTimeUtcStart및 createdDateTimeUtcEnd)입니다.

요청 URL

  curl -i -X GET "{document-translation-endpoint}/translator/document/batches?api-version={date}"

Important

문서 번역 기능에 대한 모든 API 요청에는 Azure Portal의 리소스 개요 페이지에 있는 사용자 지정 도메인 엔드포인트가 필요합니다.

요청 매개 변수

쿼리 문자열에 전달된 요청 매개 변수는 다음과 같습니다.

쿼리 매개 변수 그런 다음 필수 Type 설명
$maxpagesize query False 정수 int32 $maxpagesize은 페이지에 반환된 최대 항목입니다. $top을 통해 추가 항목이 요청된 경우(또는 $top가 지정되지 않았고 반환할 항목이 더 있는 경우) @nextLink에는 다음 페이지에 대한 링크가 포함됩니다. 클라이언트는 $maxpagesize 기본 설정을 지정하여 특정 페이지 크기로 서버 기반 페이징을 요청할 수 있습니다. 지정된 페이지 크기가 서버의 기본 페이지 크기보다 작은 경우 서버는 이 기본 설정을 준수해야 합니다.
$orderBy query False 배열 컬렉션에 대한 정렬 쿼리(예: CreatedDateTimeUtc asc, CreatedDateTimeUtc desc)
$skip query False 정수 int32 $skip은(는) 지정된 정렬 방법에 따라 서버가 보유한 레코드 목록에서 건너뛸 레코드 수를 나타냅니다. 기본적으로는 시작 시간을 내림차순으로 정렬합니다. 클라이언트는 $top 및 $skip 쿼리 매개 변수를 사용하여 반환할 결과 수와 컬렉션에 대한 오프셋을 지정할 수 있습니다. 클라이언트가 $top 및 $skip를 모두 반환하는 경우 서버는 먼저 컬렉션에 $skip을(를) 적용한 다음 $top를 적용해야 합니다. 참고: 서버가 $top 및/또는 $skip를 적용할 수 없는 경우 서버는 쿼리 옵션을 무시하는 대신 이에 대해 알리는 오류를 클라이언트에 반환해야 합니다.
$top query False 정수 int32 $top은 사용자가 모든 페이지에서 반환되기를 원하는 총 레코드 수를 나타냅니다. 클라이언트는 $top 및 $skip 쿼리 매개 변수를 사용하여 반환할 결과 수와 컬렉션에 대한 오프셋을 지정할 수 있습니다. 클라이언트가 $top 및 $skip를 모두 반환하는 경우 서버는 먼저 컬렉션에 $skip을(를) 적용한 다음 $top를 적용해야 합니다. 참고: 서버가 $top 및/또는 $skip를 적용할 수 없는 경우 서버는 쿼리 옵션을 무시하는 대신 이에 대해 알리는 오류를 클라이언트에 반환해야 합니다.
createdDateTimeUtcEnd query False 문자열 날짜-시간 이전에 항목을 가져올 종료 날짜/시간입니다.
createdDateTimeUtcStart query False 문자열 날짜-시간 항목을 가져올 시작 날짜/시간입니다.
ids query False 배열 필터링에 사용할 ID입니다.
statuses query False 배열 필터링에 사용할 상태입니다.

요청 헤더

요청 헤더는 다음과 같습니다.

헤더 설명 조건
Ocp-Apim-Subscription-Key Azure Portal의 Translator Service API 키입니다. Required
Ocp-Apim-Subscription-Region 리소스를 만든 지역입니다. 미국 서부와 같은 지역(지리적) 리소스를 사용할 때 필요합니다.
글머리 기호입니다.
Content-Type 페이로드의 콘텐츠 형식입니다. 허용되는 값은 application/json 또는 charset=UTF-8입니다. Required

응답 상태 코드

요청을 반환하는 가능한 HTTP 상태 코드는 다음과 같습니다.

상태 코드 Description
200 OK. 요청이 성공하고 모든 작업의 상태를 반환합니다. HeadersRetry-After: integerETag: string
400 잘못된 요청. 잘못된 요청입니다. 입력 매개 변수를 확인하세요.
401 권한이 없습니다. 자격 증명을 확인합니다.
500 내부 서버 오류.
기타 상태 코드 • 요청이 너무 많음
• 서버를 일시적으로 사용할 수 없음

번역 상태 응답 가져오기

성공적인 번역 가져오기 상태 응답

성공적인 응답에서 반환되는 정보는 다음과 같습니다.

속성 형식 설명
@nextLink string 다음 페이지의 URL입니다. 사용 가능한 페이지가 더 이상 없으면 Null입니다.
value TranslationStatus[] TranslationStatus[] 배열
value.id string 작업의 ID입니다.
value.createdDateTimeUtc string 작업에서 만든 날짜 시간입니다.
value.lastActionDateTimeUtc string 작업 상태가 업데이트된 날짜 시간입니다.
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 정수 처리해야 하는 총 문자 수입니다.

오류 응답

속성 형식 설명
코드 string 상위 수준 오류 코드를 포함하는 열거형입니다. 가능한 값:
• InternalServerError
• InvalidArgument
• InvalidRequest
• RequestRateTooHigh
• ResourceNotFound
• ServiceUnavailable
•무단
message string 상위 수준 오류 메시지를 가져옵니다.
target string 오류의 원인을 가져옵니다. 예를 들어 잘못된 문서가 있는 경우 documents 또는 document id이(가) 됩니다.
innerError InnerTranslationError Azure AI 서비스 API 지침을 준수하는 새로운 내부 오류 형식입니다. 이 오류 메시지에는 필수 속성 ErrorCode, 메시지 및 선택적 속성 target, 세부 정보(키 값 쌍), 내부 오류(중첩 가능)가 포함되어 있습니다.
innerError.code string 코드 오류 문자열을 가져옵니다.
innerError.message string 상위 수준 오류 메시지를 가져옵니다.
innerError.target string 오류의 원인을 가져옵니다. 예를 들어 잘못된 문서가 있는 경우 documents 또는 document id이(가) 됩니다.

예제

팁

이 메서드를 사용하여 get-translation-status 쿼리 문자열에 대한 작업 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"
    }
  }
}

다음 단계

빠른 시작에 따라 문서 번역 및 클라이언트 라이브러리 사용에 대해 자세히 알아보세요.

문서 번역 시작