本頁面由 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`，且授權要求獲得核准，則新的存取權杖只會涵蓋這個 `CodeClientConfig` 中要求的 `scope` 範圍。
`redirect_uri`	重新導向使用者體驗需要這項資訊。決定 API 伺服器在使用者完成授權流程後，將使用者重新導向至哪個網址。這個值必須與 OAuth 2.0 用戶端的其中一個授權重新導向 URI 完全相符 (您在 API 控制台中設定)，且必須符合我們的重新導向 URI 驗證規則。彈出式視窗 UX 會忽略這項屬性。
`callback`	這是彈出式視窗使用者體驗的必要條件。負責處理傳回程式碼回應的 JavaScript 函式。重新導向 UX 會忽略這項屬性。
`state`	(選用步驟) 建議用於重新導向的使用者體驗。指定應用程式用來維護授權要求與授權伺服器回應之間狀態的任何字串值。
`enable_granular_consent`	已淘汰，設定後不會生效。如要瞭解同意聲明行為的詳細資料，請參閱精細權限。
`enable_serial_consent`	已淘汰，設定後不會生效。如要瞭解同意聲明行為的詳細資料，請參閱精細權限。
`login_hint`	(選用步驟) 如果應用程式知道應由哪位使用者授權要求，就可以使用這項屬性向 Google 提供登入提示。成功後，系統會略過帳戶選取畫面。目標使用者的電子郵件地址或 ID 權杖 sub 欄位值。詳情請參閱 OpenID Connect 說明文件中的 `login_hint` 欄位。
`hd`	(選用步驟) 如果應用程式知道使用者所屬的 Workspace 網域，請使用這項資訊向 Google 提供提示。成功後，使用者帳戶會限制或預先選取提供的網域。詳情請參閱 OpenID Connect 說明文件中的 `hd` 欄位。
`ux_mode`	(選用步驟) 授權流程要使用的 UX 模式。根據預設，系統會在彈出式視窗中開啟同意聲明流程。有效值為 `popup` 和 `redirect`。
`select_account`	選用，預設值為 'false'。布林值，用於提示使用者選取帳戶。
`error_callback`	(選用步驟) 處理部分非 OAuth 錯誤的 JavaScript 函式，例如無法開啟彈出式視窗；或在傳回 OAuth 回應前關閉視窗。輸入參數的 `type` 欄位會提供詳細原因。 popup_failed_to_open：無法開啟彈出式視窗。 popup_closed：彈出式視窗在傳回 OAuth 回應前關閉。 unknown 其他錯誤的預留位置。

資料類型：CodeClient

這個類別只有一個公開方法 requestCode，可啟動 OAuth 2.0 程式碼 UX 流程。

interface CodeClient {
  requestCode(): void;
}

資料類型：CodeResponse

系統會在彈出式視窗 UX 中，將 CodeResponse JavaScript 物件傳遞至 callback 方法。在重新導向 UX 中，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`，且授權要求獲得核准，則新的存取權杖只會涵蓋這個 `TokenClientConfig` 中要求的 `scope` 範圍。
`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`	(選用步驟) 處理部分非 OAuth 錯誤的 JavaScript 函式，例如無法開啟彈出式視窗；或在傳回 OAuth 回應前關閉視窗。輸入參數的 `type` 欄位會提供詳細原因。 popup_failed_to_open：無法開啟彈出式視窗。 popup_closed：彈出式視窗在傳回 OAuth 回應前關閉。 unknown 其他錯誤的預留位置。

資料類型：TokenClient

這個類別只有一個公開方法 requestAccessToken，可啟動 OAuth 2.0 權杖 UX 流程。

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

引數
`overrideConfig`	OverridableTokenClientConfig	(選用步驟) 這個方法中要覆寫的設定。

資料類型：OverridableTokenClientConfig

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

屬性
`scope`	(選用步驟) 以空格分隔的範圍清單，可識別應用程式代表使用者存取的資源。這些值會提供資訊給 Google 向使用者顯示的同意畫面。
`include_granted_scopes`	選用，預設值為 `true`。允許應用程式使用漸進式授權，在相關情境中要求存取其他範圍。如果將這個參數的值設為 `false`，且授權要求獲得核准，則新的存取權杖只會涵蓋這個 `OverridableTokenClientConfig` 中要求的 `scope` 範圍。
`prompt`	(選用步驟) 以半形空格分隔的提示清單 (區分大小寫)，供使用者參考。
`enable_granular_consent`	已淘汰，設定後不會生效。如要瞭解同意聲明行為的詳細資料，請參閱精細權限。
`enable_serial_consent`	已淘汰，設定後不會生效。如要瞭解同意聲明行為的詳細資料，請參閱精細權限。
`login_hint`	(選用步驟) 如果應用程式知道應由哪位使用者授權要求，就可以使用這項屬性向 Google 提供登入提示。成功後，系統會略過帳戶選取畫面。目標使用者的電子郵件地址或 ID 權杖 sub 欄位值。詳情請參閱 OpenID Connect 說明文件中的 `login_hint` 欄位。
`state`	(選用步驟) 不建議採用。指定應用程式用來維護授權要求與授權伺服器回應之間狀態的任何字串值。

資料類型：TokenResponse

系統會在彈出式視窗 UX 中，將 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`	string	必要。有效的存取權杖。
`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` - 權杖無法撤銷。

Google 帳戶授權 JavaScript API 參考資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。