Руководство по сравнению Drive API v2 и v3
Оптимизируйте свои подборки
Сохраняйте и классифицируйте контент в соответствии со своими настройками.
Последняя версия API Google Drive — v3. Производительность в v3 выше, поскольку поиск возвращает только подмножество полей. Используйте текущую версию, если вам не нужна коллекция v2 . Если вы используете v2, рассмотрите возможность перехода на v3. Чтобы перейти на API Drive, см. статью «Миграция на API Drive v3» . Полный список различий между версиями см. в справочнике по сравнению API Drive v2 и v3 .
Если вы хотите продолжить использование v2, ознакомьтесь с поправкой к Руководству по Drive API v2, чтобы узнать, как следует изменить некоторые инструкции в руководствах v3 для разработчиков v2.
Чтобы узнать больше об улучшениях Drive API v3, вы можете посмотреть следующее видео от инженеров Google, в котором они обсуждают новый дизайн API.
Улучшения V3
Для оптимизации производительности и снижения сложности поведения API в версии 3 реализованы следующие улучшения по сравнению с предыдущей версией API:
- Поиск файлов и общих дисков по умолчанию не возвращает все ресурсы, возвращается только подмножество часто используемых полей. Подробнее о
fields см. в методах files.list и drives.list . - Почти все методы, возвращающие ответ, теперь требуют параметр
fields . Список всех методов, требующих fields , см. в справочнике по API Drive . - Ресурсы с дублирующими возможностями были удалены. Вот несколько примеров:
- Метод
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 . - Методы обновления теперь отклоняют запросы, в которых указаны поля, недоступные для записи.
- Поля
exportFormats и importFormats в ресурсе about версии 2 представляют собой списки допустимых форматов импорта и экспорта. В версии 3 это сопоставления типов MIME возможных целевых форматов для всех поддерживаемых форматов импорта и экспорта. - Псевдонимы
appdata и appfolder v2 теперь в v3 appDataFolder . - Ресурс
properties удалён из версии 3. Ресурс files содержит поле properties , содержащее пары «ключ-значение». Поле properties содержит общедоступные свойства, а поле appProperties — закрытые свойства, поэтому поле видимости не требуется. - Поле
modifiedTime в ресурсе files обновляет время последнего изменения файла. В версии 2 поле modifiedDate можно было изменять при обновлении только при установке поля setModifiedDate . - Поле
viewedByMeTime в ресурсе files не обновляется автоматически. - Для импорта форматов Google Docs необходимо указать соответствующий целевой
mimeType в теле ресурса. В версии 2 необходимо задать ?convert=true . - Операции импорта возвращают ошибку 400, если формат не поддерживается.
- Читатели и комментаторы не могут просматривать разрешения.
- Псевдоним
me для разрешений удален. - Некоторые функции были доступны как часть ресурса запроса, но теперь доступны как параметр запроса. Например:
- В версии 2 можно использовать
children.delete для удаления дочернего файла из родительской папки. - В версии 3 вы используете
files.update для дочернего элемента с ?removeParents=parent_id в URL-адресе.
Другие различия
Названия полей и параметров в версии 3 отличаются. Вот несколько примеров:
- Свойство
name заменяет title в ресурсе files . - Суффиксом для всех полей даты и времени вместо
Date является Time . - Операции со списками не используют поле
items для хранения результирующего набора. Тип ресурса предоставляет поле для результатов (например, files или changes ).
Если не указано иное, контент на этой странице предоставляется по лицензии Creative Commons "С указанием авторства 4.0", а примеры кода – по лицензии Apache 2.0. Подробнее об этом написано в правилах сайта. Java – это зарегистрированный товарный знак корпорации Oracle и ее аффилированных лиц.
Последнее обновление: 2025-08-29 UTC.
[null,null,["Последнее обновление: 2025-08-29 UTC."],[],[],null,["# Drive API v2 and v3 comparison guide\n\nThe latest Google Drive API version is v3. The performance in v3 is better because\nsearches only return a subset of fields. Use the current version unless you need\nthe [v2](/workspace/drive/api/v2/reference) collection. If you're using v2, consider\nmigrating to v3. To migrate, see [Migrate to Drive API v3](/workspace/drive/api/guides/migrate-to-v3). For a complete list of version differences, see\nthe [Drive API v2 and v3 comparison\nreference](/workspace/drive/api/guides/v2-to-v3-reference).\n\nIf you want to continue to use v2, see the [Guide to Drive API v2](/workspace/drive/api/guides/v2-guide) amendment to learn how some instructions in the v3\nguides must be amended for v2 developers.\n\nTo learn more about Drive API v3 improvements, you can watch the\nfollowing video by Google engineers discussing the new API design. \n\nV3 improvements\n---------------\n\nTo optimize performance and reduce API behavior complexity, v3 provides these\nimprovements over the previous API version:\n\n- Searches for files and shared drives don't return full resources by default, only a subset of commonly used fields gets returned. For more details on `fields`, see the [`files.list`](/workspace/drive/api/v3/reference/files/list) method and the [`drives.list`](/workspace/drive/api/v3/reference/drives/list) method.\n- Almost all methods that return a response now require the `fields` parameter. For a list of all methods requiring `fields`, see the [Drive API reference](/workspace/drive/api/v3/reference).\n- Resources that have duplicate capabilities were removed. Some examples:\n - The `files.list` method accomplishes the same functionality as the `Children` and `Parents` collections, so they're removed from v3.\n - The `Realtime.*` methods have been removed.\n- App Data isn't returned by default in searches. In v2, you can set the `drive.appdata` scope, and it returns application data from the `files.list` method and the [`changes.list`](/workspace/drive/api/v2/reference/changes/list) method, but it slows performance. In v3, you set the `drive.appdata` scope, and also set the query parameter `spaces=appDataFolder` to request application data.\n- All update operations use PATCH instead of PUT.\n- To export Google Documents, use the [`files.export`](/workspace/drive/api/v2/reference/files/export) method.\n- The `changes.list` method behavior is different. Instead of change IDs, use opaque page tokens. To poll the change collection, first call the [`changes.getStartPageToken`](/workspace/drive/api/v2/reference/changes/getStartPageToken) method for the initial value. For subsequent queries, the `changes.list` method returns the `newStartPageToken` value.\n- Update methods now reject requests that specify non-writable fields.\n- The v2 `exportFormats` and `importFormats` fields in the [`about`](/workspace/drive/api/reference/rest/v3/about) resource are lists of allowable import or export formats. In v3, they're MIME type maps of possible targets to all supported imports or exports.\n- The v2 `appdata` and `appfolder` aliases are now `appDataFolder` in v3.\n- The `properties` resource is removed from v3. The [`files`](/workspace/drive/api/v3/reference/files) resource has the `properties` field that contains true key-value pairs. The `properties` field contains public properties, and the `appProperties` field contains private properties, so the visibility field isn't needed.\n- The `modifiedTime` field in the `files` resource updates the last time anyone modified the file. In v2, the `modifiedDate` field was only mutable on update if you set the `setModifiedDate` field.\n- The `viewedByMeTime` field in the `files` resource doesn't automatically update.\n- To import Google Docs formats, you set the appropriate target `mimeType` in the resource body. In v2, you set `?convert=true`.\n- Import operations return a 400 error if the format isn't supported.\n- Readers and commenters can't view permissions.\n- The `me` alias for permissions is removed.\n- Some functionality was available as part of the request resource but is instead available as a request parameter. For example:\n - In v2, you can use `children.delete` to remove a child file from a parent folder.\n - In v3, you use`files.update` on the child with `?removeParents=parent_id` in the URL.\n\nOther differences\n-----------------\n\nFields and parameter names are different in v3. Some examples include:\n\n- The `name` property replaces `title` in the `files` resource.\n- `Time` is the suffix for all date and time fields instead of `Date`.\n- List operations don't use the `items` field to contain the result set. The resource type provides a field for the results (such as `files` or `changes`)."]]
