Руководство по сравнению Drive API v2 и v3

Последняя версия API Google Диска — v3. Производительность в версии 3 выше, поскольку поиск возвращает только подмножество полей. Используйте текущую версию, если вам не нужна коллекция v2 . Если вы используете версию 2, рассмотрите возможность перехода на версию 3. Инструкции по миграции см. в разделе «Миграция на Drive API v3» . Полный список различий версий см. в справочнике по сравнению Drive API v2 и v3 .

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

Чтобы узнать больше об улучшениях Drive API v3, вы можете посмотреть следующее видео, в котором инженеры Google обсуждают новый дизайн API.

Улучшения версии 3

Для оптимизации производительности и уменьшения сложности поведения API в версии 3 предусмотрены следующие улучшения по сравнению с предыдущей версией API:

  • Поиск файлов и общих дисков по умолчанию не возвращает все ресурсы, возвращается только подмножество часто используемых полей. Дополнительные сведения о fields см. в методах files.list и drives.list .
  • Почти все методы, возвращающие ответ, теперь требуют параметра fields . Список всех методов, требующих fields , см. в справочнике по Drive API .
  • Ресурсы с повторяющимися возможностями были удалены. Некоторые примеры:
    • Метод files.list выполняет ту же функциональность, что и коллекции Children и Parents , поэтому они удалены из версии 3.
    • Методы Realtime.* были удалены.
  • Данные приложения не возвращаются по умолчанию при поиске. В версии 2 вы можете установить область drive.appdata , и она возвращает данные приложения из метода files.list и метода changes.list , но это снижает производительность. В версии 3 вы задаете область действия drive.appdata , а также задаете параметр запроса spaces=appDataFolder для запроса данных приложения.
  • Все операции обновления используют PATCH вместо PUT.
  • Чтобы экспортировать документы Google, используйте метод files.export .
  • Поведение метода changes.list отличается. Вместо идентификаторов изменений используйте непрозрачные токены страниц. Чтобы опросить коллекцию изменений, сначала вызовите метод changes.getStartPageToken для получения начального значения. Для последующих запросов метод changes.list возвращает значение newStartPageToken .
  • Методы обновления теперь отклоняют запросы, в которых указаны поля, недоступные для записи.
  • Поля v2 exportFormats и importFormats в ресурсе about представляют собой списки допустимых форматов импорта или экспорта. В версии 3 это карты возможных целей MIME-типа для всех поддерживаемых импортов и экспортов.
  • Псевдонимы appdata и appfolder версии 2 теперь называются appDataFolder в версии 3.
  • Ресурс properties удален из версии 3. Ресурс files имеет поле properties , содержащее истинные пары «ключ-значение». Поле properties содержит общедоступные свойства, а поле appProperties содержит частные свойства, поэтому поле видимости не требуется.
  • Поле modifiedTime в ресурсе files обновляет информацию о том, когда кто-либо в последний раз изменял файл. В версии 2 поле modifiedDate было изменено только при обновлении, если вы установили поле setModifiedDate .
  • Поле viewedByMeTime в ресурсе files не обновляется автоматически.
  • Чтобы импортировать форматы Документов Google, вы устанавливаете соответствующий целевой mimeType в теле ресурса. В версии 2 вы устанавливаете ?convert=true .
  • Операции импорта возвращают ошибку 400, если формат не поддерживается.
  • Читатели и комментаторы не могут просматривать разрешения.
  • Псевдоним me для разрешений удален.
  • Некоторые функции были доступны как часть ресурса запроса, но вместо этого доступны как параметр запроса. Например:
    • В версии 2 вы можете использовать children.delete для удаления дочернего файла из родительской папки.
    • В версии 3 вы используете files.update для дочернего элемента с ?removeParents=parent_id в URL-адресе.

Другие различия

Имена полей и параметров в версии 3 другие. Вот некоторые примеры:

  • Свойство name заменяет title в ресурсе files .
  • Time — это суффикс для всех полей даты и времени вместо Date .
  • Операции со списком не используют поле items для хранения набора результатов. Тип ресурса предоставляет поле для результатов (например, files или changes ).