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

本參考資料說明 Google 第三方授權 JavaScript 程式庫 API，可用來從 Google 載入授權碼或存取權杖。

方法：google.accounts.oauth2.initCodeClient

initCodeClient 方法會使用參數中的設定來初始化並傳回程式碼用戶端。

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

資料類型：CodeClientConfig

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

屬性
`client_id`	必要。應用程式的用戶端 ID。您可以在 API 控制台中找到這個值。
`scope`	必要。以空格分隔的範圍清單，用於識別應用程式可代表使用者存取的資源。這些值會指示 Google 向使用者顯示的同意畫面。
`include_granted_scopes`	選用，預設為 `true`。可讓應用程式使用漸進式授權，在相關情境中要求存取其他範圍。如果您將此參數值設為 `false`，且系統已獲授權要求，則新的存取權杖只會涵蓋 `scope` 在這個 `CodeClientConfig` 中要求的所有範圍。
`redirect_uri`	必須提供重新導向使用者體驗。決定使用者完成授權流程後，API 伺服器會將使用者重新導向的位置。這個值必須與您在 API 控制台中設定的 OAuth 2.0 用戶端的其中一個已授權重新導向 URI 完全相符，且必須符合我們的重新導向 URI 驗證規則。彈出式視窗使用者體驗會忽略該屬性。
`callback`	必填。處理傳回程式碼回應的 JavaScript 函式。重新導向使用者體驗會忽略該屬性。
`state`	選用設定。建議用於重新導向使用者體驗。指定應用程式用來維持授權要求和授權伺服器回應之間狀態的任何字串值。
`enable_granular_consent`	選用，預設為 `true`。如果設為「`false`」，2019 年之前建立的 OAuth 用戶端 ID 就會停用更精細的 Google 帳戶權限。如果同時設定 `enable_granular_consent` 和 `enable_serial_consent`，系統只會套用 `enable_granular_consent` 值，並忽略 `enable_serial_consent` 值。不適用於較新的 OAuth 用戶端 ID，因為系統一律會為較新的 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 回應前，彈出式視窗會關閉。未知的預留位置。

資料類型：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 用於識別人類可讀且含有錯誤相關資訊的網頁，用來為用戶端開發人員提供該錯誤的其他相關資訊。

方法：google.accounts.oauth2.initTokenClient

initTokenClient 方法會使用參數中的設定來初始化並傳回權杖用戶端。

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`」，2019 年之前建立的 OAuth 用戶端 ID 就會停用更精細的 Google 帳戶權限。如果同時設定 `enable_granular_consent` 和 `enable_serial_consent`，系統只會套用 `enable_granular_consent` 值，並忽略 `enable_serial_consent` 值。不適用於較新的 OAuth 用戶端 ID，因為系統一律會為較新的 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 回應前，彈出式視窗會關閉。未知的預留位置。

資料類型：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`，系統會為 2019 年之前建立的 OAuth 用戶端 ID 停用更精細的 Google 帳戶權限。如果同時設定 `enable_granular_consent` 和 `enable_serial_consent`，則系統只會套用 `enable_granular_consent` 值，並忽略 `enable_serial_consent` 值。不適用於較新的 OAuth 用戶端 ID，因為系統一律會為較新的 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 用於識別人類可讀且含有錯誤相關資訊的網頁，用來為用戶端開發人員提供該錯誤的其他相關資訊。

方法：google.accounts.oauth2.hasGrantedAllScopes

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

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

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

傳回
boolean	如果授予所有範圍，則為「是」。

方法：google.accounts.oauth2.hasGrantedAnyScope

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

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

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

傳回
boolean	如果已授予任何範圍，則為「是」。

方法：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` - 無法撤銷權杖。