網站適用的 Google 第三方授權 JavaScript 程式庫 - API 參考資料

這份參考資料說明 Google 第三方授權 JavaScript Library API，這個憑證可用來載入 Google 提供的授權碼或存取權杖

方法：google.accounts.oauth2.initCodeClient

initCodeClient 方法會初始化並傳回程式碼用戶端，設定 kubectl

google.accounts.oauth2.initCodeClient(config: CodeClientConfig)

資料類型：CodeClientConfig

下表列出 CodeClientConfig 資料類型的屬性。

屬性
`client_id`	必要。應用程式的用戶端 ID。您可以在 API 控制台中找到這個值。
`scope`	必要。以空格分隔的範圍清單，這些範圍可識別應用程式可代表使用者存取的資源。這些值決定 Google 向使用者顯示的同意畫面。
`include_granted_scopes`	選用，預設為 `true`。讓應用程式使用漸進式可在相關情境中要求其他範圍的存取權。如果您為將此參數值設為 `false`，並授予授權要求，然後新的存取權杖只會涵蓋 `scope` 要求的任何範圍於`CodeClientConfig`中。
`redirect_uri`	需要重新導向使用者體驗。決定使用者完成授權流程後，API 伺服器將使用者重新導向的目的地。這個值必須與 OAuth 2.0 用戶端的授權重新導向 URI 完全相符 (您在 API 控制台中設定)，且必須符合我們的重新導向 URI 驗證規則。彈出式視窗 UX 將忽略這個屬性。
`callback`	彈出式視窗使用者體驗的必要項目。處理傳回程式碼回應的 JavaScript 函式。重新導向的使用者體驗會忽略這個屬性。
`state`	選用設定。建議用於重新導向使用者體驗。指定應用程式用來維護授權要求與授權伺服器回應之間狀態的任何字串值。
`enable_granular_consent`	選用，預設為 `true`。如果設為「`false`」，請提供更精細的 Google 帳戶權限 OAuth 用戶端 ID 在 2019 年之前建立的如果 `enable_granular_consent` 和 `enable_serial_consent` 皆已設定，則只有 `enable_granular_consent` 值就會生效，並忽略 `enable_serial_consent` 值。較新的 OAuth 用戶端 ID 則不會有任何作用，因為系統一律會啟用更精細的權限。
`enable_serial_consent`	已淘汰，請改用 `enable_granular_consent`。這個效果與 `enable_granular_consent` 相同。現有應用程式使用 `enable_serial_consent` 仍可繼續運作，但建議您更新程式碼，在以下位置使用 `enable_granular_consent`：以便進行後續的應用程式更新
`login_hint`	選用設定。如果應用程式知道應授權要求的使用者，則可以使用此屬性為 Google 提供登入提示。成功後，系統會略過帳戶選取作業。目標使用者的電子郵件地址或 ID 權杖 sub 欄位值。詳情請參閱 OpenID Connect 說明文件中的 `login_hint` 欄位。
`hd`	選用設定。如果應用程式知道使用者所屬的 Workspace 網域，請使用這個選項向 Google 提供提示。如果成功設定，使用者帳戶只能使用提供的網域，或是已為指定網域預先選取。詳情請參閱 OpenID Connect 說明文件中的 `hd` 欄位。
`ux_mode`	選用設定。用於授權流程的使用者體驗模式。根據預設，系統預設會以彈出式視窗開啟同意聲明流程。有效值為 `popup` 和 `redirect`。
`select_account`	選用，預設為 'false'。用來提示使用者選取帳戶的布林值。
`error_callback`	選用設定。可處理部分非 OAuth 錯誤的 JavaScript 函式，例如無法開啟彈出式視窗；或在 OAuth 回應前關閉。輸入參數的 `type` 欄位會提供詳細原因。 popup_failed_to_open 無法開啟彈出式視窗。 popup_closed：在 OAuth 執行前關閉彈出式視窗回應。 unknown 其他錯誤的預留位置。

資料類型：CodeClient

該類別只有一個公開方法 requestCode，用來啟動 OAuth 2.0 程式碼使用者體驗流程。

interface CodeClient {
  requestCode(): void;
}

資料類型：CodeResponse

CodeResponse JavaScript 物件將傳遞至以下程式碼：callback 彈出式視窗的使用者體驗在重新導向使用者體驗中，CodeResponse 會以網址的形式傳遞參數。

下表列出 CodeResponse 資料類型的屬性。

