Low-level function to execute a Sheets API 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_make(x, ..., encode = "json")List. Holds the components for an HTTP request, presumably created
with request_generate() or gargle::request_build(). Must contain a
method and url. If present, body and token are used.
Optional arguments passed through to the HTTP method.
If the body is a named list, how should it be encoded? This has
the same meaning as encode in all the httr::VERB()s, such as
httr::POST(). Note, however, that we default to encode = "json", which
is what you want most of the time when calling the Sheets API. The httr
default is "multipart". Other acceptable values are "form" and "raw".
Object of class response from httr.
make_request() is a very thin wrapper around gargle::request_retry(),
only adding the googlesheets4 user agent. Typically the input has been
created with request_generate() or gargle::request_build() and the output
is processed with process_response().
gargle::request_retry() retries requests that error with 429 RESOURCE_EXHAUSTED. Its basic scheme is exponential backoff, with one tweak
that is very specific to the Sheets API, which has documented usage limits:
"a limit of 500 requests per 100 seconds per project and 100 requests per 100 seconds per user"
Note that the "project" here means everyone using googlesheets4 who hasn't configured their own OAuth app. This is potentially a lot of users, all acting independently.
If you hit the "100 requests per 100 seconds per user" limit (which really does mean YOU), the first wait time is a bit more than 100 seconds, then we revert to exponential backoff.
If you experience lots of retries, especially with 100 second delays, it
means your use of googlesheets4 is more than casual and it's time for you
to get your own OAuth app or use a service account token. This is explained
in the gargle vignette vignette("get-api-credentials", package = "gargle").
Other low-level API functions:
gs4_has_token(),
gs4_token(),
request_generate()