Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

Более подробную информацию см. в разделе Длительные операции .

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

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

Высокоуровневые шаги для метода file.download. — **Рисунок 1.** Основные этапы метода file.download.

Вызов files.download : когда приложение вызывает метод download , оно запускает запрос на загрузку файла через Drive API. Подробнее см. в разделе Загрузка файлов .
Запрос разрешений : запрос отправляет учётные данные аутентификации в Drive API. Если ваше приложение требует вызова Drive API с использованием аутентификации пользователя, которая ещё не была предоставлена, оно предлагает пользователю войти в систему. Ваше приложение также запрашивает доступ с областями, которые вы указываете при настройке аутентификации.
Начать загрузку : для начала загрузки файла выполняется запрос к API Диска. Запрос может быть направлен к Google Vids или другому контенту Google Workspace.
Запуск LRO : начинается длительная операция, которая управляет процессом загрузки.
Возврат отложенной операции : API Drive возвращает отложенную операцию, содержащую информацию о пользователе, сделавшем запрос, и несколько полей метаданных файла.
Начальное состояние ожидания : ваше приложение получает ожидающую операцию вместе с начальным состоянием ожидания done=null . Это означает, что файл ещё не готов к загрузке и операция находится в состоянии ожидания.
Вызов метода operations.get и проверка результата : ваше приложение вызывает метод get с рекомендуемыми интервалами, чтобы опрашивать результат операции и получать актуальное состояние длительной операции. Если возвращается состояние ожидания done=false , ваше приложение должно продолжать опрос, пока операция не вернёт состояние завершения ( done=true ). Для больших файлов будьте готовы к нескольким опросам. Подробнее см. в разделе Получение сведений о длительной операции .
Проверка состояния ожидания : если из LRO возвращается состояние ожидания done=true , это означает, что файл готов к загрузке и что операция завершена.
Возврат завершенной операции с URI загрузки : после завершения LRO API 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 — единственный способ загрузить файлы Vids в формате MP4 и, как правило, лучше всего подходит для загрузки большинства видеофайлов.

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

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

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

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

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

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

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

Тип документа	Формат	MIME-тип	Расширение файла
Скрипт Google Apps	JSON	application/vnd.google-apps.script+json	.json
Google Документы	Microsoft Word	application/vnd.openxmlformats-officedocument.wordprocessingml.document	.docx
Google Рисунки	PNG	изображение/png	.png
Google Формы	почтовый индекс	приложение/zip	.zip
Google Таблицы	Microsoft Excel	application/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 тело ответа содержит ресурс, представляющий длительную операцию. Метод обычно возвращает ссылку для загрузки содержимого файла.

{
  "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 указывает, разрешена ли частичная загрузка . Значение true при загрузке содержимого BLOB-файла.

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

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

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

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

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

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

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

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

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

Вызов метода

operations.get(name='NAME');

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

завиток

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 файла.

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

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

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

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

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

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

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

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

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

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

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

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

Код	Перечисление	Описание	Рекомендуемые действия
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`	Операция не реализована или не поддерживается/не включена в API Диска.	Не повторяйте попытку.
13	`INTERNAL`	Внутренние ошибки. Это означает, что при обработке в базовой системе произошла непредвиденная ошибка.	Повторите попытку с экспоненциальной задержкой.
14	`UNAVAILABLE`	API Диска недоступен. Скорее всего, это временная проблема, которую можно исправить, повторив попытку с экспоненциальной задержкой. Обратите внимание, что повторные попытки неидемпотентных операций не всегда безопасны.	Повторите попытку с экспоненциальной задержкой.
15	`DATA_LOSS`	Невосстановимая потеря или повреждение данных.	Обратитесь к своему системному администратору. В случае потери или повреждения данных системный администратор может обратиться в службу поддержки.
16	`UNAUTHENTICATED`	Запрос не имеет действительных учетных данных аутентификации для операции.	Не повторяйте попытку, пока проблема не будет устранена.

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