Управление длительными операциями

Длительная операция (LRO) — это метод API, выполнение которого занимает больше времени, чем это допустимо для ответа API. Как правило, нежелательно удерживать вызывающий поток открытым во время выполнения задачи, поскольку это ухудшает пользовательский опыт. Вместо этого лучше вернуть пользователю какое-либо обещание и позволить ему проверить результат позже.

API Google Drive возвращает LRO каждый раз, когда вы вызываете метод download ресурса files для загрузки содержимого файла либо через API Drive, либо через его клиентские библиотеки .

Этот метод возвращает клиенту ресурс operations . Вы можете использовать ресурс operations для асинхронного получения статуса метода API, опрашивая операцию через метод get . LRO в Drive API соответствуют шаблону проектирования LRO от Google Cloud .

Для получения более подробной информации см. раздел «Длительные операции» .

Обзор процесса

На следующей диаграмме показаны основные этапы работы метода file.download .

1. Вызов метода files.download : Когда ваше приложение вызывает метод download , оно запускает запрос на загрузку файла через Google Drive API. Для получения дополнительной информации см. раздел «Загрузка файлов» .

2. Запрос разрешений : Запрос отправляет учетные данные для аутентификации в API Google Диска. Если вашему приложению требуется вызов API Google Диска с использованием аутентификации пользователя, которая еще не предоставлена, оно запрашивает у пользователя вход в систему. Ваше приложение также запрашивает доступ с областями действия , которые вы указываете при настройке аутентификации.

3. Начало загрузки : Для начала загрузки файла отправляется запрос к API Google Диска. Запрос может быть отправлен в Google Видео или к другому контенту Google Рабочего пространства.

4. Запуск LRO : Начинается длительная операция, которая управляет процессом загрузки.

5. Возвращает ожидающую операцию : API Google Drive возвращает ожидающую операцию, содержащую информацию о пользователе, отправившем запрос, и несколько полей метаданных файла.

6. Начальное состояние ожидания : Ваше приложение получает сообщение об ожидающей операции вместе с начальным состоянием ожидания done=null . Это означает, что файл еще не готов к загрузке и что статус операции — ожидание.

7. Вызовите operations.get и проверьте результат : ваше приложение вызывает метод get с рекомендуемыми интервалами для опроса результата операции и получения последнего состояния длительной операции. Если возвращается состояние ожидания done=false , ваше приложение должно продолжать опрос до тех пор, пока операция не вернет состояние завершения ( done=true ). Для больших файлов ожидайте многократных опросов. Для получения дополнительной информации см. раздел «Получение подробной информации о длительной операции» .

8. Проверка состояния ожидания : если LRO возвращает состояние ожидания done=true , это означает, что файл готов к загрузке и операция завершена.

9. Возвращает завершенную операцию с URI загрузки : После завершения LRO API Google Drive возвращает URI загрузки, и файл становится доступен пользователю.

Скачать файлы

Для загрузки контента в рамках длительной операции используйте метод download ресурса files . Метод принимает параметры file_id , mime_type и revision_id :

• Обязательный параметр. Параметр file_id — это идентификатор файла для загрузки.

• Необязательный параметр. Параметр запроса mime_type указывает тип MIME, который должен использоваться методом. Он доступен только при загрузке медиаконтента, не являющегося BLOB-объектом (например, документов Google Workspace). Полный список поддерживаемых типов MIME см. в разделе «Экспорт типов MIME для документов Google Workspace» .

  Если тип MIME не указан, документ Google Workspace загружается с типом MIME по умолчанию. Дополнительную информацию см. в разделе «Типы MIME по умолчанию» .

• Необязательный параметр. Параметр запроса revision_id — это идентификатор ревизии загружаемого файла. Он доступен только при загрузке файлов BLOB, документов Google Docs и таблиц Google Sheets. Возвращает код ошибки INVALID_ARGUMENT при загрузке определенной ревизии для неподдерживаемых файлов.

Метод download — единственный способ скачать видеофайлы в формате MP4, и он, как правило, лучше всего подходит для загрузки большинства видеофайлов. При попытке экспорта файлов Google Vids вы получите ошибку fileNotExportable .

Ссылки для скачивания, сгенерированные для Google Docs или Sheets, изначально приводят к перенаправлению. Щелкните по новой ссылке, чтобы загрузить файл.

Запрос к методу download запускающему LRO, и запрос на получение конечного URI загрузки должны использовать ключи ресурсов. Дополнительную информацию см. в разделе «Доступ к файлам Google Диска, доступным по ссылкам, с помощью ключей ресурсов» .

