本指南介绍了 Google Drive Activity API 中响应的主要组成部分,通过展示示例以及如何解读这些示例。
对象
DriveActivity
- 这是查询向 Drive Activity API 返回的主要资源。它描述了一个或多个操作者执行影响一个或多个目标的一项或多项操作。Timestamp
和TimeRange
- 分别用于描述 activity 发生的单个时间点,或一段时间内活动发生的开始和结束时间。Actor
-Actor
通常是最终用户。不过,有时系统事件可能会在管理员以用户或自己的身份运行,或者由无法识别的人员执行操作时触发Action
。Actor
消息封装了所有这些情况。Target
-Target
是 activity 的对象,例如文件、文件夹、共享云端硬盘或文件评论。请注意,许多操作类型都支持多种目标。例如,虽然Edit
通常适用于云端硬盘文件,但Rename
和Create
等其他操作也可以应用于云端硬盘文件夹和共享云端硬盘。不是云端硬盘内容的目标仍然可以引用云端硬盘内容,例如云端硬盘的根文件夹或包含文件注释的父文档。Action
- 每个DriveActivity
资源都有一项或多项相关操作。与事件一样,Action
也是独立的,它不仅包含操作的详细类型和信息,还包含Actor
、Target
以及Timestamp
或TimeRange
。为了避免冗余,当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 个相似的操作分为一组:1 个来自 2 个不同用户的 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
相同。