Drv is a SuperFetch plugin to access the Google Drive API. SuperFetch is a proxy for UrlFetchApp with additional features – see SuperFetch – a proxy enhancement to Apps Script UrlFetch for how it works and what it does.
This is another in my series on SuperFetch plugins.
Motivation
There are of course already 2 Drive API services (Drive and DriveApp) for Apps Script. As well as built in caching and list handling, SuperFetch plugin takes a slightly different approach to these Drive APIS, which are about navigating Drive via a series of file and folder ids.
Drv supports ids, but it also provides a more standard path style of file access (eg user/files/documents/a.doc) which I personally prefer to messing around with all those ids. Not all methods are supported yet of course, but I’ll add more over time.
Behind the scenes, Drv use the Drive REST API. It doesn’t use the built in Apps Script services at all.
The main additional features of Drv are
- Access files and folders by their path and name as well as their id
- Create intermediate folders on the fly
- Handle big lists of files automatically without bothering about paging
- Built in caching
- Closures for relative paths
- Wildcards
- Version pruning
- Resumable uploads for big files
- Automatic detection of and conversion to and from JSON
- Export and conversions automatically supported
I’ll cover some of these in this article and some more advanced topics in future articles
Script Preparation
You’ll need the bmSuperFetch library and if you want to run some tests, the bmUnitTest library – details at the end of the article.
I use a regular cloud project for all of these plugins rather than the Apps Script managed one (you can change it in Project settings), and you’ll need at least these scopes enabled in your manifest file (appsscript.json), as well as the Drive API enabled
Instantiation
First you need a SuperFetch instance. If you don’t need caching, then just omit the cacheService property.
Drv instance
This will be the handle for accessing Drv
There are various other standard SuperFetch Plugin parameters that I’ll deal with later, but the ones shown are of special interest to this article.
noCache property (optional)
You can turn off caching by setting this to true, or by omitting the CacheService poperty in the SuperFetch instantiation.
base property (optional)
You can ignore the base property if you want to be able to write to the top level of the Drive. But setting a top folder means that you can isolate to some subfolder. All all paths accessed by this instance will be relative to this base. Eg if you set base to test/users, all operations will be relative to the folder test/users
Usage
Uploading data
This will upload the payload data and return the metadata of a newly created file ‘testdrv/json/stuff.json’.
Getting the file metadata
This returns the file metadata
Downloading data
This will return the content – if it’s pareseable (as in this case), the result will be in the data property. Later on we’ll look at other kinds of data
Closures
As with all other SuperFetch plugins, Drv makes use of closures.
Path closure
Let’s rewrite all of the above using the path closure.
Combined path closure
You can specify the path and name in either the path or the access method, and in if you specify the path property in both of them, they are combined. Let’s write that again as a combined path.
Ref
You can create a new instance of drv base on an existing instance. Typically you might want to do this either to set a new base (top folder), or to change some of the characteristics of the instance (eg switch off caching).
All of these will produce the same request
Here’s how to use ref to duplicate an instance but with caching off. Any drv constructor options can be passed as the second argument of .ref()
Why closures ?
These different ways of specifying the same thing are a very useful way of limiting operations to an area of drive below a particular folder, and reusing code with minimal changes in different modes.
Listing contents
You can get a list of files like this. All of these are equivalent. In the case of list, the name property refers to the final folder name – so for example the contents of users/profiles/documents would be specified as {path:’users/profiles’, name:’documents’}
Queries in listings
.list() can also take any of the queries described in Search Query Terms for Drive
Queries can be combined with any of the closures mentioned earlier.
Paging closure
The drive API has a maximum pageSize of 1000, and after that you’d need to worry about handling paging with the basic APIS. Drv takes care of that and will make whatever calls are necessary to consolidate all the results without you having to do anything. Normally in Server side Apps Script, you just want all the the files at once.
Limit list max number of results
Behind the scenes, it’ll optimize the pageSize and make as many calls as necessary to achieve your requested max. The default max is Infinity.
Do your own paging
There may be a reason that you want to do paging or to limit the number of results per request. Drv Supports this through its paging closure. You specify the max number of items you want back, and Drv returns those, plus a pageToken if there are still more. Here’s how to do your own paging.
Caching and paging
You’ll notice I turned caching off to do my own paging in the previous example. This is because pageTokens could be invalid if taken from a previously cached result, so you must use a drv instance with noCache: true. The simplest way to do this is just to get a ref, as in the example above.
Drv will detect if you are trying do your own paging with an instance with caching enabled and give you this error
SuperFetch reponse
The result of each of these operations is a SuperFetch response that looks like this.
You’ll mainly be interested in these properties
For more info on this and other response properties see SuperFetch – a proxy enhancement to Apps Script UrlFetch
Error handling
All Superfetch plugins use the same method of signalling or optionally, reacting to an error.
You can detect an error by checking the result.error property or you can force an automatic throw if an error is detected. Here’s examples of each of these.
Constructor parameters
I’ve mentioned the usual Drv constructor parameters earlier, but here’s a full list of those expected by the constructor.
Ref parameters
The ref method creates a new Drv instance, but with a new base. The DrvApiOptions argument is the same object as for the Drv constructor, but the base property is ignored.
Unit testing
I’ll use Simple but powerful Apps Script Unit Test library to demonstrate calls and responses. It should be straightforward to see how this works and the responsese to expect from calls. These tests demonstrate each of the topics mentioned in this article, as well as some I’ll be covering in a later article, and could serve as a useful crib sheet for the plugin – it’s a long read so you may want to just come back and refer to this.
Next
I’ve only covered some of the drv topics in this article – there are plenty more, so watch out for the next 2 or 3 on this plugin.
Still to come –
- folder processing
- metadata
- wildcards
- handling big files
- exporting
- converting
- pruning
- handling rate limit problems
Links
bmSuperFetch: 1B2scq2fYEcfoGyt9aXxUdoUPuLy-qbUC2_8lboUEdnNlzpGGWldoVYg2
bmUnitTester: 1zOlHMOpO89vqLPe5XpC-wzA9r5yaBkWt_qFjKqFNsIZtNJ-iUjBYDt-x
Related

Convert any file with Apps Script

Caching, property stores and pre-caching

State management across CardService, HtmlService and Server side Add-ons

SuperFetch Plugin: Cloud Manager Secrets and Apps Script

SuperFetch caching: How does it work?

SuperFetch plugins: Tank events and appending

SuperFetch Plugins: Apps Script streaming with Tank and Drive

SuperFetch Tank Plugin: Streaming for Apps Script

SuperFetch plugin – Google Drive client for Apps Script – Part 1

SuperFetch – Twitter plugin for Apps Script – Get Follows, Mutes and blocks

SuperFetch plugin – Twitter client for Apps Script – Counts

OAuth2 and Twitter API – App only flow for Apps Script

SuperFetch plugin – Twitter client for Apps Script – Search and Get

Apps Script Oauth2 library Goa: tips, tricks and hacks

Apps Script Oauth2 – a Goa Library refresher

SuperFetch plugin – Firebase client for Apps Script

SuperFetch plugin – iam – how to authenticate to Cloud Run from Apps Script

SuperFetch – a proxy enhancement to Apps Script UrlFetch

Apps script caching with compression and enhanced size limitations
