request_generate function

Generate a Google Sheets API request

Generate a request, using knowledge of the Sheets API from its Discovery Document (https://www.googleapis.com/discovery/v1/apis/sheets/v4/rest). Use request_make() to execute the request. Most users should, instead, use higher-level wrappers that facilitate common tasks, such as reading or writing worksheets or cell ranges. The functions here are intended for internal use and for programming around the Sheets API.

request_generate() lets you provide the bare minimum of input. It takes a nickname for an endpoint and:

• Uses the API spec to look up the method, path, and base_url.
• Checks params for validity and completeness with respect to the endpoint. Uses params for URL endpoint substitution and separates remaining parameters into those destined for the body versus the query.
• Adds an API key to the query if and only if token = NULL.

request_generate(
  endpoint = character(),
  params = list(),
  key = NULL,
  token = gs4_token()
)

Arguments

• endpoint: Character. Nickname for one of the selected Sheets API v4 endpoints built into googlesheets4. Learn more in gs4_endpoints().

• params: Named list. Parameters destined for endpoint URL substitution, the query, or the body.

• key: API key. Needed for requests that don't contain a token. The need for an API key in the absence of a token is explained in Google's document "Credentials, access, security, and identity" (https://support.google.com/googleapi/answer/6158857?hl=en&ref_topic=7013279). In order of precedence, these sources are consulted: the formal key

  argument, a key parameter in params, a user-configured API key set up with gs4_auth_configure() and retrieved with gs4_api_key().

• token: Set this to NULL to suppress the inclusion of a token. Note that, if auth has been de-activated via gs4_deauth(), gs4_token() will actually return NULL.

Returns

list()

Components are method, url, body, and token, suitable as input for request_make().

Examples

req <- request_generate(
  "sheets.spreadsheets.get",
  list(spreadsheetId = gs4_example("deaths")),
  key = "PRETEND_I_AM_AN_API_KEY",
  token = NULL
)
req

See Also

gargle::request_develop(), gargle::request_build(), gargle::request_make()

Other low-level API functions: gs4_has_token(), gs4_token(), request_make()