本頁面由 Cloud Translation API 翻譯而成。

網站適用的 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 伺服器在使用者完成授權流程後，將使用者重新導向至哪個位置。這個值必須與 OAuth 2.0 用戶端的授權重新導向 URI 完全相符，也就是您在 API 控制台設定的值，且必須符合重新導向 URI 驗證規則。彈出式使用者體驗會忽略該屬性。
`callback`	彈出式視窗使用者體驗的必要元素。負責處理傳回程式碼回應的 JavaScript 函式。重新導向使用者介面會忽略該屬性。
`state`	選用設定。建議用於重新導向使用者體驗。指定應用程式用於在授權要求和授權伺服器回應之間維持狀態的任何字串值。
`enable_granular_consent`	已淘汰，設定後不會生效。如要進一步瞭解同意聲明行為，請參閱精細權限。
`enable_serial_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`	選用設定。這個 JavaScript 函式會處理某些非 OAuth 錯誤，例如彈出式視窗無法開啟，或是在傳回 OAuth 回應前關閉。輸入參數的 `type` 欄位會提供詳細原因。 popup_failed_to_open 無法開啟彈出式視窗。 popup_closed 在傳回 OAuth 回應前，彈出式視窗已關閉。 unknown：其他錯誤的預留位置。

資料類型：CodeClient

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

interface CodeClient {
  requestCode(): void;
}

資料類型：CodeResponse

彈出式使用者體驗中的 callback 方法會傳遞 CodeResponse JavaScript 物件。在重新導向使用者體驗中，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`	已淘汰，設定後不會生效。如要進一步瞭解同意聲明行為，請參閱精細權限。
`enable_serial_consent`	已淘汰，設定後不會生效。如要進一步瞭解同意聲明行為，請參閱精細權限。
`login_hint`	選用設定。如果應用程式知道應由哪位使用者授權要求，就可以使用這個屬性向 Google 提供登入提示。成功後，系統會略過帳戶選取程序。目標使用者的電子郵件地址或 ID 權杖 sub 欄位值。詳情請參閱 OpenID Connect 說明文件中的 `login_hint` 欄位。
`hd`	選用設定。如果您的應用程式知道使用者所屬的 Workspace 網域，請使用這項資訊向 Google 提供提示。成功後，使用者帳戶會受限於或預先選取提供的網域。詳情請參閱 OpenID Connect 說明文件中的 `hd` 欄位。
`state`	選用設定。不建議使用。指定應用程式用於在授權要求和授權伺服器回應之間維持狀態的任何字串值。
`error_callback`	選用設定。這個 JavaScript 函式會處理某些非 OAuth 錯誤，例如彈出式視窗無法開啟，或是在傳回 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`	已淘汰，設定後不會生效。如要進一步瞭解同意聲明行為，請參閱精細權限。
`enable_serial_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[]	選用設定。其他要檢查的範圍。

傳回
布林值	如果已授予所有範圍，則為 True。

方法：google.accounts.oauth2.hasGrantedAnyScope

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

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

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

傳回
布林值	如果已授予任何範圍，則為 True。

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