Drive Activity API Data Model

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 more Actors performing one or more Actions affecting one or more Targets.

  • Timestamp and TimeRange 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, an Actor is an end user. However, in some cases Actions can be triggered by a system event, initiated by an admin acting as a user or as themselves, or performed by an unidentifiable person. The Actor message encapsulates each of these cases.

  • Target: A Target 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, while Edit generally applies to Drive files, other actions like Rename and Create 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: Each DriveActivity has one or more related Actions. An Action is self-contained, like an event, in that it comprises not only the detailed type and information about the action, but also an Actor, a Target, and either a time stamp or time range. To avoid redundancy, an Action will not populate its own Target, Actor, or time fields when those are the same as the overall DriveActivity.

  • ActionDetail: This is the specific type and detailed information about an Action. For example, a Move action detail will have a source and destination location, and a PermissionChange 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.