在 Google Drive Activity API 中发出请求

本指南介绍了如何使用 activity.query 方法在 Google Drive Activity API 中发出请求。

查询键

您可以通过以下 2 种方式请求 activity:按 Google 云端硬盘内容请求,或按文件夹层次结构下的所有内容。

  • itemName:此键的格式为“items/ITEM_ID”。通常是云端硬盘中的文件。如果您为此键指定文件夹,它会显示该文件夹的 activity,例如创建或重命名的时间。

  • ancestorName:此键的格式为“items/ITEM_ID”,响应中会包含此文件夹下子树中所有项的活动。

如果未设置任何键,则默认使用“items/root”的 ancestorName,并显示云端硬盘中所有项的 Activity。

分页

借助 pageSize 字段,您可以请求在每个响应中返回的 activity 的大致数量。返回的 activity 的实际计数会有所不同,因此您的应用应在响应中处理任意数量。

页面大小受限。如果应用需要许多 activity,请使用分页发出多个请求,而不是为 pageSize 设置较大的值。具体而言,如果可能比响应中所含的活动更多,则响应也会包含 nextPageToken。如需检索更多结果,请重复同一请求,但添加一个 pageToken 字段,其值为来自之前响应的 nextPageToken

整合

Action 对象通常分组并在单个 DriveActivity 资源中返回。某些 Action 分组会自发发生,例如将某项内容移动到某个共享文件夹中会触发权限更改。

您还可以在请求中指定 ConsolidationStrategy(有时称为汇总或批处理)。这样一来,就可以对相关的 Action 对象进行其他分组,例如多个操作者正在编辑一个项目,或一个 Actor 将多个文件移动到新的云端硬盘文件夹。

虽然单个 Action 有一个 Actor 和一个 Target,但在分组后,生成的 DriveActivity 可有多个执行者和多个目标。但是,即使在分组之后,在 DriveActivity 资源中的所有操作中也始终会有一项“主要”操作,要么是代表性操作,要么是最重要的操作,具体取决于请求的合并策略。

因此,无论是否启用整合,许多客户端都可能只查看 DriveActivity 资源的顶级内容(例如 primaryActionDetail 中的共同操作者和目标),而忽略响应中的详细操作。

过滤条件

您可以通过在 activity.query 请求中构建 filter 字符串来限制 DriveActivity 资源中可能返回的操作。有两个受支持的字段:timedetail.action_detail_case

按时间过滤

如需按时间范围限制操作,请指定字段名称 time,并在日期值中使用数字运算符,并使用可选的“AND”联接起来。请使用自 1970 年 1 月 1 日以来的毫秒数或 RFC 3339 格式,例如:

  • time > 1452409200000 AND time <= 1492812924310
  • time >= "2016-01-10T01:02:03-05:00"

按类型过滤

如需按操作类型进行限制,请应用字段名称 detail.action_detail_case 和“包含”运算符 (:)。您可以使用单个值或用括号括起来的允许操作类型列表,并用空格分隔。如需查找操作类型列表,请查看 ActionDetail 对象。

如需从响应中排除某个操作类型,请在过滤条件字符串的开头添加一个连字符 (-)。

下面是一些操作类型示例:

  • detail.action_detail_case:RENAME
  • detail.action_detail_case:(CREATE RESTORE)
  • -detail.action_detail_case:MOVE

组合

这些过滤条件可以合并到单个 filter 字符串中,例如:

  • detail.action_detail_case:(CREATE EDIT RESTORE) time > 1452409200000

示例请求

请求云端硬盘内容的 10 项最近活动:

{
  "itemName": "items/ITEM_ID",
  "pageSize": 10
}

请求为祖先文件夹下的所有云端硬盘内容汇总活动:

{
  "ancestorName": "items/ITEM_ID",
  "consolidationStrategy": {
    "legacy": {}
  }
}

请求对云端硬盘内容执行所有 MOVERENAME 操作:

{
  "itemName": "items/ITEM_ID",
  "filter": "detail.action_detail_case:(MOVE RENAME)"
}

请求自 2018 年 1 月 1 日(美国东部标准时间)以来的所有活动:

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-01-01T00:00:00-05:00\""
}

请求 2017 年 6 月 (UTC) 期间的所有活动(EDIT 操作除外):

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-06-01T00:00:00Z\" time < \"2018-07-01T00:00:00Z\" -detail.action_detail_case:EDIT"
}