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")
}