Поделиться через

Работа с API, действия в которых могут выполняться длительное время

  • Статья

Некоторые сценарии, например копирование или отправка данных из URL-адреса, не удается выполнить за конечное количество времени. Для обработки этих сценариев и сохранения минимальных задержек для ответов API такие действия реализованы с использованием схемы действий, выполняющихся длительное время.

  1. Приложение запрашивает действие, выполняющееся длительное время, через API. API принимает действие и возвращает ответ 202 Accepted вместе с заголовком Location для URL-адреса API, чтобы можно было получать отчеты о состоянии действий.
  2. Приложение запрашивает URL-адрес отчета о состоянии действий и получает ответ AsyncJobStatus со сведениями о ходе выполнения действия, выполняющегося длительное время.
  3. Действие, выполняющееся длительное время, завершается. В следующий раз приложение запросит URL-адрес отчета о состоянии действия и получит отклик AsyncJobStatus при завершении действия.

Начальный запрос действия

Давайте по шагам рассмотрим пример сценария копирования. В этом сценарии приложение запрашивает операцию копирования папки, в которой содержится большое количество данных. На выполнение этого запроса, вероятно, потребуется несколько секунд, так как необходимо передать большой объем данных.

POST /drive/items/{folder-item-id}/copy
Content-Type: application/json
Prefer: respond-async

{
  "parentReference": {
    "path": "/drive/root:/Documents"
  },
  "name": "Copy of LargeFolder1"
}

API отправляет ответ о том, что действие принято, и URL-адрес для получения сведений о состоянии действия, выполняющегося длительное время.

HTTP/1.1 202 Accepted
Location: https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

Во многих случаях это может быть завершением запроса, так как действие копирования будет выполняться без каких-либо дополнительных действий со стороны приложения. Тем не менее если приложению необходимо отображать состояние действия копирования или убедиться, что оно выполнено без ошибок, приложение может сделать это, используя URL-адрес для отслеживания.

Получение отчета о состоянии с URL-адреса для отслеживания

Чтобы проверить состояние действия копирования, приложение отправляет запрос на URL-адрес, указанный в предыдущем отклике. Примечание. Для этого запроса не нужно выполнять аутентификацию, так как этот URL-адрес действует в течение небольшого времени и является уникальным для исходного вызывающего объекта.

GET https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

Служба возвращает ответ со сведениями о том, что действие, выполняющееся длительное время, еще не завершено:

HTTP/1.1 202 Accepted
Content-type: application/json

{
  "operation": "ItemCopy",
  "percentageComplete": 27.8,
  "status": "inProgress"
}

Эти сведения можно использовать для обновления информации о ходе копирования для пользователя. Приложение может продолжить опрашивать URL-адрес для отслеживания, чтобы получать обновленные сведения о ходе выполнения действия.

Получение отчета о выполнении действия с URL-адреса для отслеживания

Через несколько секунд операция копирования завершается. На этот раз, когда приложение отправляет запрос на URL-для отслеживания, ответом будет перенаправление на результат выполненного действия.

GET https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

По завершении действия в отклике службы отслеживания будет возвращен идентификатор ресурса для результатов.

HTTP/1.1 303 See Other
Content-type: application/json

{
    "percentageComplete": 100.0,
    "resourceId": "01MOWKYVJML57KN2ANMBA3JZJS2MBGC7KM",
    "status": "completed"
}

Получение результатов выполненной операции