Google Drive API v3 — Files Resource

When learning to use the Drive API, a good place to start is the Files resource. It is, after all, the most important of all the resources (it’s what we’re storing on Google Drive isn’t it?).

The resource has quite a comprehensive list of fields including:

  • Standard file metadata (name, size, createdTime, etc)
  • Permissions (ownership, sharing, etc)
  • Image metadata (dimensions, camera, exposure settings, etc)
  • Video metadata (dimensions, duration)

Files can be modified/accessed via a number of fairly self explanatory methods:

Now it’s worth noting that while the list of metadata for the resource is huge, by default methods will only return a few very basic ones:

{
"kind": "drive#file",
"id": "<id goes here>",
"name": "P7160390.jpg",
"mimeType": "image/jpeg"
}

Fields

In order to access the additional fields you need to understand the Standard Query Parameters which includes the fields parameter which allows selection of resource parameters to be returned (see also partial response for a full description).

For example, when using the get method with the default parameters:

{
"kind": "drive#file",
"id": "<id goes here>",
"name": "P7160390.jpg",
"mimeType": "image/jpeg"
}
Expand “Show standard parameters” to see the “fields” parameter.

When using the fields=* you get…. everything:

{
"kind": "drive#file",
"id": "<id goes here>",
"name": "P7160390.jpg",
"mimeType": "image/jpeg",
"description": "OLYMPUS DIGITAL CAMERA",
"starred": false,
"trashed": false,
"explicitlyTrashed": false,
"parents": [
"<parent id goes here>"
],
"spaces": [
"drive"
],
"version": "73714",
"webContentLink": "<link goes here>",
"webViewLink": "<link goes here>",
"iconLink": "<link goes here>",
"hasThumbnail": true,
"thumbnailLink": "<link goes here>",
"thumbnailVersion": "1",
"viewedByMe": true,
"viewedByMeTime": "2017-08-02T07:25:12.817Z",
"createdTime": "2017-08-02T07:25:12.817Z",
"modifiedTime": "2017-08-02T07:25:12.817Z",
"modifiedByMeTime": "2017-08-02T07:25:12.817Z",
"modifiedByMe": true,
"owners": [
{
"kind": "drive#user",
"displayName": "Dale Clutterbuck",
"me": true,
"permissionId": "<permission id goes here>",
"emailAddress": "<email goes here>"
}
],
"lastModifyingUser": {
"kind": "drive#user",
"displayName": "Dale Clutterbuck",
"me": true,
"permissionId": "<permission id goes here>",
"emailAddress": "<email goes here>"
},
"shared": false,
"ownedByMe": true,
"capabilities": {
"canAddChildren": false,
"canChangeViewersCanCopyContent": true,
"canComment": true,
"canCopy": true,
"canDelete": true,
"canDownload": true,
"canEdit": true,
"canListChildren": false,
"canMoveItemIntoTeamDrive": true,
"canReadRevisions": true,
"canRemoveChildren": false,
"canRename": true,
"canShare": true,
"canTrash": true,
"canUntrash": true
},
"viewersCanCopyContent": true,
"writersCanShare": true,
"permissions": [
{
"kind": "drive#permission",
"id": "<permission id goes here>",
"type": "user",
"emailAddress": "<email goes here>",
"role": "owner",
"displayName": "Dale Clutterbuck",
"deleted": false
}
],
"originalFilename": "P7160390.jpg",
"fullFileExtension": "jpg",
"fileExtension": "jpg",
"md5Checksum": "fe2c874a9930f96096bb5732debf2cd9",
"size": "7064333",
"quotaBytesUsed": "7064333",
"headRevisionId": "<id for the head revision goes here>",
"imageMediaMetadata": {
"width": 2934,
"height": 3912,
"rotation": 0,
"time": "2017:07:25 14:32:24",
"cameraMake": "OLYMPUS IMAGING CORP.",
"cameraModel": "E-M5MarkII",
"exposureTime": 0.016666668,
"aperture": 3.5,
"flashUsed": false,
"focalLength": 34.0,
"isoSpeed": 200,
"meteringMode": "Pattern",
"exposureMode": "Auto",
"colorSpace": "sRGB",
"whiteBalance": "Auto",
"exposureBias": 0.0,
"maxApertureValue": 3.0,
"lens": "OLYMPUS M.12-40mm F2.8"
},
"isAppAuthorized": false
}
Using the “*” in fields I can get the full complete metadata for the file.

You can selectively choose fields, for example using the fields=name,trashed:

{
“name”: “P7160390.jpg”,
“trashed”: false
}

Pagination

The API uses pagination to limit the size of responses. By default the list method will usually return up to 100 results. However this can be selected from 1 to 1000 using the pageSize parameter, for example pagesize=1000.

If a method returns more than the request page size, or there are more results the nextPageToken will be provided with the response. If there are no more results, the nextPageToken will be omitted.

{
"kind": "drive#fileList",
"nextPageToken": "<next page token is here>",
...

In order to get the next page of results, you need to include the previous nextPageToken as a parameter in the next method call pageToken=<previous next page token>.

Searching

When using the list method, it is useful to understand how to search (duh, this is a Google product). Search is done using the q parameter. The documentation has a good description of how to use the search functionality. Without it, list will return everything, including files that have been “trashed”.

For example using the list method with q=trashed=true will provide the list of all the trashed files.

To search for the list of files within a folder, you need to know the ID of the folder. If you don’t already have the ID, get the ID using the q=name="Test"and trashed=false parameter and the list method:

{
“kind”: “drive#fileList”,
“incompleteSearch”: false,
“files”: [
{
“kind”: “drive#file”,
“id”: “<the folder id>”,
“name”: “Test”,
“mimeType”: “application/vnd.google-apps.folder”
}
]
}

Then using the folder id with the list method again and q="<the folder id>" in parents (the quotations are important) will return a list of the files that have the folder as their parent:

{
“kind”: “drive#fileList”,
“incompleteSearch”: false,
“files”: [
{
“kind”: “drive#file”,
“id”: “<id>”,
“name”: “P7160390.jpg”,
“mimeType”: “image/jpeg”
},
<...snip...>,
{
“kind”: “drive#file”,
“id”: “<id>”,
“name”: “Test Doc”,
“mimeType”: “application/vnd.google-apps.document”
}
]
}

Useful notes

  • You can pre-generate ID’s before uploading documents (for non-Google Docs/Sheets/etc), but you don’t have to.
  • List returns everything, including trashed files.
  • List can only return up to 1000 files and may revert to pagination. Expect to do repeated calls to get the complete list. Always lookout for the nextPageToken in the response!
  • Folders don’t know their children, but files/folders know who their parents are.
  • Description and links to the various sections of the Google Drive API v3 documentation can be found at the bottom of my other article