此页面由 Cloud Translation API 翻译。

适用于网站的 Google 第三方授权 JavaScript 库 - API 参考文档

本参考文档介绍了 Google 第三方 JavaScript JavaScript Library API，该 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 且必须符合我们的重定向 URI 验证规则。该属性会被弹出式用户体验忽略。
`callback`	对于弹出式用户体验而言是必需的。用于处理返回的代码响应的 JavaScript 函数。重定向用户体验会忽略此属性。
`state`	（可选）建议用于重定向用户体验。指定您的应用用于维护授权请求与授权服务器响应之间的状态的任何字符串值。
`enable_serial_consent`	可选，默认为 `true`。如果此政策设为 `false`，系统会为 2019 年之前创建的 OAuth 客户端 ID 停用更精细的 Google 帐号权限。对较新的 OAuth 客户端 ID 没有影响，因为始终会为它们启用更精细的权限。
`hint`	（可选）如果您的应用知道应由哪个用户授权请求，则可使用此属性向 Google 提供提示。目标用户的电子邮件地址。如需了解详情，请参阅 OpenID Connect 文档中的 `login_hint` 字段。
`hosted_domain`	（可选）如果您的应用知道用户所属的 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，用于识别用户可理解的网页，其中包含有关错误的信息，用于为客户端开发者提供有关该错误的更多信息。

方法：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_serial_consent`	可选，默认为 `true`。如果此政策设为 `false`，系统会为 2019 年之前创建的 OAuth 客户端 ID 停用更精细的 Google 帐号权限。对较新的 OAuth 客户端 ID 没有影响，因为始终会为它们启用更精细的权限。
`hint`	（可选）如果您的应用知道应由哪个用户授权请求，则可使用此属性向 Google 提供提示。目标用户的电子邮件地址。如需了解详情，请参阅 OpenID Connect 文档中的 `login_hint` 字段。
`hosted_domain`	（可选）如果您的应用知道用户所属的 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_serial_consent`	可选，默认为 `true`。如果此政策设为 `false`，系统会为 2019 年之前创建的 OAuth 客户端 ID 停用更精细的 Google 帐号权限。对较新的 OAuth 客户端 ID 没有影响，因为始终会为它们启用更精细的权限。
`hint`	（可选）如果您的应用知道应由哪个用户授权请求，则可使用此属性向 Google 提供提示。目标用户的电子邮件地址。如需了解详情，请参阅 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`	字符串[]	（可选）要检查的其他范围。

返回
布尔值	如果所有范围都被授予，则返回 true。

方法：google.accounts.oauth2.hasGrantedAnyScope

检查用户是否已授予任何一个或多个指定范围。

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

参数
`tokenResponse`	`TokenResponse`	必需。一个 `TokenResponse` 对象。
`firstScope`	字符串	必需。要检查的范围。
`restScopes`	字符串[]	（可选）要检查的其他范围。

返回
布尔值	如果有任何范围被授予，则为 true。

方法：google.accounts.oauth2.revoke

revoke 方法可撤消用户向应用授予的所有范围。需要有效的访问令牌才能撤消权限。

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

参数
`accessToken`	字符串	必需。有效的访问令牌。
`done`	函数	（可选）撤消操作完成后的回调函数。