Получение сведений о состоянии документов

Если количество документов в ответе превышает наш предел разбиения на страницы, используется разбиение на страницы на стороне сервера. Ответы, разбитые на страницы, указывают на частичный результат и включают в ответ маркер продолжения. Отсутствие маркера продолжения означает, что дополнительные страницы недоступны.

Параметры запроса $top, $skip и $maxpagesize можно использовать для настройки количества возвращаемых результатов и смещения по коллекции.

$top обозначает общее число записей, которые пользователь хочет вернуть на всех страницах. $skip указывает количество состояний документов, пропускаемых в сохраняемом на сервере списке на основе указанного метода сортировки. По умолчанию сортировка выполняется по убыванию времени начала. $maxpagesize — максимальное число элементов, возвращаемых на странице. Если с помощью $top запрошено больше элементов (или значение $top не указано, а число возвращаемых элементов больше), @nextLink будет содержать ссылку на следующую страницу.

Параметр запроса $orderBy можно использовать для сортировки возвращаемого списка (например, "$orderBy=createdDateTimeUtc asc" или "$orderBy=createdDateTimeUtc desc"). По умолчанию сортировка выполняется по убыванию значения createdDateTimeUtc. Некоторые параметры запроса можно использовать для фильтрации возвращаемого списка (например, "status=Succeeded,Cancelled" возвращает только выполненные и отмененные документы). Параметры createdDateTimeUtcStart и createdDateTimeUtcEnd можно использовать вместе или по отдельности, чтобы задать диапазон значений даты и времени для фильтрации возвращаемого списка. Поддерживаемые параметры запроса фильтрации: status, ID, createdDateTimeUtcStart, createdDateTimeUtcEnd.

При включении параметров $top, и $skip сервер должен сначала применить $skip, а затем $top к коллекции.

Примечание

Если сервер не может соблюдать $top и/или $skip, сервер должен вернуть клиенту сообщение об ошибке, а не просто игнорировать параметры запроса. Это снижает риск того, что клиент сделает предположения о возвращаемых данных.

URL-адрес запроса

Отправьте запрос GET на следующий адрес.

GET https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches/{id}/documents

Узнайте, как найти имя личного домена.

Важно!

  • Конечную точку личного домена необходимо указывать во всех запросах API к службе перевода документов.
  • Вы не можете использовать конечную точку, найденную в портал Azure ключах ресурсов и конечной точке глобального преобразователя, — для выполнения HTTP-запросов к преобразованию документов.

Параметры запроса

В таблице ниже приведены параметры, которые передаются в строке запроса.

Параметр запроса В Обязательно Тип Описание
идентификатор path True строка Идентификатор операции.
maxPageSize query Неверно целое число (int32) $maxpagesize — максимальное число элементов, возвращаемых на странице. Если с помощью $top запрошено больше элементов (или значение $top не указано, а число возвращаемых элементов больше), @nextLink будет содержать ссылку на следующую страницу. Клиенты МОГУТ запрашивать разбиение на страницы определенного размера на сервере с помощью параметра $maxpagesize. Сервер ДОЛЖЕН учитывать этот параметр, если размер страницы меньше, чем размер по умолчанию на сервере.
$orderBy query Неверно array Запрос сортировки для коллекции (например, "CreatedDateTimeUtc asc", "CreatedDateTimeUtc desc").
$skip query Неверно целое число (int32) $skip указывает количество записей, пропускаемых в сохраняемом на сервере списке на основе указанного метода сортировки. По умолчанию сортировка выполняется по убыванию времени начала. Клиенты МОГУТ использовать параметры запроса $top и $skip для указания количества возвращаемых результатов и смещения по коллекции. Если указаны оба параметра $top и $skip, сервер должен сначала применить для коллекции параметр $skip, а затем — $top. Если сервер не может соблюсти $top и (или) $skip, оно должен вернуть клиенту сообщение об ошибке, а не просто проигнорировать параметры запроса.
$top query Неверно целое число (int32) $top обозначает общее число записей, которые пользователь хочет вернуть на всех страницах. Клиенты МОГУТ использовать параметры запроса $top и $skip для указания количества возвращаемых результатов и смещения по коллекции. Если указаны оба параметра $top и $skip, сервер должен сначала применить для коллекции параметр $skip, а затем — $top. Если сервер не может соблюсти $top и (или) $skip, оно должен вернуть клиенту сообщение об ошибке, а не просто проигнорировать параметры запроса.
createdDateTimeUtcEnd query Неверно строка (дата-время) Конечное значение даты и времени для получения элементов.
createdDateTimeUtcStart query Неверно строка (дата-время) Начальное значение даты и времени для получения элементов.
ids query Неверно array Идентификаторы, используемые при фильтрации.
statuses query Неверно array Состояния, используемые при фильтрации.

