index.Rmd

---
output: github_document
---

```{r setup, include = FALSE}
auth_success <- tryCatch(
  googledrive:::drive_auth_docs(),
  googledrive_auth_internal_error = function(e) e
)

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  error = TRUE,
  purl = googledrive::drive_has_token(),
  eval = googledrive::drive_has_token()
)
```

```{r eval = !googledrive::drive_has_token(), echo = FALSE, comment = NA}
googledrive:::drive_bullets(c(
  "Code chunks will not be evaluated, because:",
  strsplit(auth_success$message, split = "\n")[[1]]
))
googledrive::drive_deauth()
```

# googledrive

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/googledrive)](https://CRAN.R-project.org/package=googledrive)
[![R-CMD-check](https://github.com/tidyverse/googledrive/workflows/R-CMD-check/badge.svg)](https://github.com/tidyverse/googledrive/actions)
[![Codecov test coverage](https://codecov.io/gh/tidyverse/googledrive/branch/main/graph/badge.svg)](https://codecov.io/gh/tidyverse/googledrive?branch=main)
<!-- badges: end -->

## Overview

googledrive allows you to interact with files on Google Drive from R.

## Installation

Install from CRAN:

```{r, eval = FALSE}
install.packages("googledrive")
```

## Usage

### Load googledrive

```{r}
library("googledrive")
```

```{r drive-setup, eval = FALSE, include = FALSE}
# This chunk contains code to setup all the files necessary for this document
# to make sense, starting from a blank slate. Likewise, it contains code to
# delete those same files.
#
# It is meant to be run occasionally, interactively, by a human maintainer.
# So far, I can't think of anywhere better to put this.
#
# The visible, executable chunks may also create files, in which case the
# necessary clean up code shall also be visible and executable.

CLEAN <- SETUP <- FALSE

examples <- drive_examples_remote()
builtin <- c(
  system.file("DESCRIPTION"),
  R.home("doc/html/Rlogo.svg"),
  R.home("doc/BioC_mirrors.csv"),
  R.home("doc/THANKS")
)

if (isTRUE(SETUP)) {
  purrr::map2(
    examples$id, examples$name,
    ~ drive_cp(as_id(.x), name = .y)
  )
  purrr::map(builtin, ~ drive_upload(.x))

  drive_mkdir("abc")
  abc_def <- drive_mkdir("abc/def")
  drive_upload(
    system.file("NEWS.md", package = "googledrive"),
    path = abc_def,
    name = "googledrive-NEWS.md"
  )
  
  THANKS <- drive_get("THANKS")
  r_logo <- drive_get("r_logo.jpg")
  x <- list(THANKS, r_logo)
  purrr::map(x, ~ drive_update(.x, starred = TRUE))
  purrr::map(x, ~ drive_share(.x, role = "reader", type = "anyone"))
}

if (isTRUE(CLEAN)) {
  drive_rm(examples)
  drive_rm(basename(builtin))
  drive_rm("abc/")
  drive_rm(drive_find("index-chicken"))
}
```

### Package conventions

* Most functions begin with the prefix `drive_`. Auto-completion is your friend.
* Goal is to allow Drive access that feels similar to Unix file system utilities, e.g., `find`, `ls`, `mv`, `cp`, `mkdir`, and `rm`.
* The metadata for one or more Drive files is held in a `dribble`, a "Drive tibble". This is a data frame with one row per file. A dribble is returned (and accepted) by almost every function in googledrive. Design goals:
  - Give humans what they want: the file name
  - Track what the API wants: the file ID
  - Hold on to all the other metadata sent back by the API
* googledrive is "pipe-friendly" and, in fact, re-exports `%>%`, but does not require its use.

### Quick demo

Here's how to list up to `n_max` of the files you see in [My Drive](https://drive.google.com). You can expect to be sent to your browser here, to authenticate yourself and authorize the googledrive package to deal on your behalf with Google Drive.

```{r}
drive_find(n_max = 30)
```

You can narrow the query by specifying a `pattern` you'd like to match names against. Or by specifying a file type: the `type` argument understands MIME types, file extensions, and a few human-friendly keywords.

```{r eval = FALSE}
drive_find(pattern = "chicken")
drive_find(type = "spreadsheet")     ## Google Sheets!
drive_find(type = "csv")             ## MIME type = "text/csv"
drive_find(type = "application/pdf") ## MIME type = "application/pdf"
```

Alternatively, you can refine the search using the `q` query parameter. Accepted search clauses can be found in the [Google Drive API documentation](https://developers.google.com/drive/v3/web/search-parameters). For example, to see all files that you've starred and that are readable by "anyone with a link", do this:

```{r}
(files <- drive_find(q = c("starred = true", "visibility = 'anyoneWithLink'")))
```

You generally want to store the result of a googledrive call, as we do with `files` above. `files` is a dribble with info on several files and can be used as the input for downstream calls. It can also be manipulated as a regular data frame at any point.

#### Identify files

`drive_find()` searches by file properties, but you can also identify files by name (path, really) or by Drive file id using `drive_get()`.

```{r}
(x <- drive_get("~/abc/def/googledrive-NEWS.md"))
```

`as_id()` can be used to convert various inputs into a marked vector of file ids. It works on file ids (for obvious reasons!), various forms of Drive URLs, and `dribble`s.
 
```{r}
x$id

# let's retrieve same file by id (also a great way to force-refresh metadata)
drive_get(x$id)
drive_get(as_id(x))
```

In general, googledrive functions that operate on files allow you to specify the file(s) by name/path, file id, or in a `dribble`. If it's ambiguous, use `as_id()` to mark a character vector as holding Drive file ids as opposed to file paths. This function can also extract file ids from various URLs.

#### Upload files

We can upload any file type. 

```{r}
(chicken <- drive_upload(
  drive_example_local("chicken.csv"),
  "index-chicken.csv"
))
```

Notice that file was uploaded as `text/csv`. Since this was a `.csv` document, and we didn't specify the type, googledrive guessed the MIME type. We can overrule this by using the `type` parameter to upload as a Google Spreadsheet. Let's delete this file first.

```{r}
drive_rm(chicken)

# example of using a dribble as input
chicken_sheet <- drive_example_local("chicken.csv") %>% 
  drive_upload(
    name = "index-chicken-sheet",
    type = "spreadsheet"
  )
```

Much better!

#### Share files

To allow other people to access your file, you need to change the sharing permissions. You can check the sharing status by running `drive_reveal(..., "permissions")`, which adds a logical column `shared` and parks more detailed metadata in a `permissions_resource` variable.

```{r}
chicken_sheet %>% 
  drive_reveal("permissions")
```

Here's how to grant anyone with the link permission to view this data set.

```{r}
(chicken_sheet <- chicken_sheet %>%
   drive_share(role = "reader", type = "anyone"))
```

This comes up so often, there's even a convenience wrapper, `drive_share_anyone()`.

#### Publish files

Versions of Google Documents, Sheets, and Presentations can be published online. You can check your publication status by running `drive_reveal(..., "published")`, which adds a logical column `published` and parks more detailed metadata in a `revision_resource` variable.

```{r}
chicken_sheet %>% 
  drive_reveal("published")
```

By default, `drive_publish()` will publish your most recent version.

```{r}
(chicken_sheet <- drive_publish(chicken_sheet))
```

#### Download files

##### Google files

We can download files from Google Drive. Native Google file types (such as Google Documents, Google Sheets, Google Slides, etc.) need to be exported to some conventional file type. There are reasonable defaults or you can specify this explicitly via `type` or implicitly via the file extension in `path`. For example, if I would like to download the "chicken_sheet" Google Sheet as a `.csv` I could run the following.

```{r}
drive_download("index-chicken-sheet", type = "csv")
```

Alternatively, I could specify type via the `path` parameter.

```{r}
drive_download(
  "index-chicken-sheet",
  path = "index-chicken-sheet.csv",
  overwrite = TRUE
)
```

Notice in the example above, I specified `overwrite = TRUE`, in order to overwrite the local csv file previously saved.

Finally, you could just allow export to the default type. In the case of Google Sheets, this is an Excel workbook:

```{r}
drive_download("index-chicken-sheet")
```

##### All other files

Downloading files that are *not* Google type files is even simpler, i.e. it does not require any conversion or type info.

```{r}
# download it and prove we got it
drive_download("chicken.txt")
readLines("chicken.txt") %>% head()
```

#### Clean up

```{r}
file.remove(c(
  "index-chicken-sheet.csv", "index-chicken-sheet.xlsx", "chicken.txt"
))
drive_find("index-chicken") %>% drive_rm()
```

## Privacy

[Privacy policy](https://www.tidyverse.org/google_privacy_policy)