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

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

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

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

Дополнительные сведения см. в разделе Длительные операции .

Примечание. И метод files.download() , и метод operations.get() используют обычную квоту Drive API. Дополнительную информацию см. в разделе Ограничения использования .

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

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

Рисунок 1. Общие шаги для метода file.download.

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

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

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

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

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

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

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

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

9. Возврат завершенной операции с URI загрузки . После завершения LRO Drive API возвращает 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 и Таблиц Google. Возвращает код ошибки INVALID_ARGUMENT при загрузке определенной версии неподдерживаемых файлов.

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

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

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

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

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

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

Примечание. Метод download() доступен только в Drive API v3.

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

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

Тип документа	Формат	MIME-тип	Расширение файла
Скрипт Google Apps	JSON	приложение/vnd.google-apps.script+json	.json
Google Документы	Microsoft Word	application/vnd.openxmlformats-officedocument.wordprocessingml.document	.docx
Гугл рисунки	PNG	изображение/png	.png
Google Формы	Почтовый индекс	приложение/zip	.zip
Google Таблицы	Майкрософт Эксель	Приложение/vnd.openxmlformats-officedocument.spreadsheetml.sheet	.xlsx
Google Сайты	Необработанный текст	текст/необработанный	.текст
Google Презентации	Microsoft PowerPoint	application/vnd.openxmlformats-officedocument.presentationml.presentation	.pptx
Google Видео	МП4	приложение/mp4	.mp4
Jamboard	PDF	приложение/pdf	.pdf

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

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

Совет: Сохраните значение поля name , так как оно понадобится вам для опроса LRO.

{
  "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 : ключ ресурса помогает защитить ваш файл от непреднамеренного доступа. Дополнительную информацию см. в разделе Доступ к файлам на Диске с общим доступом по ссылке с помощью ключей ресурсов .

• NAME : имя, назначенное сервером.

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

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

Получите подробную информацию о длительной операции

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

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

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

Примечание. Пользователь, отправляющий запрос метода get() должен совпадать с пользователем, который инициировал соседний запрос метода download() , иначе запрос завершится неудачно.

Опрос длительной операции

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

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

Любые запросы к get() должны использовать ключи ресурсов. Дополнительную информацию см. в разделе Доступ к файлам на Диске с общим доступом по ссылке с помощью ключей ресурсов .

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

Вызов метода

operations.get(name='NAME');

Замените NAME именем, назначенным сервером операции, как показано в ответе на запрос метода download() .

завиток

Примечание. В следующей команде предполагается, что вы вошли в интерфейс командной строки gcloud под своей учетной записью, запустив gcloud init или gcloud auth login или используя Cloud Shell , который автоматически выполняет вход в интерфейс командной строки gcloud. Вы можете проверить активную учетную запись, запустив gcloud auth list .

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

Замените NAME именем, назначенным сервером операции, как показано в ответе на запрос метода download() .

Команда использует путь /drive/v3/operations/ NAME .

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

Ответ на запрос get() состоит из ресурса, представляющего длительную операцию. Дополнительную информацию см. в разделе Загрузка ответа .

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

Скачать версию

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

Примечание. Доступ к историческим версиям ограничен в зависимости от роли. Прежде чем пытаться получить доступ, проверьте поле capabilities.canReadRevisions ресурса files .

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

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

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

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

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

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

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

Примечание. Если вы используете более старую версию Drive API v2, вам необходимо отправить авторизованный запрос GET к его свойству downloadUrl . Google Диск генерирует этот недолговечный URL-адрес, когда вы запрашиваете версию, но не полагаетесь на него для дальнейшего использования. Вы также можете экспортировать редакцию в один из поддерживаемых форматов, проверив свойство exportLinks .

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

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

В случае сбоя LRO его ответ включает канонический код ошибки Google Cloud .

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

Подробнее об этой модели ошибок и о том, как с ней работать, можно прочитать в API Design Guide .

Код	Перечисление	Описание	Рекомендуемое действие
1	CANCELLED	Операция была отменена, как правило, вызывающей стороной.	Повторите операцию.
2	UNKNOWN	Эта ошибка может быть возвращена, если значение Status , полученное из другого адресного пространства, принадлежит пространству ошибок, которое неизвестно в этом адресном пространстве. Если ошибка API не возвращает достаточно информации, ошибка может быть преобразована в эту ошибку.	Повторите попытку с экспоненциальной задержкой.
3	INVALID_ARGUMENT	Клиент указал недопустимый аргумент. Эта ошибка отличается от FAILED_PRECONDITION . INVALID_ARGUMENT указывает аргументы, которые являются проблемными независимо от состояния системы, например неправильное имя файла.	Не повторяйте попытку, не устранив проблему.
4	DEADLINE_EXCEEDED	Срок истек до завершения операции. Для операций, изменяющих состояние системы, эта ошибка может быть возвращена, даже если операция завершилась успешно. Например, успешный ответ от сервера мог быть отложен на время, достаточное для истечения крайнего срока.	Повторите попытку с экспоненциальной задержкой.
5	NOT_FOUND	Некоторый запрошенный объект, например ресурс FHIR, не найден.	Не повторяйте попытку, не устранив проблему.
6	ALREADY_EXISTS	Объект, который пытался создать клиент, например экземпляр DICOM, уже существует.	Не повторяйте попытку, не устранив проблему.
7	PERMISSION_DENIED	У вызывающего объекта нет разрешения на выполнение указанной операции. Этот код ошибки не означает, что запрос действителен, запрошенный объект существует или удовлетворяет другим предварительным условиям.	Не повторяйте попытку, не устранив проблему.
8	RESOURCE_EXHAUSTED	Некоторые ресурсы исчерпаны, например квота на проект.	Повторите попытку с экспоненциальной задержкой. Квота может стать доступной со временем.
9	FAILED_PRECONDITION	Операция была отклонена, поскольку система не находится в состоянии, необходимом для выполнения операции. Например, удаляемый каталог не пуст или операция rmdir применяется к некаталогу.	Не повторяйте попытку, не устранив проблему.
10	ABORTED	Операция была прервана, как правило, из-за проблемы параллелизма, например сбоя проверки секвенсора или прерывания транзакции.	Повторите попытку с экспоненциальной задержкой.
11	OUT_OF_RANGE	Была предпринята попытка выполнить операцию за пределами допустимого диапазона, например поиск или чтение за пределами конца файла. В отличие от INVALID_ARGUMENT , эта ошибка указывает на проблему, которую можно устранить, если изменится состояние системы.	Не повторяйте попытку, не устранив проблему.
12	UNIMPLEMENTED	Операция не реализована или не поддерживается/не включена в Drive API.	Не повторяйте попытку.
13	INTERNAL	Внутренние ошибки. Это указывает на то, что при обработке в базовой системе произошла непредвиденная ошибка.	Повторите попытку с экспоненциальной задержкой.
14	UNAVAILABLE	API Диска недоступен. Скорее всего, это временное состояние, которое можно исправить, повторив попытку с экспоненциальной задержкой. Обратите внимание, что не всегда безопасно повторять неидемпотентные операции.	Повторите попытку с экспоненциальной задержкой.
15	DATA_LOSS	Невосстановимая потеря или повреждение данных.	Обратитесь к своему системному администратору. Системный администратор может обратиться к представителю службы поддержки в случае потери или повреждения данных.
16	UNAUTHENTICATED	В запросе нет действительных учетных данных аутентификации для операции.	Не повторяйте попытку, не устранив проблему.

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

• Загрузка и экспорт файлов
• Управление версиями файлов