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

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

The Google Drive API returns a LRO every time you call the download method on the files resource to download the content of a file either through the Drive API or its client libraries .

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

For more information, see Long-running operations .

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

The following diagram shows the high-level steps of how the file.download method works.

1. Call files.download : When your app calls the download method, it launches the Drive API download request for the file. For more information, see Download files .

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

3. Start download : A Drive API request is made to start the file download. The request could be made to Google Vids or some other Google Workspace content.

4. Start LRO : A long-running operation begins and it manages the download process.

5. Return pending operation : The Drive API returns a pending operation containing information about the user making the request and several file metadata fields.

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

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

8. Check pending state : If the pending state of done=true is returned from the LRO, this denotes the file is ready for download and that the operation status is complete.

9. Return completed operation with download URI : Once the LRO is done, the Drive API returns the download URI and the file is now available to the user.

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

To download content under a long-running operation, use the download method on the files resource. The method takes the parameters of file_id , mime_type , and revision_id :

• Required. The file_id path parameter is the ID of the file to download.

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

  If the MIME type isn't set, the Google Workspace document is downloaded with a default MIME type. For more information, see Default MIME types .

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

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

Download links generated for Google Docs or Sheets initially return a redirect. Click the new link to download the file.

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

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

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

Replace FILE_ID with the fileId of the file that you want to download.

Типы 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 : A resource key helps protect your file from unintended access. For more information, see Access link-shared Drive files using resource keys .

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

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

Note that the partialDownloadAllowed field denotes if a partial download is permitted and is true when downloading blob file content.

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

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

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

The get method gets the latest state of a long-running operation asynchronously. Clients can use this method to poll the operation result at intervals as recommended by the API service.

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

Для опроса доступного 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 . Параметр alt=media сообщает серверу, что запрашивается загрузка содержимого в альтернативном формате ответа.

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

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

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

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 .

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

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