sheets_id
is an S3 class that marks a string as a Google Sheet's id, which
the Sheets API docs refer to as spreadsheetId
.
Any object of class sheets_id
also has the drive_id
class, which is used by googledrive::googledrive for the same purpose. This means you
can provide a sheets_id
to googledrive::googledrive functions, in order to do anything
with your Sheet that has nothing to do with it being a spreadsheet. Examples:
change the Sheet's name, parent folder, or permissions. Read more about using
googlesheets4 and googledrive::googledrive together in vignette("drive-and-sheets")
.
Note that a sheets_id
object is intended to hold just one id, while the
parent class drive_id
can be used for multiple ids.
as_sheets_id()
is a generic function that converts various inputs into an
instance of sheets_id
. See more below.
When you print a sheets_id
, we attempt to reveal the Sheet's current
metadata, via gs4_get()
. This can fail for a variety of reasons (e.g. if
you're offline), but the input sheets_id
is always revealed and returned,
invisibly.
as_sheets_id()
These inputs can be converted to a sheets_id
:
Spreadsheet id, "a string containing letters, numbers, and some special characters", typically 44 characters long, in our experience. Example:
1qpyC0XzvTcKT6EISywvqESX3A0MwQoFDE8p-Bll4hps
.A URL, from which we can excavate a spreadsheet or file id. Example:
"https://docs.google.com/spreadsheets/d/1BzfL0kZUz1TsI5zxJF1WNF01IxvC67FbOJUiiGMZ_mQ/edit#gid=1150108545"
.A one-row
dribble
, a "Drive tibble" used by the googledrive::googledrive package. In general, adribble
can represent several files, one row per file. Since googlesheets4 is not vectorized over spreadsheets, we are only prepared to accept a one-rowdribble
.googledrive::drive_get("YOUR_SHEET_NAME")
is a great way to look up a Sheet via its name.gs4_find("YOUR_SHEET_NAME")
is another good way to get your hands on a Sheet.
Spreadsheet meta data, as returned by, e.g.,
gs4_get()
. Literally, this is an object of classgooglesheets4_spreadsheet
.
Examples
mini_gap_id <- gs4_example("mini-gap")
class(mini_gap_id)
#> [1] "sheets_id" "drive_id" "vctrs_vctr" "character"
mini_gap_id
#>
#> ── <googlesheets4_spreadsheet> ────────────────────────────────────────
#> Spreadsheet name: mini-gap
#> ID: 1k94ZVVl6sdj0AXfK9MQOuQ4rOhd1PULqpAu2_kr9MAU
#> Locale: en_US
#> Time zone: America/Los_Angeles
#> # of sheets: 5
#>
#> ── <sheets> ───────────────────────────────────────────────────────────
#> (Sheet name): (Nominal extent in rows x columns)
#> Africa: 6 x 6
#> Americas: 6 x 6
#> Asia: 6 x 6
#> Europe: 6 x 6
#> Oceania: 6 x 6
as_sheets_id("abc")
#>
#> ── <googlesheets4_spreadsheet> ────────────────────────────────────────
#> Spreadsheet name: "<unknown>"
#> ID: abc
#> Locale: <unknown>
#> Time zone: <unknown>
#> # of sheets: <unknown>
#>
#> Unable to get metadata for this Sheet. Error details:
#> Client error: (404) NOT_FOUND
#> • A specified resource is not found, or the request is rejected by
#> undisclosed reasons, such as whitelisting.
#> • Requested entity was not found.