This guide explains the main components of a response in the Drive Activity API, showing examples and how to interpret them.
Objects
DriveActivity
: This is the main resource returned by queries to the Drive Activity API. It describes one or moreActors
performing one or moreActions
affecting one or moreTargets
.Timestamp
andTimeRange
describe, respectively, either a single point in time when activity occurred, or a start/end when the activity occurred over a span of time.Actor
: Typically, anActor
is an end user. However, in some casesActions
can be triggered by a system event, initiated by an admin acting as a user or as themselves, or performed by an unidentifiable person. TheActor
message encapsulates each of these cases.Target
: ATarget
is the object of some 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, whileEdit
generally applies to Drive files, other actions likeRename
andCreate
can also apply to Drive folders and shared drives. Targets which are not Drive items themselves may still refer to one, such as the root folder of a drive or the parent document containing a file comment.Action
: EachDriveActivity
has one or more relatedActions
. 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 a time stamp or time range. To avoid redundancy, anAction
will not 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 will have a source and destination location, and aPermissionChange
will specify who can now access a document and with what privileges.
Examples
A user edited a file in Drive.
A simple DriveActivity
might include only one action, such as one user editing
one file.
"activities":[{
"primary_action_detail":{ "edit":{} },
"actors":[ { "user":{ "known_user":{ "person_name":"people/999988889999" } } } ],
"targets":[ { "drive_item":{ "name":"items/89ab67cd4523efghijklm1", "title":"Class Notes", "file":{} } } ],
"timestamp":{ "seconds":"1536794657", "nanos":791000000 },
"actions":[ { "detail":{ "edit":{} } } ]
}]
Note that the Action
in this response does not include the Actor
, Target
,
or TimeStamp
because those are the same as those of the overall
DriveActivity
.
Two users edited the same file at similar times.
When consolidation is enabled, related actions will be grouped into one
DriveActivity
. In this example, two similar actions were grouped: one Edit
action from each of two users.
"activities":[{
"primary_action_detail":{ "edit":{} },
"actors":[
{ "user":{ "known_user":{ "person_name":"people/999988889999" } } },
{ "user":{ "known_user":{ "person_name":"people/111100001111" } } }
],
"targets":[
{ "drive_item":{ "name":"items/abcd111222333efgh", "title":"School Calendar", "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/999988889999" } } },
"timestamp":{ "seconds":"1541089830", "nanos":830000000 }
},
{
"detail":{ "edit":{} },
"actor":{ "user":{ "known_user":{ "person_name":"people/111100001111" } } },
"timestamp":{ "seconds":"1541089823", "nanos":712000000 }
}
]
}]
Note that in this example, the Actions
do not contain the Target
, because it
is the same as that of the overall DriveActivity
.
This also illustrates how apps might use only the summary information in
DriveActivity
: without looking at the individual Actions
, this response
indicates that two users edited a given file over a span of time.
A user moved two files into a new directory.
In this example, two related Move
actions were grouped by the consolidation
strategy 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/105019719834313321069" } } } ],
"targets":[
{ "drive_item":{ "name":"items/abc9999defgh", "title":"Client Notes", "file":{} } },
{ "drive_item":{ "name":"items/123xxyyzz456", "title":"Payment History", "file":{} } }
],
"timestamp":{ "seconds":"1541090960", "nanos":985000000 },
"actions":[
{
"detail":{ "move":{ "added_parents":[ { ... } ] "removed_parents":[ { ... } ] } },
"target":{ "drive_item":{ "name":"items/abc9999defgh", "title":"Client Notes", "file":{} } }
},
{
"detail":{ "move":{ "added_parents":[ { ... } ] "removed_parents":[ { ... } ] } },
"target":{ "drive_item":{ "name":"items/123xxyyzz456", "title":"Payment History", "file":{} } }
}
]
}]
Note that the Actions
do not contain the Actor
or TimeStamp
here, because
they are the same as that of the overall DriveActivity
.