Заголовки запросов

Заголовки запроса.

Заголовки Описание
Ocp-Apim-Subscription-Key Обязательный заголовок запроса

Коды состояния ответа

Ниже приведены возможные коды состояния HTTP, которые возвращает запрос.

Код состояния Описание
200 Все в порядке. Успешный запрос и возвращает статус документов. HeadersRetry-After: integerETag: строка
400 Недопустимый запрос. Проверьте входные параметры.
401 Не авторизовано. Проверьте свои учетные данные.
404 Ресурс не найден.
500 Внутренняя ошибка сервера.
Другие коды состояния
  • Слишком много запросов
  • Сервер временно недоступен

Получить ответ о статусе документов

Успешный ответ на получение статуса документов

В случае успешного ответа возвращается следующая информация.

Имя Тип Описание
@nextLink строка URL следующей страницы. Нулевое значение, если доступных страниц больше нет.
value DocumentStatus [] Подробный статус отдельных документов указан ниже.
value.path строка Расположение документа или папки.
value.sourcePath строка Расположение исходного документа.
value.createdDateTimeUtc строка Дата и время создания операции.
value.lastActionDateTimeUtc строка Дата и время, когда был обновлен статус операции.
value.status status Список возможных статусов работы или документа.
  • Отменено
  • Cancelling
  • Сбой
  • NotStarted
  • Запущен
  • Выполнено
  • ValidationFailed,
value.to строка К языку.
value.progress number Ход выполнения перевода (если доступно).
value.id строка Идентификатор документа.
value.characterCharged Целое число Символы, учитываемые в API.

Сообщение об ошибке

Имя Тип Описание
code строка Перечисления с высокоуровневыми кодами ошибок. Возможные значения:
  • InternalServerError
  • InvalidArgument
  • InvalidRequest
  • RequestRateTooHigh
  • ResourceNotFound
  • ServiceUnavailable
  • Не авторизовано
message строка Получает сообщение об ошибке высокого уровня.
target строка Получает источник ошибки. Например, в случае недействительного документа это будет "документы" или «"дентификатор документа".
innerError InnerTranslationError Новый формат внутренней ошибки, соответствующий рекомендациям API Cognitive Services. Он содержит обязательные свойства ErrorCode и message, а также необязательные свойства target, details (пара "ключ-значение"), inner error (это свойство может быть вложенным).
innerError.code строка Получение строки с кодом ошибки.
innerError.message строка Получение высокоуровневого сообщения об ошибке.
innerError.target строка Получает источник ошибки. К примеру, для недопустимого документа это будет "документы" или "идентификатор документа".

Примеры

Пример успешного ответа

Ниже приведен пример успешного ответа.

{
  "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.0/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55/documents?$top=5&$skip=15"
}

Пример ответа с ошибкой

Ниже приведен пример ответа с ошибкой. Схема для других кодов ошибок такая же.

Код состояния: 500

{
  "error": {
    "code": "InternalServerError",
    "message": "Internal Server Error",
    "target": "Operation",
    "innerError": {
      "code": "InternalServerError",
      "message": "Unexpected internal server error has occurred"
    }
  }
}

Дальнейшие действия

Чтобы узнать больше об использовании службы перевода документов и клиентской библиотеки, обратитесь к нашему краткому руководству.