gargle v0.5.0
Monthly downloads
Utilities for Working with Google APIs
Provides utilities for working with Google APIs
<https://developers.google.com/apis-explorer>. This includes
functions and classes for handling common credential types and for
preparing, executing, and processing HTTP requests.
Readme
gargle
The goal of gargle is to take some of the agonizing pain out of working with Google APIs. This includes functions and classes for handling common credential types and for preparing, executing, and processing HTTP requests.
The target user of gargle is an R package author who is wrapping one of the ~250 Google APIs listed in the APIs Explorer. gargle aims to play roughly the same role as Google’s official client libraries, but for R. gargle may also be useful to useRs making direct calls to Google APIs, who are prepared to navigate the details of low-level API access.
gargle’s functionality falls into two main domains:
- Auth. The
token_fetch()
function calls a series of concrete credential-fetching functions to obtain a valid access token (or it quietly dies trying).- This covers explicit service accounts, application default credentials, Google Compute Engine, and the standard OAuth2 browser flow.
- gargle offers the
Gargle2.0
class, which extendshttr::Token2.0
. It is the default class for user OAuth 2.0 credentials. There are two main differences fromhttr::Token2.0
: greater emphasis on the user’s email (e.g. Google identity) and default token caching is at the user level.
- Requests and responses. A family of functions helps to prepare HTTP requests, (possibly with reference to an API spec derived from a Discovery Document), make requests, and process the response.
See the articles for holistic advice on how to use gargle.
Installation
You can install the released version of gargle from CRAN with:
install.packages("gargle")
And the development version from GitHub with:
# install.packages("devtools")
devtools::install_github("r-lib/gargle")
Basic usage
gargle is a low-level package and does not do anything visibly exciting on its own. But here’s a bit of usage in an interactive scenario where a user confirms they want to use a specific Google identity and loads an OAuth2 token.
library(gargle)
token <- token_fetch()
#> The gargle package is requesting access to your Google account. Select a
#> pre-authorised account or enter '0' to obtain a new token. Press
#> Esc/Ctrl + C to abort.
#> 1: janedoe_personal@gmail.com
#> 2: janedoe@example.com
#> Selection: 1
token
#> <Token (via gargle)>
#> <oauth_endpoint> google
#> <app> gargle-demo
#> <email> janedoe_personal@gmail.com
#> <scopes> ...userinfo.email
#> <credentials> access_token, expires_in, refresh_token, scope, ...
Here’s an example of using request and response helpers to make a one-off request to the Web Fonts Developer API. We show the most popular web font families served by Google Fonts.
library(gargle)
req <- request_build(
method = "GET",
path = "webfonts/v1/webfonts",
params = list(
sort = "popularity"
),
key = gargle_api_key(),
base_url = "https://www.googleapis.com"
)
resp <- request_make(req)
out <- response_process(resp)
out <- out[["items"]][1:8]
vapply(out, function(x) x[["family"]], character(1))
#> [1] "Roboto" "Open Sans" "Lato" "Montserrat"
#> [5] "Noto Sans JP" "Source Sans Pro" "Roboto Condensed" "Oswald"
Please note that the ‘gargle’ project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
Functions in gargle
Name | Description | |
field_mask | Generate a field mask | |
request_develop | Build a Google API request | |
oauth_app_from_json | Create an OAuth app from JSON | |
gargle-package | gargle: Utilities for Working with Google APIs | |
gargle2.0_token | Generate a gargle token | |
request_make | Make a Google API request | |
response_process | Process a Google API response | |
init_AuthState | Create an AuthState | |
gargle_oauth_sitrep | OAuth token situation report | |
internal-assets | Assets for internal use | |
gargle_options | Options consulted by gargle | |
token-info | Get info from a token | |
gargle_app | OAuth app for demonstration purposes | |
token_fetch | Fetch a token for the given scopes | |
gargle_api_key | API key for demonstration purposes | |
Gargle-class | OAuth2 token objects specific to Google APIs | |
GceToken | Token for use on Google Compute Engine instances | |
credentials_service_account | Load a service account token | |
AuthState-class | Authorization state | |
credentials_app_default | Load Application Default Credentials | |
credentials_user_oauth2 | Get an OAuth token for a user | |
cred_funs | Credential function registry | |
credentials_gce | Get a token for Google Compute Engine | |
credentials_byo_oauth2 | Load a user-provided token | |
No Results! |
Vignettes of gargle
Last month downloads
Details
License | MIT + file LICENSE |
URL | https://gargle.r-lib.org, https://github.com/r-lib/gargle |
BugReports | https://github.com/r-lib/gargle/issues |
VignetteBuilder | knitr |
Encoding | UTF-8 |
Language | en-US |
LazyData | true |
RoxygenNote | 7.1.0 |
NeedsCompilation | no |
Packaged | 2020-05-06 00:41:53 UTC; jenny |
Repository | CRAN |
Date/Publication | 2020-05-06 06:30:17 UTC |
suggests | covr , knitr , rmarkdown , sodium , spelling , testthat (>= 2.3.2) |
imports | fs (>= 1.3.1) , glue (>= 1.3.0) , httr (>= 1.4.0) , jsonlite , rlang (>= 0.4.2) , stats , withr |
depends | R (>= 3.2) |
Contributors | RStudio, Hadley Wickham, Google Inc, Craig Citro |
Include our badge in your README
[](http://www.rdocumentation.org/packages/gargle)