This guide explains the main components of a response in the Google Drive Activity API, showing examples and how to interpret them.
Objects
DriveActivity
—This is the primary resource returned by queries to the Drive Activity API. It describes one or more actors performing one or more actions affecting one or more targets.Timestamp
andTimeRange
—These describe, respectively, either a single point in time when activity occurred, or the start and end of when the activity occurred over a span of time.Actor
—Typically, anActor
is an end user. However, sometimes, a system event can trigger anAction
when an admin is acting as a user or as themselves, or when performed by an unidentifiable person. TheActor
message encapsulates each of these cases.Target
—ATarget
is the object of an activity, like a file, a folder, a shared drive, or a file comment. Note that many action types support more than one kind of target. For example, thoughEdit
generally applies to Drive files, other actions likeRename
andCreate
can also apply to Drive folders and shared drives. Targets that aren't Drive items can still refer to one, such as the root folder of a drive or the parent document containing a file comment.Action
—EachDriveActivity
resource has one or more related actions. AnAction
is self-contained, like an event, in that it comprises not only the detailed type and information about the action, but also anActor
, aTarget
, and either aTimestamp
orTimeRange
. To avoid redundancy, anAction
doesn't populate its ownTarget
,Actor
, or time fields when those are the same as the overallDriveActivity
.ActionDetail
—This is the specific type and detailed information about anAction
. For example, aMove
action detail has a source and destination location, and aPermissionChange
specifies who can now access a document and with what privileges.
Example responses
A user edited a file in Drive:
A simple DriveActivity
resource might include only one action, such as a user
editing one file.
"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":{} } } ]
}]
This output includes the following values:
- ACCOUNT_ID: the ID of the user. It can be used with the People API to get more information.
- ITEM_ID: the ID of the Drive item.
- TITLE: the title of the Drive item.
Note that the Action
in this response doesn't include the Actor
, Target
,
or TimeStamp
because they're the same as the overall DriveActivity
.
Two users edited the same file at similar times:
When consolidation is turned on, related actions are grouped into one
DriveActivity
. In this example, 2 similar actions are grouped: one Edit
action type from 2 different users.
"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 }
}
]
}]
This output includes the following values:
- ACCOUNT_ID_1: the ID of the first user. It can be used with the People API to get more information.
- ACCOUNT_ID_2: the ID of the second user.
- ITEM_ID: the ID of the Drive item.
- TITLE: the title of the Drive item.
Note that the actions in this response don't include the Target
because it's
the same as the overall DriveActivity
.
The example also illustrates how apps might use only the summary information in
DriveActivity
, without looking at the individual actions. The response
indicates that 2 users edited a given file over a span of time.
A user moved 2 files into a new directory:
In this example, the consolidation strategy grouped 2 related Move
actions
because the files were moved from the same source to the same destination at the
same time.
"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":{} } }
}
]
}]
This output includes the following values:
- ACCOUNT_ID: the ID of the user. It can be used with the People API to get more information.
- ITEM_ID_1: the ID of the first Drive item.
- ITEM_ID_2: the ID of the second Drive item.
- TITLE_1: the title of the first Drive item.
- TITLE_2: the title of the second Drive item.
Note that the actions in this response don't include the Actor
or TimeStamp
because they're the same as the overall DriveActivity
.