屬性
`code`	成功權杖回應的授權碼。
`scope`	使用者核准以空格分隔的範圍清單。
`state`	應用程式用來維持授權要求與回應之間狀態的字串值。
`error`	單一 ASCII 錯誤代碼。
`error_description`	提供額外資訊的人類可讀 ASCII 文字，用於協助用戶端開發人員瞭解發生的錯誤。
`error_uri`	這個 URI 可用來識別人類可讀的網頁以及錯誤相關資訊。這個 URI 會用來為用戶端開發人員提供與錯誤有關的額外資訊。

方法：google.accounts.oauth2.initTokenClient

initTokenClient 方法會初始化並傳回權杖用戶端，設定 kubectl

google.accounts.oauth2.initTokenClient(config: TokenClientConfig)

資料類型：TokenClientConfig

下表列出 TokenClientConfig 資料類型的屬性。

屬性
`client_id`	必要。應用程式的用戶端 ID。您可以在 API 控制台中找到這個值。
`callback`	必要。處理傳回的權杖回應的 JavaScript 函式。
`scope`	必要。以空格分隔的範圍清單，這些範圍可識別應用程式可代表使用者存取的資源。這些值決定 Google 向使用者顯示的同意畫面。
`include_granted_scopes`	選用，預設為 `true`。讓應用程式使用漸進式可在相關情境中要求其他範圍的存取權。如果您為將此參數值設為 `false`，並授予授權要求，然後新的存取權杖只會涵蓋 `scope` 要求的任何範圍於`TokenClientConfig`中。
`prompt`	選用，預設為 'select_account'。以空格分隔向使用者顯示的提示清單 (區分大小寫)。可能的值包括：空白字串：系統只會在應用程式首次要求存取權時提示使用者。無法使用其他值指定。 'none'：不要顯示任何驗證或同意畫面。不得使用其他值指定。 'consent'：提示使用者表示同意。 'select_account' 提示使用者選取帳戶。
`enable_granular_consent`	選用，預設為 `true`。如果設為「`false`」，請提供更精細的 Google 帳戶權限 OAuth 用戶端 ID 在 2019 年之前建立的如果 `enable_granular_consent` 和 `enable_serial_consent` 皆已設定，則只有 `enable_granular_consent` 值就會生效，並忽略 `enable_serial_consent` 值。較新的 OAuth 用戶端 ID 則不會有任何作用，因為系統一律會啟用更精細的權限。
`enable_serial_consent`	已淘汰，請改用 `enable_granular_consent`。這個效果與 `enable_granular_consent` 相同。現有應用程式使用 `enable_serial_consent` 仍可繼續運作，但建議您更新程式碼，在以下位置使用 `enable_granular_consent`：以便進行後續的應用程式更新
`login_hint`	選用設定。如果應用程式知道應授權要求的使用者，則可以使用此屬性為 Google 提供登入提示。成功後，系統會略過帳戶選取作業。目標使用者的電子郵件地址或 ID 權杖 sub 欄位值。詳情請參閱 OpenID Connect 說明文件中的 `login_hint` 欄位。
`hd`	選用設定。如果應用程式知道使用者所屬的 Workspace 網域，請使用這個選項向 Google 提供提示。如果成功設定，使用者帳戶只能使用提供的網域，或是已為指定網域預先選取。詳情請參閱 OpenID Connect 說明文件中的 `hd` 欄位。
`state`	選用設定。不建議。指定應用程式用來維護授權要求與授權伺服器回應之間狀態的任何字串值。
`error_callback`	選用設定。可處理部分非 OAuth 錯誤的 JavaScript 函式，例如無法開啟彈出式視窗；或在 OAuth 回應前關閉。輸入參數的 `type` 欄位會提供詳細原因。 popup_failed_to_open 無法開啟彈出式視窗。 popup_closed：在 OAuth 執行前關閉彈出式視窗回應。 unknown 其他錯誤的預留位置。

資料類型：TokenClient

類別只有一個公開方法 requestAccessToken，用來啟動 OAuth 2.0 權杖使用者體驗流程。

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}

引數
`overrideConfig`	OverridableTokenClientConfig	選用設定。在這個方法中要覆寫的設定。

資料類型：OverridableTokenClientConfig

下表列出 OverridableTokenClientConfig 的屬性以及資料類型

