Drive Activity API 数据模型

本指南介绍了 Google Drive Activity API 中响应的主要组成部分，并提供了示例以及如何解读这些示例。

对象

  • DriveActivity - 这是对 Drive Activity API 的查询返回的主要资源。它描述一个或多个执行一项或多项操作的操作者，这些操作会影响一个或多个目标。

  • Timestamp 和 TimeRange - 分别用于描述活动发生的单个时间点，或活动在一段时间内的开始和结束时间。

  • Actor - 通常，Actor 是最终用户。不过，有时，当管理员以用户身份或以自己的身份执行操作，或者由无法识别的人员执行操作时，系统事件可能会触发 Action。Actor 消息封装了每种情况。

  • Target - Target 是活动的对象，例如文件、文件夹、共享云端硬盘或文件评论。请注意，许多操作类型支持多种类型的目标。例如，虽然 Edit 通常适用于云端硬盘文件，但 Rename 和 Create 等其他操作也可以应用于云端硬盘文件夹和共享云端硬盘。非云端硬盘项的目标仍可引用云端硬盘项，例如云端硬盘的根文件夹或包含文件评论的父级文档。

  • Action - 每个 DriveActivity 资源都有一个或多个相关操作。Action 是自包含的，就像事件一样，它不仅包含有关操作的详细类型和信息，还包含 Actor、Target 以及 Timestamp 或 TimeRange。为避免冗余，当 Action 的 Target、Actor 或时间字段与整体 DriveActivity 相同时，Action 不会填充自己的 Target、Actor 或时间字段。

  • ActionDetail - 这是 Action 的具体类型和详细信息。例如，Move 操作详情具有来源和目的地位置，PermissionChange 则用于指定哪些人现在可以访问文档以及他们拥有哪些权限。

示例回复

用户在云端硬盘中修改了文件：

一个简单的 DriveActivity 资源可能只包含一个操作，例如用户修改一个文件。

"activities":[{
  "primary_action_detail":{ "edit":{} },
  "actors":[ { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID" } } } ],
  "targets":[ { "drive_item":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } } ],
  "timestamp":{ "seconds":"1536794657", "nanos":791000000 },
  "actions":[ { "detail":{ "edit":{} } } ]
}]

此输出包括以下值：

  • ACCOUNT_ID：用户的 ID。它可与 People API 搭配使用，以获取更多信息。
  • ITEM_ID：云端硬盘内容的 ID。
  • TITLE：云端硬盘内容的标题。

请注意，此响应中的 Action 不包含 Actor、Target 或 TimeStamp，因为它们与整个 DriveActivity 相同。

两位用户在相近的时间编辑了同一文件：

启用合并后，系统会将相关操作归为一项 DriveActivity。在此示例中，系统将 2 项类似操作进行了分组：来自 2 位不同用户的 1 项 Edit 操作类型。

"activities":[{
  "primary_action_detail":{ "edit":{} },
  "actors":[
    { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_1" } } },
    { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_2" } } }
  ],
  "targets":[
    { "drive_item":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } }
  ],
  "time_range":{
    "start_time":{ "seconds":"1541089823", "nanos":712000000 },
    "end_time":{ "seconds":"1541089830", "nanos":830000000 }
  },
  "actions":[
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_1" } } },
      "timestamp":{ "seconds":"1541089830", "nanos":830000000 }
    },
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_2" } } },
      "timestamp":{ "seconds":"1541089823", "nanos":712000000 }
    }
  ]
}]

此输出包括以下值：

  • ACCOUNT_ID_1：第一个用户的 ID。它可与 People API 搭配使用，以获取更多信息。
  • ACCOUNT_ID_2：第二个用户的 ID。
  • ITEM_ID：云端硬盘内容的 ID。
  • TITLE：云端硬盘内容的标题。

请注意，此响应中的操作不包括 Target，因为它与整个 DriveActivity 相同。

该示例还说明了应用如何仅使用 DriveActivity 中的摘要信息，而无需查看具体操作。响应表明，2 位用户在一段时期内编辑了指定文件。

用户将 2 个文件移到了新目录：

在此示例中，合并策略将 2 项相关的 Move 操作归为一组，因为这些文件同时从同一来源移到了同一目的地。

"activities":[{
  "primary_action_detail":{
    "move":{
      "added_parents":[ { ... } ]
      "removed_parents":[ { ... } ]
    }
  },
  "actors":[ { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID" } } } ],
  "targets":[
    { "drive_item":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } },
    { "drive_item":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
  ],
  "timestamp":{ "seconds":"1541090960", "nanos":985000000 },
  "actions":[
    {
      "detail":{ "move":{ "added_parents":[ { ... } ] "removed_parents":[ { ... } ] } },
      "target":{ "drive_item":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } }
    },
    {
      "detail":{ "move":{ "added_parents":[ { ... } ] "removed_parents":[ { ... } ] } },
      "target":{ "drive_item":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
    }
  ]
}]

此输出包括以下值：

  • ACCOUNT_ID：用户的 ID。它可与 People API 搭配使用，以获取更多信息。
  • ITEM_ID_1：第一个云端硬盘项的 ID。
  • ITEM_ID_2：第二个云端硬盘内容的 ID。
  • TITLE_1：第一个云端硬盘项的标题。
  • TITLE_2：第二个云端硬盘内容的标题。

请注意，此响应中的操作不包括 Actor 或 TimeStamp，因为它们与整个 DriveActivity 相同。