Recursively fetching metadata for all files in a Google Drive folder#

For google-drive-to-sqlite I wanted a mechanism to recursively return metadata on every file in a specified Goole Drive folder.

Fetching files in a single folder#

To fetch files in a single folder with the ID FOLDER_ID you need to use this API:

1
https://www.googleapis.com/drive/v3/files?q=...

The q= parameter needs to be fed the following special search query:

1
"FOLDER_ID" in parents

So the URL for a folder with ID 1E6Zg2X2bjjtPzVfX8YqdXZDCoB3AVA7i ends up looking like this:

1
https://www.googleapis.com/drive/v3/files?q=%221E6Zg2X2bjjtPzVfX8YqdXZDCoB3AVA7i%22%20in%20parents

You need to accompany that with a Authorization: Bearer YOUR_ACCESS_TOKEN header - see Google OAuth for CLI applications for more on that.

Fetching specific fields#

The metadata representation you get back by default is pretty thin.

You can add &fields=* to the URL to get back the full JSON representation - but this can actually be a little bit too much data, mainly because it includes a list of every user who has permissions relating to every file.

You can specify individual fields, but it’s not instantly obvious how to do so. The syntax turns out to look like this:

1
nextPageToken, files(id, kind, name)

Each token corresonds to a key, The files(id, kind, name) bit selects the fields you want from items in the files array.

The full list of file keys I’ve been using are:

1
[
2
    "kind",
3
    "id",
4
    "name",
5
    "mimeType",
6
    "starred",
7
    "trashed",
8
    "explicitlyTrashed",
9
    "parents",
10
    "spaces",
11
    "version",
12
    "webViewLink",
13
    "iconLink",
14
    "hasThumbnail",
15
    "thumbnailVersion",
16
    "viewedByMe",
17
    "createdTime",
18
    "modifiedTime",
19
    "modifiedByMe",
20
    "owners",
21
    "lastModifyingUser",
22
    "shared",
23
    "ownedByMe",
24
    "viewersCanCopyContent",
25
    "copyRequiresWriterPermission",
26
    "writersCanShare",
27
    "folderColorRgb",
28
    "quotaBytesUsed",
29
    "isAppAuthorized",
30
    "linkShareMetadata",
31
]

Recursively fetching from sub-folders#

This will get you the files and folders within a folder… but you have to do extra work if you want to recursively fetch files from every sub-folder.

A sub-folder in the response from that API looks like this:

1
{
2
    "kind": "drive#file",
3
    "id": "1ixwEcEUmZ5-RZY2AQrwG-s1rvOF9LtqX",
4
    "name": "My sub-folder",
5
    "mimeType": "application/vnd.google-apps.folder"
6
}

So fetching everything involves fetching the contents of a folder, then filtering out anything with a mimeType of application/vnd.google-apps.folder, extracting the id and recursively fetching the contents of that folder too.

You also need to handle pagination, in case a folder contains more than 100 items. That’s done using the nextPageToken key in the response JSON, which you can then pass as ?pageToken= to the API to retrieve the next page.

Note that while the Google Drive API implies that a file can live in more than one folder - parents is an array of IDs - Google Drive simplified their model in September 2020 such that a file can only be in a single folder.

Code#

Here’s the code I used to implement recursive fetching of folder contents:

1
def paginate_files(access_token, *, q=None, fields=None):
2
    pageToken = None
3
    files_url = "https://www.googleapis.com/drive/v3/files"
4
    params = {}
5
    if fields is not None:
6
        params["fields"] = "nextPageToken, files({})".format(",".join(fields))
7
    if q is not None:
8
        params["q"] = q
9
    while True:
10
        if pageToken is not None:
11
            params["pageToken"] = pageToken
12
        else:
13
            params.pop("pageToken", None)
14
        data = httpx.get(
15
            files_url,
16
            params=params,
17
            headers={"Authorization": "Bearer {}".format(access_token)},
18
            timeout=30.0,
19
        ).json()
20
        if "error" in data:
21
            raise Exception(data)
22
        yield from data["files"]
23
        pageToken = data.get("nextPageToken", None)
24
        if pageToken is None:
25
            break
26

27

28
def files_in_folder_recursive(access_token, folder_id, fields):
29
    for file in paginate_files(
30
        access_token, q='"{}" in parents'.format(folder_id), fields=fields
31
    ):
32
        yield file
33
        if file["mimeType"] == "application/vnd.google-apps.folder":
34
            yield from files_in_folder_recursive(access_token, file["id"], fields)