다음을 통해 공유

모든 문서에 대한 상태 가져오기

  • 아티클

참조
기능: Azure AI 번역기 → 문서 번역
 API 버전: 2024-05-01
HTTP 메서드: GET

Important

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

  • 이 메서드를 get documents status 사용하여 번역 작업의 모든 문서에 대한 상태 요청합니다.

  • $top, $skip 및 $maxpagesize 쿼리 매개 변수를 사용하여 반환할 결과 수와 컬렉션의 오프셋을 지정할 수 있습니다.

    • $top은 사용자가 모든 페이지에서 반환되기를 원하는 총 레코드 수를 나타냅니다.
    • $skip은 지정된 정렬 방법에 따라 서버가 보유한 문서 상태 목록에서 건너뛸 레코드 수를 나타냅니다. 기본적으로 레코드는 내림차순 시작 시간을 기준으로 정렬됩니다.
    • $maxpagesize은 페이지에 반환된 최대 항목입니다.
    • $top을 통해 추가 항목이 요청된 경우(또는 $top가 지정되지 않았고 반환할 항목이 더 있는 경우) @nextLink에는 다음 페이지에 대한 링크가 포함됩니다.
    • 응답의 문서 수가 페이징 제한을 초과하면 서버 측 페이징이 사용됩니다.
    • 페이지가 매겨진 응답은 부분 결과를 나타내며 응답에 연속 토큰을 포함합니다. 연속 토큰이 없으면 다른 페이지를 사용할 수 없습니다.

참고 항목

서버가 $top 및/또는 $skip를 준수할 수 없는 경우 서버는 쿼리 옵션을 무시하는 대신 이에 대해 알리는 오류를 클라이언트에 반환해야 합니다. 이렇게 하면 클라이언트가 반환된 데이터에 대해 가정할 위험이 줄어듭니다.

  • $orderBy 쿼리 매개 변수를 사용하여 반환된 목록(예: $orderBy=createdDateTimeUtc asc 또는 $orderBy=createdDateTimeUtc desc)을 정렬할 수 있습니다.
  • 기본 정렬은 다음을 createdDateTimeUtc기준으로 내림차순입니다. 일부 쿼리 매개 변수는 반환된 목록(예: status=Succeeded,Cancelled)을 필터링하는 데 성공 및 취소된 문서만 반환하는 데 사용할 수 있습니다.
  • 쿼리 매개 변수와 createdDateTimeUtcEnd 쿼리 매개 변수를 createdDateTimeUtcStart 결합하거나 별도로 사용하여 반환된 목록을 필터링하는 날짜/시간 범위를 지정할 수 있습니다.
  • 지원되는 필터링 쿼리 매개 변수는 (status, id, createdDateTimeUtcStart및 createdDateTimeUtcEnd)입니다.
  • $top과 $skip가 모두 포함된 경우 서버는 먼저 컬렉션에 $skip을 적용한 다음 $top를 적용해야 합니다.

요청 URL

다음에 GET 요청을 보냅니다.

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

id 값 찾기

  • POST start-batch-translation 메서드 응답 헤더 Operation-Location URL 값에서 작업을 id 찾을 수 있습니다. 매개 변수 다음에 있는 /document/ 영숫자 문자열은 작업의 작업입니다.id
응답 헤더 응답 URL
Operation-Location {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01

요청 매개 변수

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

쿼리 매개 변수 그런 다음 필수 Type 설명
id path True string 작업 ID입니다.
$maxpagesize query False integer int32 $maxpagesize은 페이지에 반환된 최대 항목입니다. $top을 통해 추가 항목이 요청된 경우(또는 $top가 지정되지 않았고 반환할 항목이 더 있는 경우) @nextLink에는 다음 페이지에 대한 링크가 포함됩니다. 클라이언트는 기본 설정을 지정하여 특정 페이지 크기로 서버 기반 페이징을 $maxpagesize 요청할 수 있습니다. 지정된 페이지 크기가 서버의 기본 페이지 크기보다 작은 경우 서버는 이 기본 설정을 준수해야 합니다.
$orderBy query False 배열 컬렉션에 대한 정렬 쿼리입니다(예: CreatedDateTimeUtc asc, CreatedDateTimeUtc desc).
$skip query False integer int32 $skip 지정된 정렬 방법에 따라 서버에서 보유하는 레코드 목록에서 건너뛸 레코드 수를 나타냅니다. 기본적으로는 시작 시간을 내림차순으로 정렬합니다. 클라이언트는 $top 및 $skip 쿼리 매개 변수를 사용하여 반환할 결과 수와 컬렉션에 대한 오프셋을 지정할 수 있습니다. 클라이언트가 $top과 $skip를 모두 반환하는 경우 서버는 먼저 컬렉션에 $skip을 적용한 다음 $top를 적용해야 합니다. 서버가 적용 $top 할 $skip수 없는 경우 서버는 쿼리 옵션을 무시하는 대신 클라이언트에 오류를 반환해야 합니다.
$top query False integer 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의 번역기 서비스 API 키입니다. Required
Ocp-Apim-Subscription-Region 리소스를 만든 지역입니다. • 미국 서부와 같은 지역(지리적) 리소스를 사용할 때 필요합니다.
글머리 기호입니다.
Content-Type 페이로드의 콘텐츠 형식입니다. 허용되는 값은 application/json 또는 charset=UTF-8입니다. • 필수

응답 상태 코드

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

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

문서 상태 가져오기 응답

성공적인 문서 가져오기 상태 응답

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

속성 형식 설명
@nextLink string 다음 페이지의 URL입니다. 사용 가능한 페이지가 더 이상 없으면 Null입니다.
value DocumentStatus [] 개별 문서의 상세 상태 목록입니다.
value.path string 문서 또는 폴더의 위치입니다.
value.sourcePath string 원본 문서의 위치입니다.
value.createdDateTimeUtc string 작업에서 만든 날짜 시간입니다.
value.lastActionDateTimeUtc string 작업의 상태 업데이트되는 날짜 시간입니다.
값. 상태 status 작업 또는 문서에 사용할 수 있는 상태 목록입니다.
• 취소됨
•취소
•실패
• NotStarted
•실행
•성공
• ValidationFailed
value.to string 언어로.
value.progress 번호 번역 진행률(사용 가능한 경우)입니다.
value.id string 문서 ID입니다.
value.characterCharged 정수 API로 청구되는 문자 수입니다.

오류 응답

속성 형식 설명
코드 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-document-상태 쿼리 문자열에 대한 매개 변수를 검색 documentId 합니다.

성공적인 응답 예제

다음 JSON 개체는 성공적인 응답의 예입니다.

{
  "value": [
    {
      "path": "https://myblob.blob.core.windows.net/destinationContainer/fr/mydoc.txt",
      "sourcePath": "https://myblob.blob.core.windows.net/sourceContainer/fr/mydoc.txt",
      "createdDateTimeUtc": "2020-03-26T00:00:00Z",
      "lastActionDateTimeUtc": "2020-03-26T01:00:00Z",
      "status": "Running",
      "to": "fr",
      "progress": 0.1,
      "id": "273622bd-835c-4946-9798-fd8f19f6bbf2",
      "characterCharged": 0
    }
  ],
  "@nextLink": "https://westus.cognitiveservices.azure.com/translator/text/batch/v1.1/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55/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"
    }
  }
}

다음 단계

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

문서 번역 시작