从 Drive Activity API v1 迁移

本指南介绍了 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 的请求格式类似。具体而言，您仍然可以请求云端硬盘文件或云端硬盘父级的活动记录，但请注意，您必须将这些请求参数的格式设置为资源名称，方法是将 items/ 添加为这些参数的前缀。

“分组”现在称为合并，并且 source 和 userId 请求参数已移除。

此外，我们还提供了新的过滤条件选项，可让您限制响应中返回的活动记录数据类型。

操作

在 v1 API 中，活动类型和与该活动关联的数据位于单独的字段中。例如，如果 primaryEventType 字段包含值 move，则应用会假定顶级 move 字段已填充添加和移除的父级。

在 v2 API 中，这些字段不再是不同的字段。ActionDetail 消息只能设置一个字段。它表示操作类型，并包含与该操作相关的详细信息。例如，表示移动的 ActionDetail 仅会设置 move 字段，该字段会列出添加和移除的父项。

v1 API primaryEventType 字段大致与 v2 primaryActionDetail 对应。

行为者

在 v1 API 中，如果操作者是已知用户，则返回的 activity 包含 User；对于特殊情况，还可以包含顶级字段（例如 fromUserDeletion）。

在 v2 API 中，提供了一组更丰富的 Actor 类型，并且当执行者是已知用户时，系统会填充 user.knownUser。如果您的应用需要有关用户的详细信息，可以通过将 KnownUser 字段 personName 传递给 people.get 方法，从 People API 中查询这些信息。

目标

在 v1 API 中，目标始终是云端硬盘项。在 v2 API 中，目标可以是云端硬盘中的其他类型的对象。例如，对云端硬盘所做的更改的目标类型为 Drive。系统仍会返回共享云端硬盘的根文件夹（在 root 字段中显示为 DriveItem），但它不是 activity 的直接目标。类似的概念也适用于 FileComment 资源，其 parent 字段引用包含目标评论会话的云端硬盘项。

合并的活动

在 v1 API 中，设置汇总（“分组”）策略后，响应样式会发生变化。具体而言，启用合并后，每个 activity 都包含组成 singleEvents 和一个 combinedEvent，用于汇总这些组成事件之间的共同 activity。停用合并后，combinedEvent 字段会包含每个活动的原始未合并事件。其中任何事件都可能代表多项操作，例如创建和分享。

在 v2 API 中，响应样式不会因汇总策略而改变，因为返回的 DriveActivity 始终包含一整套操作者、目标和操作。