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