googledrive (version 0.1.1)

generate_request: Build a request for the Google Drive v3 API

Description

Build a request, using some knowledge of the Drive v3 API. Most users should, instead, use higher-level wrappers that facilitate common tasks, such as uploading or downloading Drive files. The functions here are intended for internal use and for programming around the Drive API.

Usage

generate_request(endpoint = character(), params = list(), key = NULL,
  token = drive_token())
build_request(path = "", method, params = list(), body = list(),
  token = NULL)

Arguments

endpoint

Character. Nickname for one of the selected Drive v3 API endpoints built into googledrive. Learn more in drive_endpoints().

params

Named list. Parameters destined for endpoint URL substitution, the query, or, for generate_request() only, the body.

key

API key. Will be 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. In order of precedence, these sources are consulted: the formal key argument, a key parameter in params, a pre-configured API key fetched via drive_api_key(). googledrive ships with a built-in key or users can override with their own via drive_auth_config().

token

Drive token. Set to NULL to suppress the inclusion of a token. Note that, if auth has been de-activated via drive_auth_config(), drive_token() will actually return NULL.

path

Character, e.g., "drive/v3/files/{fileId}". It can include variables inside curly brackets, as the example does, which are substituted using named parameters found in the params argument.

method

Character, should match an HTTP verb, e.g., GET, POST, PATCH or PUT

body

List, values to pass to the API request body.

Value

list() Components are method, path, query, body, token, and url, suitable as input for make_request(). The path is post-substitution and the query is a named list of all the non-body params that were not used during this substitution. url is the full URL after prepending the base URL for the Drive v3 API and appending the query.

Details

There are two functions:

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

  • Uses the API spec to look up the path and method.

  • Checks params for validity and completeness with respect to the endpoint. Separates body parameters from those destined for path substitution or the query.

  • Adds an API key to the query if token = NULL. Or, at least, we try.

  • Adds supportsTeamDrives = TRUE to the query if the endpoint requires.

generate_request() then passes things along to build_request(). Use drive_endpoints() to see which endpoints can be accessed this way.

• build_request() builds a request from explicit parts. It is quite dumb, only doing URL endpoint substitution and URL formation. It's up to the caller to make sure the path, method, params, body, and token are valid. Use this to call a Drive API endpoint that doesn't appear in the list returned by drive_endpoints().

See Also

Other low-level API functions: drive_token, make_request, process_response

Examples

# NOT RUN {
req <- generate_request(
  "drive.files.get",
  list(fileId = "abc"),
  token = drive_token()
)
req
# }
# NOT RUN {
## re-create the previous request, but the hard way, i.e. "by hand"
req <- build_request(
  path = "drive/v3/files/{fileId}",
  method = "GET",
  list(fileId = "abc", key = "an-api-key"),
  token = NULL
)
req

## call an endpoint not used by googledrive
## List a file's comments
## https://developers.google.com/drive/v3/reference/comments/list
# }
# NOT RUN {
req <- build_request(
  path = "drive/v3/files/{fileId}/comments",
  method = "GET",
  params = list(
    fileId = "your-file-id-goes-here",
    fields = "*"
  ),
  token = drive_token()
)
process_response(make_request(req))
# }