/
README.Rmd
168 lines (114 loc) · 7.79 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
can_decrypt <- gargle::secret_has_key("GOOGLESHEETS4_KEY")
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
error = TRUE,
fig.path = "man/figures/README-",
out.width = "100%",
purl = can_decrypt,
eval = can_decrypt
)
options(tibble.print_min = 5L, tibble.print_max = 5L)
```
```{r eval = !can_decrypt, echo = FALSE, comment = NA}
message("No token available. Code chunks will not be evaluated.")
```
```{r readme-auth, include = FALSE}
googlesheets4:::gs4_auth_docs()
```
# googlesheets4 <a href="https://googlesheets4.tidyverse.org"><img src="man/figures/logo.png" align="right" height="138" alt = ""/></a>
<!-- badges: start -->
[](https://CRAN.R-project.org/package=googlesheets4)
[](https://github.com/tidyverse/googlesheets4/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/tidyverse/googlesheets4?branch=main)
<!-- badges: end -->
## Overview
googlesheets4 provides an R interface to [Google Sheets](https://docs.google.com/spreadsheets/) via the [Sheets API v4](https://developers.google.com/sheets/api/). It is a reboot of an earlier package called [googlesheets](https://github.com/jennybc/googlesheets#readme).
*Why **4**? Why googlesheets**4**? Did I miss googlesheets1 through 3? No. The idea is to name the package after the corresponding version of the Sheets API. In hindsight, the original googlesheets should have been googlesheets**3**.*
## Installation
You can install the released version of googlesheets4 from [CRAN](https://CRAN.R-project.org) with:
```{r, eval = FALSE}
install.packages("googlesheets4")
```
And the development version from [GitHub](https://github.com/) with:
```{r eval = FALSE}
#install.packages("pak")
pak::pak("tidyverse/googlesheets4")
```
## Cheatsheet
You can see how to read data with googlesheets4 in the **data import cheatsheet**, which also covers similar functionality in the related packages readr and readxl.
<a href="https://github.com/rstudio/cheatsheets/blob/master/data-import.pdf"><img src="https://raw.githubusercontent.com/rstudio/cheatsheets/master/pngs/thumbnails/data-import-cheatsheet-thumbs.png" width="630" height="252" alt="thumbnail of data import cheatsheet"/></a>
## Auth
googlesheets4 will, by default, help you interact with Sheets as an authenticated Google user. If you don't plan to write Sheets or to read private Sheets, use `gs4_deauth()` to indicate there is no need for a token. See the article [googlesheets4 auth](https://googlesheets4.tidyverse.org/articles/articles/auth.html) for more.
For this overview, we've logged into Google as a specific user in a hidden chunk.
## Attach googlesheets4
```{r}
library(googlesheets4)
```
## Read
The main "read" function of the googlesheets4 package goes by two names, because we want it to make sense in two contexts:
* `read_sheet()` evokes other table-reading functions, like
`readr::read_csv()` and `readxl::read_excel()`. The `sheet` in this case
refers to a Google (spread)Sheet.
* `range_read()` is the right name according to the
[naming convention](https://googlesheets4.tidyverse.org/articles/articles/function-class-names.html)
used throughout the googlesheets4 package.
`read_sheet()` and `range_read()` are synonyms and you can use either one. Here we'll use `read_sheet()`.
googlesheets4 is [pipe-friendly](https://r4ds.had.co.nz/pipes.html) (and reexports `%>%`), but works just fine without the pipe.
Read from
* a URL
* a Sheet ID
* a [`dribble`](https://googledrive.tidyverse.org/reference/dribble.html)
produced by the googledrive package, which can lookup by file name
These all achieve the same thing:
```{r}
# URL
read_sheet("https://docs.google.com/spreadsheets/d/1U6Cf_qEOhiR9AZqTqS3mbMF3zt2db48ZP5v3rkrAEJY/edit#gid=780868077")
# Sheet ID
read_sheet("1U6Cf_qEOhiR9AZqTqS3mbMF3zt2db48ZP5v3rkrAEJY")
# a googledrive "dribble"
googledrive::drive_get("gapminder") %>%
read_sheet()
```
*Note: the only reason we can read a sheet named "gapminder" (the last example) is because the account we're logged in as has a Sheet named "gapminder".*
See the article [Find and Identify Sheets](https://googlesheets4.tidyverse.org/articles/articles/find-identify-sheets.html) for more about specifying the Sheet you want to address. See the article [Read Sheets](https://googlesheets4.tidyverse.org/articles/articles/find-identify-sheets.html) for more about reading from specific sheets or ranges, setting column type, and getting low-level cell data.
## Write
`gs4_create()` creates a brand new Google Sheet and can optionally send some initial data.
```{r}
(ss <- gs4_create("fluffy-bunny", sheets = list(flowers = head(iris))))
```
`sheet_write()` (over)writes a whole data frame into a (work)sheet within a (spread)Sheet.
```{r}
head(mtcars) %>%
sheet_write(ss, sheet = "autos")
ss
```
`sheet_append()`, `range_write()`, `range_flood()`, and `range_clear()` are more
specialized writing functions. See the article [Write Sheets](https://googlesheets4.tidyverse.org/articles/articles/write-sheets.html) for more about writing to Sheets.
```{r include = FALSE}
googledrive::drive_trash(ss)
```
## Where to learn more
[Get started](https://googlesheets4.tidyverse.org/articles/googlesheets4.html) is a more extensive general introduction to googlesheets4.
Browse the [articles index](https://googlesheets4.tidyverse.org/articles/index.html) to find articles that cover various topics in more depth.
See the [function index](https://googlesheets4.tidyverse.org/reference/index.html) for an organized, exhaustive listing.
## Contributing
If you'd like to contribute to the development of googlesheets4, please read [these guidelines](https://googlesheets4.tidyverse.org/CONTRIBUTING.html).
Please note that the googlesheets4 project is released with a [Contributor Code of Conduct](https://googlesheets4.tidyverse.org/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.
## Privacy
[Privacy policy](https://www.tidyverse.org/google_privacy_policy)
## Context
googlesheets4 draws on and complements / emulates other packages in the tidyverse:
* [googlesheets](https://cran.r-project.org/package=googlesheets) is the package that googlesheets4 replaces. Main improvements in googlesheets4: (1) wraps the current, most modern Sheets API; (2) leaves all "whole file"
operations to googledrive; and (3) uses shared infrastructure for auth and more, from the gargle package. The v3 API wrapped by googlesheets is deprecated. [Starting in April/May 2020](https://workspace.google.com/blog/product-announcements/migrate-your-apps-use-latest-sheets-api),
features will gradually be disabled and it's anticipated the API will fully
shutdown in September 2020. At that point, the original googlesheets
package must be retired.
* [googledrive](https://googledrive.tidyverse.org) provides a fully-featured interface to the Google Drive API. Any "whole file" operations can be accomplished with googledrive: upload or download or update a spreadsheet, copy, rename, move, change permission, delete, etc. googledrive supports Team Drives.
* [readxl](https://readxl.tidyverse.org) is the tidyverse package for reading Excel files (xls or xlsx) into an R data frame. googlesheets4 takes cues from parts of the readxl interface, especially around specifying which cells to read.
* [readr](https://readr.tidyverse.org) is the tidyverse package for reading delimited files (e.g., csv or tsv) into an R data frame. googlesheets4 takes cues from readr with respect to column type specification.