googledrive 2.0.0

We’re jazzed to announce the release of googledrive 2.0.0 (https://googledrive.tidyverse.org).

googledrive wraps the Drive REST API v3. The most common file operations are implemented in high-level functions designed for ease of use. You can find, list, create, trash, delete, rename, move, copy, browse, download, read, share, and publish Drive files, including those on shared drives.

You can install it from CRAN with:

install.packages("googledrive")

Version 2.0.0 is mostly motivated by the need to react to changes to Google Drive and in the Drive API itself. We’re also bumping the required version of the gargle package (https://gargle.r-lib.org), which handles everything around auth.

You can see a full list of changes in the release notes.

Auth updates

If you are generally fairly passive about googledrive auth, then you should just sit back and let things happen organically during usage. If you’ve used googledrive before, you can expect to see some messages about cleaning and relocating the token cache when you first use v2.0.0. You can also expect to re-authenticate yourself with Google and re-authorize the “Tidyverse API Packages” to work with your files. This is all due to changes in gargle.

If your usage requires you to be more proactive about auth, read the blog post for gargle’s recent v1.2.0 release. A key point is that we have rolled the built-in OAuth client, which is why those relying on it will need to re-auth.

If the rolling of the tidyverse OAuth client is highly disruptive to your workflow, consider this a wake-up call that you should be using your own OAuth client or, quite possibly, an entirely different method of auth. Our credential rolling will have no impact on users who use their own OAuth client or service account tokens.

Team Drives are dead! Long live shared drives!

Google Drive has rebranded Team Drives as shared drives. While anyone can have a My Drive, shared drives are only available for Google Workspace (previously known as G Suite). This generally means a Google account you have through your employer or school, as opposed to a personal one. Shared drives and the files within are owned by a team or organization, as opposed to an individual.

The transition from Team Drives to shared drives appears to be more about vocabulary than changes in behaviour. Inside googledrive, this required some housekeeping work, but users won’t notice much other than the obvious changes to function and argument names.

All team_drive_*() functions have been deprecated, in favor of their shared_drive_*() successors. Likewise, any team_drive argument has been deprecated, in favor of a new shared_drive argument. The terms used to describe search collections have also changed slightly, with "allDrives" replacing "all". This applies to the corpus argument of drive_find() and drive_get().

Single parenting and shortcuts

As of 2020-09-30, Drive no longer allows a file to be placed in multiple folders, which, frankly, is a big relief! Going forward, every file will have exactly 1 parent folder. In many cases that parent is just the top-level or root folder of your “My Drive” or of a shared drive.

This change has been accompanied by the introduction of file shortcuts, which function much like symbolic or “soft” links. Shortcuts are the new way to make a file appear to be in more than one place. A shortcut is a special type of Drive file, characterized by the application/vnd.google-apps.shortcut MIME type.

You can make a shortcut to any Drive file, including to a Drive folder, with shortcut_create(). Here we also use drive_example_remote() to access one of our new persistent, world-readable example files.

library(googledrive)

# Target one of the official example files
(src_file <- drive_example_remote("chicken.csv"))
#> # A dribble: 1 x 3
#>   name        id                                drive_resource   
#>   <chr>       <drv_id>                          <list>           
#> 1 chicken.csv 1VOh6wWbRfuQLxbLg87o58vxJt95SIiZ7 <named list [37]>

sc <- src_file %>% 
  shortcut_create(name = "chicken_sheet_shortcut")
#> Created Drive file:
#> • 'chicken_sheet_shortcut' <id: 1YAPexlK3b3o7Mk-xadahXMYbMGLvScea>
#> With MIME type:
#> • 'application/vnd.google-apps.shortcut'

Use shortcut_resolve() to dereference a shortcut, i.e. resolve it to its target file id. Here we also demonstrate the new drive_read_string() function that is handy for reading file content directly into R.

sc %>% 
  shortcut_resolve() %>%
  drive_read_string() %>% 
  readr::read_csv()
#> ℹ Resolved 1 shortcut found in 1 file:
#> • 'chicken_sheet_shortcut' <id: 1YAPexlK3b3o7Mk-xadahXMYbMGLvScea> ->
#>   'chicken.csv' <id: 1VOh6wWbRfuQLxbLg87o58vxJt95SIiZ7>
#> No encoding supplied: defaulting to UTF-8.
#> # A tibble: 5 x 4
#>   chicken            breed         sex    motto                                 
#>   <chr>              <chr>         <chr>  <chr>                                 
#> 1 Foghorn Leghorn    Leghorn       roost… That's a joke, ah say, that's a joke,…
#> 2 Chicken Little     unknown       hen    The sky is falling!                   
#> 3 Ginger             Rhode Island… hen    Listen. We'll either die free chicken…
#> 4 Camilla the Chick… Chantecler    hen    Bawk, buck, ba-gawk.                  
#> 5 Ernie The Giant C… Brahma        roost… Put Captain Solo in the cargo hold.

If you just want to see whether a file is a shortcut, use drive_reveal(dat, "mime_type") to add a MIME type column to any dribble.

Drive has been migrating existing files to the one-parent state, i.e., “single parenting” them. Drive selects the most suitable parent folder to keep, “based on the hierarchy’s properties”, and replaces any other parent-child relationships with a shortcut.

If you often refer to Drive files by their filepath (or name), as opposed to by file id, look in the release notes for more about how shortcuts are handled within googledrive.

Making googledrive shut up

googledrive_quiet is a new option to suppress informational messages from googledrive. Unless it’s explicitly set to TRUE, the default is to message. local_drive_quiet() and with_drive_quiet() are withr-style convenience helpers for setting googledrive_quiet = TRUE for some limited scope.

As a result, the verbose argument of all googledrive functions is deprecated and will be removed in a future release. In the current release, verbose = FALSE is still honored, but generates a warning.

Everything else

Remember that the release notes offer more information.

Here are a few more changes in v2.0.0:

The user interface has gotten more stylish, thanks to the cli package (https://cli.r-lib.org). All informational messages, warnings, and errors are now emitted via cli, which uses rlang’s condition functions under-the-hood.
We now share a variety of world-readable, persistent example files on Drive, for use in examples and documentation. These remote example files complement the local example files that were already included in googledrive. Access with drive_examples_remote() and friends.
drive_read_string() and drive_read_raw() are new functions that read the content of a Drive file directly into R.
The dribble and drive_id classes are implemented using a more modern and effective approach from the vctrs package (https://vctrs.r-lib.org).

Acknowledgements

We’d like to thank everyone who has furthered the development of googledrive, since the last major release (v1.0.0), through their contributions in issues and pull requests:

@andrie, @Arf9999, @batpigandme, @ben519, @bllittle, @bschilder, @bshor, @christopherkn, @claytonperry, @cmchuter, @ctgrubb, @DataStrategist, @DavidGarciaEstaun, @Diego-MX, @dollarvora, @douglascm, @drwilkins, @enricodata, @FedericoTrifoglio, @griswomw, @hadley, @hideaki, @ian-adams, @jcheng5, @jennybc, @jimhester, @JMKelleher, @jobdiogenes, @kongdd, @kpmainali, @mehrnoushmalek, @MichaelTD83, @mitchelloharawild, @muschellij2, @paulvern, @pseudorational, @robertoromor, @shahab3476, @smingerson, @spocks, @tklebel, @tpbarrette, @viquiff92, @vnijs, @voremargot, @wilvancleve, @wuc66, and @xgirouxb.