屬性
`scope`	選用設定。以空格分隔的範圍清單，這些範圍會識別資源您的應用程式可以代表使用者存取這些值告知 Google 向使用者顯示的同意畫面。
`include_granted_scopes`	選用，預設為 `true`。讓應用程式使用漸進式可在相關情境中要求其他範圍的存取權。如果您為將此參數值設為 `false`，並授予授權要求，然後新的存取權杖只會涵蓋 `scope` 要求的任何範圍於`OverridableTokenClientConfig`中。
`prompt`	選用設定。以空格分隔且區分大小寫的提示清單，用於向使用者顯示。
`enable_granular_consent`	選用，預設為 `true`。如果設為「`false`」，請提供更精細的 Google 帳戶權限設為 2019 年之前建立的 OAuth 用戶端 ID 將會停用。如果同時設定 `enable_granular_consent` 和 `enable_serial_consent`，請只設定 `enable_granular_consent` 值就會生效，並忽略 `enable_serial_consent` 值。較新的 OAuth 用戶端 ID 則不會有任何作用，因為系統一律會啟用更精細的權限。
`enable_serial_consent`	已淘汰，請改用 `enable_granular_consent`。這個效果與 `enable_granular_consent` 相同。現有應用程式使用 `enable_serial_consent` 仍可繼續運作，但建議您更新程式碼，在以下位置使用 `enable_granular_consent`：以便進行後續的應用程式更新
`login_hint`	選用設定。如果應用程式知道應授權要求的使用者，則可以使用此屬性為 Google 提供登入提示。成功後，系統會略過帳戶選取作業。目標使用者的電子郵件地址或 ID 權杖 sub 欄位值。詳情請參閱 OpenID Connect 說明文件中的 `login_hint` 欄位。
`state`	選用設定。不建議。指定應用程式用來維護授權要求與授權伺服器回應之間狀態的任何字串值。

資料類型：TokenResponse

TokenResponse JavaScript 物件將傳遞至以下程式碼中的回呼方法：彈出式視窗的使用者體驗

下表列出 TokenResponse 資料類型的屬性。

屬性
`access_token`	成功權杖回應的存取權杖。
`expires_in`	存取權杖的生命週期 (以秒為單位)。
`hd`	登入使用者所屬的代管網域。
`prompt`	從 TokenClientConfig 或 OverridableTokenClientConfig 指定值清單中使用的提示值。
`token_type`	核發權杖的類型。
`scope`	使用者核准以空格分隔的範圍清單。
`state`	應用程式用來維持授權要求與回應之間狀態的字串值。
`error`	單一 ASCII 錯誤代碼。
`error_description`	提供額外資訊的人類可讀 ASCII 文字，用於協助用戶端開發人員瞭解發生的錯誤。
`error_uri`	這個 URI 可用來識別人類可讀的網頁以及錯誤相關資訊。這個 URI 會用來為用戶端開發人員提供與錯誤有關的額外資訊。

方法：google.accounts.oauth2.hasGrantedAllScopes

檢查使用者是否授予所有指定範圍或範圍。

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;

引數
`tokenResponse`	`TokenResponse`	必要。`TokenResponse` 物件。
`firstScope`	字串	必要。要檢查的範圍。
`restScopes`	string[]	選用設定。其他要檢查的範圍。

傳回
布林值	若所有範圍皆已授權，則為「是」。

方法：google.accounts.oauth2.hasGrantedAnyScope

檢查使用者是否授予任何指定範圍或範圍。

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;

引數
`tokenResponse`	`TokenResponse`	必要。`TokenResponse` 物件。
`firstScope`	字串	必要。要檢查的範圍。
`restScopes`	string[]	選用設定。其他要檢查的範圍。

傳回
布林值	如果已授權任何範圍，則為「是」。

方法：google.accounts.oauth2.revoke

revoke 方法會撤銷使用者授予應用程式的所有範圍。您必須具備有效的存取權杖才能撤銷權限。

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;

引數
`accessToken`	字串	必要。有效的存取權杖。
`callback`	函式	選用設定。RevocationResponse 處理常式。

資料類型：RevocationResponse

系統會將 RevocationResponse JavaScript 物件傳遞至您的回呼方法。

下表列出 RevocationResponse 資料類型的屬性。

屬性
`successful`	布林值。`true` 成功時，失敗時為 `false`。
`error`	字串。未定義成功。單一 ASCII 錯誤代碼。這類情況包括但不限於標準 OAuth 2.0 錯誤代碼。`revoke` 方法的常見錯誤： `invalid_token` - 在呼叫 `revoke` 方法之前，權杖已過期或撤銷。在大多數情況下，您可以已撤銷`accessToken`。 `invalid_request` - 符記無法撤銷。建議您確保 `accessToken` 是有效的 Google OAuth 2.0 憑證。
`error_description`	字串。未定義成功。人類可讀的 ASCII 文字提供關於 `error` 屬性。開發人員可以運用這項資訊發生的錯誤。`error_description` 字串僅提供英文版。以下是 `error` 中列出的常見錯誤：對應的 `error_description`： `invalid_token` - 權杖已過期或撤銷， `invalid_request` - 符記無法撤銷。