gargle v0.1.3

0

Monthly downloads

0th

Percentile

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

Build
Status AppVeyor Build
Status codecov.io lifecycle

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 extends httr::Token2.0. It is the default class for user OAuth 2.0 credentials. There are two main differences from httr::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 Places API. We’ll find the restaurants in a certain part of Vancouver, BC.

library(gargle)

req <- request_build(
  method = "GET",
  path = "maps/api/place/nearbysearch/json",
  params = list(
    location = "49.268682,-123.167117",
    radius = 100,
    type = "restaurant"
  ),
  key = gargle_api_key(),
  base_url = "https://maps.googleapis.com"
)
resp <- request_make(req)
out <- response_process(resp)
vapply(out$results, function(x) x$name, character(1))
#> [1] "The Naam"                    "The Oakwood Canadian Bistro"
#> [3] "Healthy Noodle House"        "Tapatio Mexican Cafe & Bar" 
#> [5] "FreshFast"

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
response_process Process a Google API response
gargle_options Options consulted by gargle
gargle_oauth_sitrep OAuth token situation report
gargle_api_key API key for demonstration purposes
credentials_user_oauth2 Get an OAuth token for a user
gargle_app OAuth app for demonstration purposes
tidyverse_app OAuth app for tidyverse packages
tidyverse_api_key API key for tidyverse packages
token_fetch Fetch a token for the given scopes
oauth_app_from_json Create an OAuth app from JSON
init_AuthState Create an AuthState
request_make Make a Google API request
request_develop Build a Google API request
gargle-package gargle: Utilities for Working with Google APIs
Gargle-class OAuth2 token objects specific to Google APIs
credentials_app_default Load Application Default Credentials
AuthState-class Authorization state
cred_funs Credential function registry
credentials_service_account Load a service account token
gargle2.0_token Generate a gargle token
credentials_gce Get a token for Google Compute Engine
GceToken Token for use on Google Compute Engine instances
No Results!

Vignettes of gargle

Name
articles/managing-tokens-securely.Rmd
gargle-auth-in-client-package.Rmd
how-gargle-gets-tokens.Rmd
request-helper-functions.Rmd
No Results!

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
LazyData true
RoxygenNote 6.1.1
NeedsCompilation no
Packaged 2019-05-27 16:19:50 UTC; jenny
Repository CRAN
Date/Publication 2019-06-03 13:10:16 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/gargle)](http://www.rdocumentation.org/packages/gargle)