R googlesheets4 gs4_auth 授权 googlesheets4

授权 googlesheets4 查看和管理您的 Google 表格。该函数是 gargle::token_fetch() 的包装器。

默认情况下，您将被定向到网络浏览器，要求登录您的 Google 帐户，并授予 googlesheets4 代表您使用 Google 表格进行操作的权限。默认情况下，经过您的许可，这些用户凭据会缓存在您的主目录下的文件夹中，可以根据需要自动刷新它们。用户级别的存储意味着同一个代币可以在多个项目中使用，并且代币不太可能意外同步到云端。

用法

gs4_auth(
  email = gargle::gargle_oauth_email(),
  path = NULL,
  subject = NULL,
  scopes = "spreadsheets",
  cache = gargle::gargle_oauth_cache(),
  use_oob = gargle::gargle_oob_default(),
  token = NULL
)

参数

email

可选的。如果指定，email 可以采用几种不同的形式：

• "jane@gmail.com" ，即实际的电子邮件地址。这允许用户定位特定的 Google 身份。如果指定，则用于令牌查找，即确定缓存中是否已存在合适的令牌。如果未找到此类令牌，则使用 email 在 OAuth 选择器中预先选择目标 Google 身份。 (但是请注意，缓存时与令牌关联的电子邮件始终是根据令牌本身确定的，而不是根据此参数确定的)。

• "*@example.com" ，即 domain-only 全局模式。如果您需要 alice@example.com 和 bob@example.com 的代码 "just works" ，这会很有帮助。

• TRUE 表示您正在批准电子邮件自动发现。如果在缓存中恰好找到一个匹配的令牌，则将使用该令牌。

• FALSE 或 NA 表示您想要忽略令牌缓存并在浏览器中强制执行新的 OAuth 舞蹈。

默认为名为 "gargle_oauth_email" 的选项，由 gargle_oauth_email() 检索(除非包装程序包实现不同的默认行为)。

path

标识服务帐户的 JSON，采用 jsonlite::fromJSON() 的 txt 参数支持的形式之一(通常是文件路径或 JSON 字符串)。

subject

可选主题声明。如果您希望使用 path 表示的服务帐户来模拟 subject(普通用户)，请指定此项。在此之前，管理员必须向服务帐户授予域范围的权限。通过电子邮件识别要冒充的用户，例如subject = "user@example.com" 。请注意，gargle 会自动添加非敏感 "https://www.googleapis.com/auth/userinfo.email" 范围，因此必须为服务帐户启用此范围以及所请求的任何其他 scopes。

scopes

一个或多个 API 范围。每个范围都可以完整指定，或者对于工作表 API-specific 范围，以 gs4_scopes() 识别的缩写形式指定：

• "spreadsheets" =“https://www.googleapis.com/auth/spreadsheets”(默认值)

• "spreadsheets.readonly" = "https://www.googleapis.com/auth/spreadsheets.readonly"

• "drive" = "https://www.googleapis.com/auth/drive"

• "drive.readonly" = "https://www.googleapis.com/auth/drive.readonly"

• "drive.file" = "https://www.googleapis.com/auth/drive.file"

参看https://developers.google.com/identity/protocols/oauth2/scopes#sheets有关每个范围的权限的详细信息。

cache

指定 OAuth 令牌缓存。默认为名为 "gargle_oauth_cache" 的选项，通过 gargle_oauth_cache() 检索。

use_oob

首次获取令牌时是否使用带外身份验证(或者可能是由 gargle 实现的变体，称为 "pseudo-OOB")。默认为 gargle_oob_default() 返回的值。请注意，(伪)OOB 身份验证仅影响初始 OAuth 舞蹈。如果我们检索(并可能刷新)缓存的令牌，use_oob 不起作用。

如果 OAuth 客户端由包装器包隐式提供，则其类型可能默认为 gargle_oauth_client_type() 返回的值。您可以通过设置 options(gargle_oauth_client_type = "web") 或 options(gargle_oauth_client_type = "installed") 来控制客户端类型。

token

具有类 Token2.0 的令牌或 httr 类 request 的对象，即已使用 httr::config() 准备的令牌，并且在 auth_token 组件中具有 Token2.0。

细节

大多数用户在大多数情况下不需要显式调用gs4_auth()——它是由第一个需要授权的操作触发的。即使被调用，默认参数通常就足够了。

但是，必要时，gs4_auth() 允许用户显式：

• 通过 email 规范声明要使用的 Google 身份。

• 通过 path 使用服务帐户令牌或工作负载身份联合。

• 带上你自己的token。

• 自定义scopes。

• 使用非默认 cache 文件夹或关闭缓存。

• 通过 use_oob 显式请求出界 (OOB) 身份验证。

如果您在浏览器中与 R 交互(适用于 RStudio Server、Posit Workbench、Posit Cloud 和 Google Colaboratory)，则需要 OOB 身份验证或 pseudo-OOB 变体。如果这不会自动发生，您可以使用 use_oob = TRUE 显式请求，或者更持久地通过 options(gargle_oob_default = TRUE) 设置选项。

传统 OOB 或 pseudo-OOB 身份验证之间的选择取决于 OAuth 客户端的类型。如果客户端属于 "installed" 类型，则 use_oob = TRUE 会导致传统 OOB 身份验证。如果客户端属于 "web" 类型，则 use_oob = TRUE 会导致 pseudo-OOB auth。提供内置 OAuth 客户端的包通常可以检测要使用的客户端类型。但如果您需要明确设置，请使用"gargle_oauth_client_type"选项：

options(gargle_oauth_client_type = "web")       # pseudo-OOB
# or, alternatively
options(gargle_oauth_client_type = "installed") # conventional OOB

有关查找令牌的多种方法的详细信息，请参阅 gargle::token_fetch() 。要更深入地控制身份验证，请使用 gs4_auth_configure() 引入您自己的 OAuth 客户端或 API key 。要了解有关漱口选项的更多信息，请参阅gargle::gargle_options。

也可以看看

例子

if (FALSE) { # rlang::is_interactive()
# load/refresh existing credentials, if available
# otherwise, go to browser for authentication and authorization
gs4_auth()

# indicate the specific identity you want to auth as
gs4_auth(email = "jenny@example.com")

# force a new browser dance, i.e. don't even try to use existing user
# credentials
gs4_auth(email = NA)

# use a 'read only' scope, so it's impossible to edit or delete Sheets
gs4_auth(scopes = "spreadsheets.readonly")

# use a service account token
gs4_auth(path = "foofy-83ee9e7c9c48.json")
}