Working With the Google Drive API: Track Changes in Individual and Team Drives

Developers commonly integrate with cloud storage services such as Google Drive to sync files that change between their app and users’ cloud storage. At Kloudless, we’ve seen activity monitoring used for everything from workflow automation to data loss protection.

The Kloudless unified Events API enables developers to track changes regardless of which cloud storage account a user connects. Google Drive remains one of the most popular services users connect accounts for. In this blog post, we’ll discuss the various ways to track changes in Google Drive and when to use each.

Google Drive provides three different API endpoints each capable of tracking changes in a user’s account:

• The Drive Changes API
• The Drive Activity API
• The Admin SDK’s Reports API

The Changes API

The Changes API provides an efficient way to detect changes to all files, including those that have been shared with a user. Here is an example of a change resource returned when listing changes in an account:

{
  "kind": "drive#change",
  "type": "file",
  "time": "2017-09-07T09:02:26.581Z",
  "removed": false,
  "fileId": "0B648bYBbhWYoc3RhcnRlcl9maWxlX2Rhc2hlclYw",
  "file": {
   "kind": "drive#file",
   "id": "0B648bYBbhWYoc3RhcnRlcl9maWxlX2Rhc2hlclYw",
   "name": "Getting started",
   "mimeType": "application/pdf"
  }
}

The Changes API helps detect which data has changed or been removed. It doesn’t provide much information on how the change occurred, or activity other than additions, updates, and deletions. However, the Changes API does support webhook notifications to avoid repeatedly polling the API endpoints.

This API endpoint especially helps with use cases involving basic one-way sync, such as with automation rules. However, the Drive Activity API described below is more helpful for use cases that require additional detail.

The Activity API

The Drive Activity API also retrieves changes in a user’s Google Drive or Team Drive but provides more detail than the Changes API does. File renames and moves don’t overlap with additions and deletions, for example. Here is an example DriveActivity object:

{
  "primaryActionDetail": {
    "create": {
      "new": {}
    }
  },
  "actors": [
    {
      "user": {
        "knownUser": {
          "personName": "people/105543818741636526322",
          "isCurrentUser": true
        }
      }
    }
  ],
  "actions": [
    {
      "detail": {
        "create": {
          "new": {}
        }
      }
    },
    {
      "detail": {
        "move": {
          "addedParents": [
            {
              "driveItem": {
                "name": "items/0AK48bYBbhWYoUk9PVA",
                "folder": {
                  "type": "MY_DRIVE_ROOT"
                }
              }
            }
          ]
        }
      }
    }
  ],
  "targets": [
    {
      "driveItem": {
        "name": "items/1sP77lasbdEw0MuzRYn_Wwe60fQsBtJ0e",
        "title": "test_75",
        "folder": {
          "type": "STANDARD_FOLDER"
        },
        "mimeType": "application/vnd.google-apps.folder",
        "owner": {
          "user": {
            "knownUser": {
              "personName": "people/105543818745636526322",
              "isCurrentUser": true
            }
          },
          "domain": {
            "name": "kloudless.com",
            "legacyId": "115685618164385049061"
          }
        }
      }
    }
  ],
  "timestamp": "2019-01-11T01:44:42.774Z"
}

Examples of additional detail include the type, target, and actor associated with the event. This enables nuanced responses to different types of activity, such as in use cases involving analysis and audit.

This API endpoint’s primary downside is that it requires activity to be queried rather than followed in a stream. The API response returns activity in descending order by time, which makes it harder to get new events beginning at a particular point in time. To do so, developers must paginate backward in time till reaching the point in the event stream they’d like to begin receiving data from.

The Reports API

Only G Suite admins can grant access to their organization’s activity data via the Admin SDK’s Reports API. It provides the ability to monitor all activity in a G Suite tenant.

This also means that all activity in Team Drives can be monitored with a single query, which is a major benefit over the Changes and Activity API that each require individual requests for activity on every Team Drive. For example, the Activity API only returns activity in a user’s individual Google Drive unless the request specifies a Team Drive ID as the ancestor.

To retrieve org-wide Google Drive activity using the Reports API, set the applicationName to drive in the list request‘s query parameter. Here is an example Drive Audit Activity event:

{
  "kind": "admin#reports#activity",
  "id": {
    "time": "2019-02-06T09:03:39.606Z",
    "uniqueQualifier": "-5443151506617447182",
    "applicationName": "drive",
    "customerId": "C01qa2s2v"
  },
  "etag": "\"S3VtFupSeWkpIL4X4oyC3FQHUIg/E2ZKSzeRrqE9s-FpaKGD2CoejFk\"",
  "actor": {
    "email": "jord@kloudless.com",
    "profileId": "100363596389311801930"
  },
  "ipAddress": "51.34.106.0",
  "events": [
    {
      "type": "access",
      "name": "delete",
      "parameters": [
        {
          "name": "primary_event",
          "boolValue": true
        },
        {
          "name": "billable",
          "boolValue": true
        },
        {
          "name": "doc_id",
          "value": "11Y1Z3vaZHkhWuOy69BqzNgXzpn-KyP8W"
        },
        {
          "name": "doc_type",
          "value": "unknown"
        },
        {
          "name": "doc_title",
          "value": "tést_file_53019599"
        },
        {
          "name": "visibility",
          "value": "private"
        },
        {
          "name": "owner",
          "value": "jord@kloudless.com"
        },
        {
          "name": "owner_is_team_drive",
          "boolValue": false
        }
      ]
    }
  ]
}

The Reports API especially helps with use cases related to audit and security, such as Data Loss Prevention. It also supports webhooks.

However, apps might find it challenging to identify complex actions since the API groups together several sub-events and marks one as the primary action. Certain inconsistencies may appear, such as both copies and new file creation including create as the primary action, and change_acl_editors representing either link creation or deletion. In some cases, the API doesn’t identify the primary event either.