Здесь представлен протокол запроса.

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

Замените FILE_ID на fileId файла, который вы хотите загрузить.

Типы MIME по умолчанию

Если при загрузке контента, не являющегося BLOB-объектом, не указан MIME-тип, по умолчанию назначаются следующие MIME-типы:

Скачать ответ

При вызове метода download тело ответа содержит ресурс, представляющий собой длительную операцию. Метод обычно возвращает ссылку для загрузки содержимого файла.

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

В этот вывод включены следующие значения:

• RESOURCE_KEY : Ключ ресурса помогает защитить ваш файл от несанкционированного доступа. Для получения дополнительной информации см. раздел «Доступ к файлам Google Диска, используемым в качестве общего ресурса, с помощью ключей ресурсов» .

• NAME : Имя, присвоенное сервером.

• DOWNLOAD_URI : Конечный URI для загрузки файла.

Обратите внимание, что поле partialDownloadAllowed указывает, разрешена ли частичная загрузка , и принимает true при загрузке содержимого BLOB-файла.

Узнайте подробности о давно работающей операции.

Длительные операции — это вызовы методов, выполнение которых может занять значительное количество времени. Как правило, вновь созданные операции загрузки изначально возвращаются в состоянии ожидания ( done=null ), особенно это касается видеофайлов.

Вы можете использовать ресурс operations , предоставляемый API Drive, чтобы проверить статус обработки LRO, указав уникальное имя, присвоенное сервером.

Метод get асинхронно получает последнее состояние длительной операции. Клиенты могут использовать этот метод для опроса результата операции с интервалами, рекомендованными API-сервисом.

Опрос – это давно существующая операция.

Для опроса доступного LRO многократно вызывайте метод get до завершения операции. Используйте экспоненциальную задержку между каждым запросом на опрос, например, 10 секунд.

Доступ к файлу LRO сохраняется как минимум 12 часов, но в некоторых случаях может быть продлен. Этот период может меняться и различаться в зависимости от типа файла. После истечения срока действия ресурса необходимо запросить новый способ download .

При выполнении любых запросов на get следует использовать ключи ресурсов. Дополнительную информацию см. в разделе «Доступ к файлам Google Диска, доступным по ссылкам, с помощью ключей ресурсов» .

Здесь представлены протоколы запросов.

operations.get(name='NAME');

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

Обратите внимание, что name возвращается только в ответе на запрос download . Другого способа получить его нет, поскольку API Google Drive не поддерживает метод list . Если значение name потеряно, необходимо сгенерировать новый ответ, повторно вызвав метод download .

Ответ на get -запрос представляет собой ресурс, отражающий длительную операцию. Для получения дополнительной информации см. раздел «Загрузка ответа» .

Когда ответ содержит состояние "завершено" ( done=true ), длительная операция завершена.

Скачать исправленную версию

Вы можете использовать значение поля headRevisionId из ресурса files для загрузки последней ревизии. Это позволит получить ревизию, соответствующую метаданным файла, который вы получили ранее. Чтобы загрузить данные для всех предыдущих ревизий файла, которые все еще хранятся в облаке, вы можете вызвать метод list ресурса revisions с параметром fileId . Это вернет все revisionIds в файле.

Для загрузки содержимого ревизий BLOB-файлов необходимо вызвать метод get ресурса ` revisions , указав идентификатор загружаемого файла, идентификатор ревизии и параметр ` alt=media URL`. Параметр alt=media URL` сообщает серверу, что запрашивается загрузка содержимого в альтернативном формате ответа.

Редактирование документов Google Docs, Sheets, Slides и видеороликов невозможно загрузить с помощью метода get с URL-адресом alt=media . В противном случае возникает ошибка fileNotDownloadable .

Параметр URL-адреса alt=media является системным параметром, доступным для всех REST API Google. Если вы используете клиентскую библиотеку для API Google Drive, вам не нужно явно указывать этот параметр.

Здесь представлен протокол запроса.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

Замените следующее:

• FILE_ID : fileId файла, который вы хотите загрузить.
• REVISION_ID : revisionId ревизии, которую вы хотите загрузить.

В документах Google Docs, Drawings и Slides номера версий автоматически увеличиваются. Однако в последовательности чисел могут быть пробелы, если версии были удалены, поэтому не следует полагаться на последовательные номера для восстановления версий.

Устранение неполадок LRO

При сбое LRO в ответе отображается стандартный код ошибки Google Cloud .

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

Более подробную информацию об этой модели ошибок и способах работы с ней можно найти в Руководстве по проектированию API .

Связанные темы

• Загрузка и экспорт файлов