Drive Activity API data model

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 and TimeRange—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, an Actor is an end user. However, sometimes, a system event can trigger an Action when an admin is acting as a user or as themselves, or when performed by an unidentifiable person. The Actor message encapsulates each of these cases.

  • Target—A Target 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, though Edit generally applies to Drive files, other actions like Rename and Create 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—Each DriveActivity resource 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 Timestamp or TimeRange. To avoid redundancy, an Action doesn't 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 has a source and destination location, and a PermissionChange 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.