Drive Activity API 数据模型

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

对象

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

  • Timestamp 和 TimeRange：这两个参数分别描述了活动发生的单个时间点，或活动在一段时间内发生的开始和结束时间。

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

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

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

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

示例回复

请查看以下内容，了解示例响应。

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

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

"activities":[{
  "primaryActionDetail":{ "edit":{} },
  "actors":[ { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID" } } } ],
  "targets":[ { "driveItem":{ "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 相同。

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

使用 ConsolidationStrategy 时，系统会将相关操作划分为一个组合 DriveActivity。在此示例中，系统将两项类似的操作进行了分组：两位不同用户执行的 Edit 操作类型。

"activities":[{
  "primaryActionDetail":{ "edit":{} },
  "actors":[
    { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_1" } } },
    { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_2" } } }
  ],
  "targets":[
    { "driveItem":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } }
  ],
  "timeRange":{
    "startTime":{ "seconds":"1541089823", "nanos":712000000 },
    "endTime":{ "seconds":"1541089830", "nanos":830000000 }
  },
  "actions":[
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_1" } } },
      "timestamp":{ "seconds":"1541089830", "nanos":830000000 }
    },
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_2" } } },
      "timestamp":{ "seconds":"1541089823", "nanos":712000000 }
    }
  ]
}]

此输出包括以下值：

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

请注意，此响应中的 Action 对象不包含 Target，因为它与整个 DriveActivity 相同。

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

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

在此示例中，ConsolidationStrategy 将两个相关的 Move 操作分组，因为文件同时从同一来源移到了同一目的地。

"activities":[{
  "primaryActionDetail":{
    "move":{
      "addedParents":[ { ... } ]
      "removedParents":[ { ... } ]
    }
  },
  "actors":[ { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID" } } } ],
  "targets":[
    { "driveItem":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } },
    { "driveItem":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
  ],
  "timestamp":{ "seconds":"1541090960", "nanos":985000000 },
  "actions":[
    {
      "detail":{ "move":{ "addedParents":[ { ... } ] "removedParents":[ { ... } ] } },
      "target":{ "driveItem":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } }
    },
    {
      "detail":{ "move":{ "addedParents":[ { ... } ] "removedParents":[ { ... } ] } },
      "target":{ "driveItem":{ "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：第二个云端硬盘内容的标题。

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