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 方法实现的功能与 ChildrenParents 集合相同,因此已从 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 exportFormatsimportFormats 字段是允许的导入或导出格式列表。在 v3 中,它们是可能目标到所有受支持的导入或导出内容的 MIME 类型映射。
  • v2 appdataappfolder 别名在 v3 中现为 appDataFolder
  • v3 中移除了 properties 资源。files 资源具有包含真实键值对的 properties 字段。properties 字段包含公开属性,appProperties 字段包含私有属性,因此不需要可见性字段。
  • 任何人上次修改文件时,files 资源中的 modifiedTime 字段会更新。在 v2 中,只有在您设置了 setModifiedDate 字段的情况下,modifiedDate 字段才会在更新时可变。
  • files 资源中的 viewedByMeTime 字段不会自动更新。
  • 如需导入 Google 文档格式,请在资源正文中设置适当的目标 mimeType。在 v2 中,您设置了 ?convert=true
  • 如果格式不受支持,导入操作会返回 400 错误。
  • 查看者和评论者无法查看权限。
  • 移除了权限的 me 别名。
  • 某些功能以前作为请求资源的一部分提供,但现在以请求参数的形式提供。例如:
    • 在 v2 中,您可以使用 children.delete 从父文件夹中移除子文件。
    • 在 v3 中,您对子级使用 files.update,并在网址中使用 ?removeParents=parent_id

其他差异

字段和参数名称在 v3 中有所不同。部分示例如下:

  • name 属性替换了 files 资源中的 title
  • Time 是所有日期和时间字段的后缀,而不是 Date
  • 列出操作不使用 items 字段来包含结果集。资源类型提供结果字段(例如 fileschanges)。