Drive API v2 与 v3 比较指南

Google Drive API 的最新版本为 v3。v3 中的性能更好，因为搜索只会返回部分字段。除非您需要 v2 集合，否则请使用当前版本。如果您使用的是 v2，请考虑迁移到 v3。如需进行迁移，请参阅迁移到 Drive API v3。如需查看版本差异的完整列表，请参阅 Drive API v2 和 v3 比较参考文档。

如果您想继续使用 v2，请参阅 Drive API v2 指南修订版，了解如何针对 v2 开发者修改 v3 指南中的部分说明。

如需详细了解 Drive API v3 的改进，您可以观看以下视频，其中 Google 工程师讨论了新 API 设计。

V3 改进

为了优化性能并降低 API 行为复杂性，v3 在之前的 API 版本的基础上做出了以下改进：

  • 默认情况下，搜索文件和共享云端硬盘不会返回完整资源，只会返回部分常用字段。如需详细了解 fields，请参阅 files.list 方法和 drives.list 方法。
  • 现在，几乎所有返回响应的方法都需要 fields 参数。如需查看需要 fields 的所有方法的列表，请参阅 Drive API 参考文档。
  • 移除了具有重复功能的资源。一些示例：
    • files.list 方法可实现与 Children 和 Parents 集合相同的功能，因此我们从 v3 中移除了它们。
    • 移除了 Realtime.* 方法。
  • 默认情况下，搜索中不会返回应用数据。在 v2 中，您可以设置 drive.appdata 作用域，它会从 files.list 方法和 changes.list 方法返回应用数据，但会降低性能。在 v3 中，您需要设置 drive.appdata 范围，还需要设置查询参数 spaces=appDataFolder 以请求应用数据。
  • 所有更新操作都使用 PATCH 而非 PUT。
  • 如需导出 Google 文档，请使用 files.export 方法。
  • changes.list 方法的行为有所不同。请改用不透明的页面令牌，而不是更改 ID。如需轮询更改集合，请先调用初始值的 changes.getStartPageToken 方法。对于后续查询，changes.list 方法会返回 newStartPageToken 值。
  • 更新方法现在会拒绝指定不可写入字段的请求。
  • about 资源中的 v2 exportFormats 和 importFormats 字段是允许的导入或导出格式的列表。在 v3 中，它们是将可能的目标与所有受支持的导入或导出内容的 MIME 类型进行映射的映射。
  • v2 中的 appdata 和 appfolder 别名现在在 v3 中为 appDataFolder。
  • properties 资源已从 v3 中移除。files 资源具有包含真实键值对的 properties 字段。properties 字段包含公共媒体资源，appProperties 字段包含私有媒体资源，因此不需要公开范围字段。
  • files 资源中的 modifiedTime 字段会在任何人上次修改文件时更新。在 v2 中，只有在您设置了 setModifiedDate 字段的情况下，modifiedDate 字段在更新时才可变。
  • files 资源中的 viewedByMeTime 字段不会自动更新。
  • 如需导入 Google 文档格式，您可以在资源正文中设置适当的目标 mimeType。在 v2 中，您需要设置 ?convert=true。
  • 如果不支持格式，导入操作会返回 400 错误。
  • 读者和评论者无法查看权限。
  • 移除了权限的 me 别名。
  • 某些功能之前是作为请求资源的一部分提供的，现在则作为请求参数提供。例如：
    • 在 v2 中，您可以使用 children.delete 从父文件夹中移除子文件。
    • 在 v3 中，您可以在网址中使用 ?removeParents=parent_id 对子项使用 files.update。

其他差异

v3 中的字段和参数名称不同。部分示例如下：

  • name 属性取代了 files 资源中的 title。
  • Time 是所有日期和时间字段的后缀，而非 Date。
  • 列表操作不会使用 items 字段来包含结果集。资源类型为结果提供了一个字段（例如 files 或 changes）。