此参考页面记录了您的服务必须实现的 API 端点，才能支持与 Google 进行账号关联。这包括基于 OAuth 的账号关联、精简的账号关联和应用快速关联。
前提条件和标准
为成功实现这些端点，您的服务必须遵循以下标准：
- OAuth 2.0：符合 RFC 6749。
- 令牌撤消：符合 RFC 7009。
- JSON Web 令牌 (JWT)：符合 RFC 7519（精简关联必需）。
- HTTPS：所有端点都必须通过安全的 HTTPS 连接提供服务。
授权端点
授权端点负责对用户进行身份验证，并征得用户同意将其账号与 Google 相关联。
- 网址：在 Actions 控制台或 Google Cloud 控制台中配置。
- 方法：
GET
请求参数
| 参数 | 说明 |
|---|---|
client_id |
您分配给 Google 的客户端 ID。 |
redirect_uri |
您将对此请求的响应发送到的网址。 |
state |
在重定向 URI 中原封不动地传递回 Google 的记录值。 |
response_type |
对于授权代码流程，必须为 code。 |
scope |
（可选）Google 请求的数据对应的范围列表（以空格分隔）。 |
user_locale |
（可选）Google 账号语言设置，使用 BCP-47 语言标记（例如 en-US）指定。 |
令牌交换端点
此端点负责将授权代码交换为令牌，以及刷新过期的访问令牌。
- 网址：在 Actions 控制台或 Google Cloud 控制台中配置。
- 方法：
POST - Content-Type：
application/x-www-form-urlencoded
将授权代码换成令牌
以下参数用于初始令牌交换请求。
请求参数
| 参数 | 说明 |
|---|---|
client_id |
您分配给 Google 的客户端 ID。 |
client_secret |
您分配给 Google 的客户端密钥。 |
grant_type |
必须为 authorization_code。 |
code |
从授权端点接收到的授权代码。 |
redirect_uri |
初始请求中使用的相同重定向 URI。 |
用刷新令牌换取访问令牌
刷新访问令牌时会使用以下参数。
请求参数
| 参数 | 说明 |
|---|---|
client_id |
您分配给 Google 的客户端 ID。 |
client_secret |
您分配给 Google 的客户端密钥。 |
grant_type |
必须为 refresh_token。 |
refresh_token |
之前向 Google 签发的刷新令牌。 |
响应 (JSON)
返回成功的响应，并在 HTTPS 响应的正文中包含一个 JSON 对象。
- HTTP 状态：
200 OK - Content-Type：
application/json;charset=UTF-8
| 字段 | 说明 |
|---|---|
token_type |
必需。必须为 bearer。 |
access_token |
必需。用于访问服务 API 的短期有效令牌。 |
refresh_token |
对于 authorization_code grant_type，此属性为必需属性。一种长期有效的令牌，用于获取新的访问令牌。 |
expires_in |
必需。访问令牌的剩余生命周期（以秒为单位）。 |
错误响应
如果对令牌端点的请求失败，则返回 HTTP 400 Bad Request 错误，并返回包含以下字段的 JSON 响应：
- HTTP 状态：
400 Bad Request - Content-Type：
application/json;charset=UTF-8
| 错误字段 (JSON) | 说明 |
|---|---|
error |
必需。必须为 invalid_grant。 |
error_description |
（可选）提供更多信息的人类可读文本。 |
处理精简的关联 intent
如果您的服务支持简化的账号关联（使用 Google 登录的 OAuth），您的令牌交换端点还必须支持 JSON Web 令牌 (JWT) 断言，并实现 check、create 和 get intent。
这些请求中使用了以下参数：
请求参数
| 参数 | 说明 |
|---|---|
intent |
所请求的具体简化关联 intent：check、get 或 create。 |
grant_type |
对于这些请求，此参数的值始终为 urn:ietf:params:oauth:grant-type:jwt-bearer。 |
assertion |
一种 JSON Web 令牌 (JWT)，可提供经过签名的 Google 用户身份断言。JWT 包含的信息包括用户的 Google 账号 ID、姓名和电子邮件地址。 您的服务器必须使用 JWT 验证部分中列出的条件来验证此 JWT。 |
client_id |
您分配给 Google 的客户端 ID。 |
client_secret |
您分配给 Google 的客户端密钥。 |
scope |
可选：您已配置 Google 向用户请求的任何范围。通常在 get 和 create 意图期间出现。 |
response_type |
对于 create intent 是必需的：必须设置为 token。 |
JWT 验证
为确保简化关联的安全性，您的服务器必须使用以下条件验证 assertion (JWT)：
- 签名：根据 Google 的公钥（可在 Google 的 JWK 端点处获取）验证签名。
- 签发者 (
iss)：必须为https://accounts.google.com。 - 受众群体 (
aud)：必须与分配给您的集成项目的 Google API 客户端 ID 一致。 - 到期时间 (
exp)：必须是未来的时间。
针对 check 意图的响应
包含 intent=check 的请求会验证您的用户数据库中是否存在 Google 账号（由解码后的 JWT 断言中的 sub 或 email 声明标识）。
- HTTP 状态：
200 OK（找到账号）或404 Not Found（未找到账号） - Content-Type：
application/json;charset=UTF-8
| 字段 | 说明 |
|---|---|
account_found |
必需。如果账号存在，则为 true；否则为 false。 |
针对 get 意图的响应
包含 intent=get 的请求会请求现有 Google 账号的访问令牌。
- HTTP 状态：
200 OK - Content-Type：
application/json;charset=UTF-8
成功的响应 JSON 对象与成功的标准令牌交换响应（返回 access_token、refresh_token 等）使用完全相同的结构。
如果无法关联账号，则返回 HTTP 401 错误。
- HTTP 状态：
401 Unauthorized - Content-Type：
application/json;charset=UTF-8
| 错误字段 (JSON) | 说明 |
|---|---|
error |
必需。必须为 linking_error。 |
login_hint |
（可选）要传递给回退 OAuth 关联流程的用户的电子邮件地址。 |
针对 create 意图的响应
包含 intent=create 的请求会请求使用 JWT 中提供的信息创建新的用户账号。
- HTTP 状态：
200 OK - Content-Type：
application/json;charset=UTF-8
成功的响应 JSON 对象与成功的标准令牌交换响应（返回 access_token、refresh_token 等）使用完全相同的结构。
如果用户已存在，系统会返回 HTTP 401 错误，提示用户关联其现有账号。
- HTTP 状态：
401 Unauthorized - Content-Type：
application/json;charset=UTF-8
| 错误字段 (JSON) | 说明 |
|---|---|
error |
必需。必须为 linking_error。 |
login_hint |
要传递给回退 OAuth 关联流程的用户的电子邮件地址。 |
UserInfo 端点（可选）
用于检索关联用户的基本个人资料信息，如 OpenID Connect Core 1.0 规范中所述。“精简关联”或“一键登录”等功能需要此设置。
- 方法：
GET - 身份验证：
Authorization: Bearer ACCESS_TOKEN
响应 (JSON)
返回成功的响应，并在 HTTPS 响应的正文中包含一个 JSON 对象。
- HTTP 状态：
200 OK - Content-Type：
application/json;charset=UTF-8
响应字段
| 字段 | 说明 |
|---|---|
sub |
必需。用于在您的系统中标识用户的唯一 ID。 |
email |
必需。用户的电子邮件地址。 |
email_verified |
必需。一个布尔值，用于指示电子邮件地址是否已通过验证。 |
given_name |
（可选）用户的名字。 |
family_name |
（可选）用户的姓氏。 |
name |
（可选）用户的全名。 |
picture |
（可选）指向用户个人资料照片的网址。 |
错误响应
如果访问令牌无效或已过期，则返回 HTTP 401 Unauthorized 错误。您还应添加 WWW-Authenticate 响应标头。
在账户关联过程中返回的任何失败响应（4xx 或 5xx）都被视为不可恢复。在这种情况下，Google 会舍弃所有检索到的令牌，用户必须重新启动账户关联过程。
令牌撤消端点（可选）
允许 Google 在用户解除其账号与 Google 平台的关联时通知您的服务。此端点必须满足 RFC 7009 中所述的要求。
- 方法：
POST - Content-Type：
application/x-www-form-urlencoded
请求参数
| 参数 | 说明 |
|---|---|
client_id |
此字符串用于将请求源标识为 Google。此字符串必须在您的系统中注册为 Google 的唯一标识符。 |
client_secret |
您向 Google 注册的用于服务的密钥字符串。 |
token |
要撤消的令牌。 |
token_type_hint |
（可选）有关要撤消的令牌类型的提示，可以是 access_token 或 refresh_token。如果未指定，则默认为 access_token。 |
响应
当令牌成功删除或令牌已失效时，返回成功响应。
- HTTP 状态：
200 OK - Content-Type：
application/json;charset=UTF-8
错误响应
如果因任何原因（例如数据库不可用）无法删除令牌，请返回 HTTP 503 错误。Google 将稍后或根据 Retry-After 标头的规定重试请求。
- HTTP 状态：
503 Service Unavailable - Content-Type：
application/json;charset=UTF-8 - 标头：
Retry-After: <HTTP-date / delay-seconds>