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

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

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

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

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

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

На следующей диаграмме показаны общие этапы работы метода 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, изначально возвращают перенаправление. Нажмите новую ссылку, чтобы загрузить файл.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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() . Другого способа получить его нет, поскольку Drive API не поддерживает метод List() . Если значение name потеряно, необходимо сгенерировать новый ответ, повторно вызвав запрос метода download() .

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

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

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

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

Чтобы загрузить содержимое ревизии файлов больших двоичных объектов, необходимо вызвать метод 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 ревизии, которую вы хотите загрузить.

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

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

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

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

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

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

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

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

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

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

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

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

На следующей диаграмме показаны общие этапы работы метода 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 файла, который вы хотите загрузить.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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() . Другого способа получить его нет, поскольку Drive API не поддерживает метод List() . Если значение name потеряно, необходимо сгенерировать новый ответ, повторно вызвав запрос метода download() .

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

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

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

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

Чтобы загрузить содержимое ревизии файлов больших двоичных объектов, необходимо вызвать метод 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 ревизии, которую вы хотите загрузить.

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

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

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

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

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

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

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