googlesheets (version 0.2.0)

googlesheet: Register a Google Sheet

Description

The googlesheets package must gather information on a Google Sheet from https://developers.google.com/google-apps/spreadsheets/{the API} prior to any requests to read or write data. We call this registering the sheet and store the result in a googlesheet object. Note this object does not contain any sheet data, but rather contains metadata about the sheet. We populate a googlesheet object with information from the https://developers.google.com/google-apps/spreadsheets/worksheets{worksheets feed} and, if available, also from the https://developers.google.com/google-apps/spreadsheets/worksheets#retrieve_a_list_of_spreadsheets{spreadsheets feed}. Choose from the functions below depending on the type of sheet-identifying input you will provide. Is it a sheet title, key, browser URL, or worksheets feed (another URL, mostly used internally)?

Usage

gs_title(x, verbose = TRUE)
gs_key(x, lookup = NULL, visibility = NULL, verbose = TRUE)
gs_url(x, lookup = NULL, visibility = NULL, verbose = TRUE)
gs_ws_feed(x, lookup = NULL, verbose = TRUE)
gs_gs(x, visibility = NULL, verbose = TRUE)

Arguments

x

sheet-identifying information; a character vector of length one holding sheet title, key, browser URL or worksheets feed OR, in the case of gs_gs only, a googlesheet object

verbose

logical; do you want informative messages?

lookup

logical, optional. Controls whether googlesheets will place authorized API requests during registration. If unspecified, will be set to TRUE if authorization has previously been used in this R session, if working directory contai

visibility

character, either "public" or "private". Consulted during explicit construction of a worksheets feed from a key, which happens only when lookup = FALSE and googlesheets is prevented from looking up information in the spreadsheets

Value

• a googlesheet object

Details

A registered googlesheet will contain information on:

• sheet_keythe key of the spreadsheet
• sheet_titlethe title of the spreadsheet
• n_wsthe number of worksheets contained in the spreadsheet
• ws_feedthe "worksheets feed" of the spreadsheet
• updatedthe time of last update (at time of registration)
• reg_datethe time of registration
• visibilityvisibility of spreadsheet (Google's confusing vocabulary); actually, does not describe a property of spreadsheet itself but rather whether requests will be made with or without authorization
• is_publiclogical indicating visibility is "public" (meaning unauthenticated requests will be sent), as opposed to "private" (meaning authenticated requests will be sent)
• authorthe name of the owner
• emailthe email of the owner
• linksdata.frame of links specific to the spreadsheet
• wsa data.frame about the worksheets contained in the spreadsheet

A googlesheet object will contain this information from the spreadsheets feed if it was available at the time of registration:

• alt_keyalternate key; applies only to "old" sheets

Since the spreadsheets feed contains private user data, googlesheets must be properly authorized to access it. So a googlesheet object will only contain info from the spreadsheets feed if lookup = TRUE, which directs us to look up sheet-identifying information in the spreadsheets feed.