本指南介绍了 Google Drive Activity API v1 与 v2 之间的区别,以及如何更改 v1 应用以支持 v2 API。
授权
v1 API 使用了此范围:
https://www.googleapis.com/auth/activity
v2 API 需要以下范围之一:
https://www.googleapis.com/auth/drive.activity
https://www.googleapis.com/auth/drive.activity.readonly
资源名称
在 v1 API 中,Google 云端硬盘内容和用户等对象的标识符是不透明字符串。在 v2 API 中,这些对象通常使用资源名称来引用。如需了解详情,请参阅 Cloud API 设计指南。
这些标识符通常可以进行转换。例如,v2 API 中的云端硬盘内容使用资源名称 items/ITEM_ID_V1
来引用。
请求数
v2 的请求格式与 v1 类似。具体来说,您仍然可以请求云端硬盘文件或云端硬盘祖先实体对应的 activity,但请注意,您必须将这些请求参数的格式设置为资源名称,方法是在参数前面加上 items/
前缀。
“分组”现在称为 Consolidation,并且 source
和 userId
请求参数已移除。
还有一些新的 Filter 选项,可用于限制响应中返回的 activity 数据类型。
Action
在 v1 API 中,activity 类型以及与 activity 关联的数据位于不同的字段中。例如,如果 primaryEventType
字段包含值 move
,则应用会假设顶级 move
字段已填充添加和移除的父级。
在 v2 API 中,这些字段不再不同。ActionDetail
消息只有一个字段集。它表示操作类型,并包含与该操作相关联的详细信息。例如,表示一项举动的 ActionDetail
仅设置 move
字段,而该字段会列出添加和移除的父级。
v1 API 的 primaryEventType
字段与 v2 primaryActionDetail
大致对应。
Actors
在 v1 API 中,如果执行者是已知用户,返回的 activity 会包含 User
;对于特殊情况,返回的 activity 可以选择性地包含顶级字段,例如 fromUserDeletion
。
在 v2 API 中,可以使用一组更丰富的 Actor
类型,当操作者是已知用户时,系统会填充 user.knownUser
。如果您的应用需要有关用户的详细信息,可以通过 People API 进行查询,只需将 KnownUser
字段 personName
传递给 people.get
方法即可。
目标
在 v1 API 中,目标始终是云端硬盘内容。在 v2 API 中,目标是云端硬盘中其他类型的对象。例如,对云端硬盘的更改的目标类型为 Drive
。系统仍会返回共享云端硬盘的根文件夹(作为 root
字段中的 DriveItem
),但它不是 activity 的直接目标。类似的概念适用于 FileComment
资源,其 parent
字段引用包含目标评论线程的云端硬盘内容。
合并活动
在 v1 API 中,响应样式在设置整合(“分组”)策略后发生了变化。具体而言,启用整合后,每个 activity 都包含组成部分 singleEvents
和 combinedEvent
(总结了这些组成事件中的共同活动)。关闭整合功能后,combinedEvent
字段会包含每个活动的原始未合并事件。这些事件中的任何一个都可以表示多项操作,例如创建和分享。
在 v2 API 中,响应的样式不会根据整合策略而发生变化,因为返回的 DriveActivity
始终包含完整的操作者、目标和操作。