对帐号授权

创建 Google Cloud 和 Device Access 项目后，您可以为 SDM API 授权 Google 账号使用受支持的 Google Nest 设备。

关联您的账号

如需查看结构和设备，您必须使用 PCM 将 Google 账号关联到Device Access 项目。借助 PCM， user 可以授予权限，允许 developer访问其结构和设备数据。

在本指南中，您将同时担任 user 和 developer的角色。

在网络浏览器中打开以下链接，并将以下内容替换为：

将 project-id 替换为您的 Device Access Project ID
oauth2-client-id 替换为来自您的 Google Cloud 凭据的 OAuth2 客户端 ID

https://nestservices.google.com/partnerconnections/project-id/auth?redirect_uri=https://www.google.com&access_type=offline&prompt=consent&client_id=oauth2-client-id&response_type=code&scope=https://www.googleapis.com/auth/sdm.service

如果您最近使用多个账号登录了 Google，系统可能会显示初始的选择账号界面，其中列出了您的 Google 账号。如果是，请选择与您要授权使用 Device Access的设备相关联的 Google 账号。
Google Nest 权限界面本身就是 PCM。您可以在此处授予住宅和设备权限。针对住宅（第 1 步）以及该住宅中受 SDM API 支持的任何设备（第 2 步）开启相应权限，然后点击下一步。
在选择账号以继续项目名称界面上（其中项目名称是您的 Google Cloud 项目的名称），选择您希望授权给 SDM API 的 Google 账号。使用与之前相同的 Google 账号。
选择账号后，您可能会看到一条警告消息，指出 Google 尚未验证此应用。如果看到此消息，请点击高级选项，然后点击前往项目名称（不安全）以继续操作。如需了解详情，请参阅此应用未经 Google 验证。
在授予项目名称权限界面上，点击允许，以授予项目访问您 Google 账号的权限。
在确认您的选择界面上，确保您要授予的权限已勾选，然后点击允许进行确认。
您应重定向到 https://www.google.com。授权代码以网址中的 code 参数形式返回，格式应如下所示：
```
https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service
```
复制授权代码。

获取访问令牌

使用授权代码检索访问令牌，该令牌可用于调用 SDM API。

打开终端并运行以下 curl 命令，替换：
1. oauth2-client-id 和 oauth2-client-secret 替换为来自您的 Google Cloud 凭据的 OAuth2 客户端 ID 和客户端密钥
2. authorization-code 替换为您在上一步中收到的验证码
```
curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&code=authorization-code&grant_type=authorization_code&redirect_uri=https://www.google.com'
```

Google OAuth 会返回两个令牌：访问令牌和刷新令牌。

{
  "access_token": "access-token",
  "expires_in": 3599,
  "refresh_token": "refresh-token",
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}

复制这两个值。访问令牌用于调用 SDM API，刷新令牌用于获取新的访问令牌。

进行设备列表调用

只有在您使用新访问令牌进行首次 devices.list 调用后，授权才算完成。此初始调用会完成授权流程，并启用事件（如果您已设置 Pub/Sub 订阅）。

使用 curl 为 devices 端点发出此调用：

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

如果调用成功，系统会返回与您的 Device Access项目相关联的设备列表。每种设备都有自己独特的可用特征列表：

{
  "devices": [
    {
      "name": "enterprises/project-id/devices/device-id",
      "type": "sdm.devices.types.device-type",
      "traits": { ... },
      "parentRelations": [
        {
          "parent": "enterprises/project-id/structures/structure-id/rooms/room-id",
          "displayName": "device-room-name"
        }
      ]
    }
  ]
}

如何使用刷新令牌

SDM API 的访问令牌仅在 1 小时内有效，如 Google OAuth 返回的 expires_in 参数中所述。如果访问令牌过期，请使用刷新令牌获取新令牌。

该命令与访问令牌命令类似，只是您需要使用不同的 grant_type。

打开终端并运行以下 curl 命令，替换：
1. oauth2-client-id 和 oauth2-client-secret 替换为来自您的 Google Cloud 凭据的 OAuth2 客户端 ID 和客户端密钥
2. refresh-token 替换为您在最初获取访问令牌时收到的验证码。
```
curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&refresh_token=refresh-token&grant_type=refresh_token'
```

Google OAuth 返回新的访问令牌。

{
  "access_token": "new-access-token",
  "expires_in": 3599,
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}

问题排查

如需详细了解 Google OAuth，请参阅使用 OAuth 2.0 访问 Google API。

刷新令牌一直过期

如果客户端 ID 未获批准，刷新令牌可能会在 7 天后停止工作，这是一种可能的原因。7 天的令牌过期时间与商业版或沙盒版审批无关。服务账号或用户账号需要获得 OAuth 2.0 客户端 ID 审批并投入生产，才能获得更长的令牌有效期。如需了解详情，请参阅刷新令牌过期。

访问遭拒

如果您已在 Google Cloud 中设置 OAuth 权限请求页面，并且用户类型为外部，那么当您尝试使用未列为应用测试用户的 Google 账号进行账号关联时，系统会显示“拒绝访问”错误。请务必将该 Google 账号添加到 OAuth 权限请求页面的测试用户部分。

合作伙伴连接管理工具 (PCM) 错误

如需获得有关访问 PCM 时遇到的任何错误的帮助，请参阅合作伙伴连接管理器 (PCM) 错误参考。

此应用未经 Google 验证

SDM API 使用受限范围，这意味着任何在授权期间使用此范围的应用都将处于“未经验证”状态，除非完成 OAuth API 验证。当您 Device Access 用于个人用途时，无需进行 OAuth API 验证。

在授权过程中，您可能会看到“Google 尚未验证此应用”屏幕，如果您的 OAuth 权限请求页面中未在 Google Cloud 中配置 sdm.service 范围，则会显示此屏幕。点击高级选项，然后点击前往项目名称（不安全），即可绕过此界面。

如需了解详情，请参阅“未经验证的应用”界面。

客户端无效

尝试获取访问令牌或刷新令牌时，如果您提供的 OAuth 2.0 客户端密钥不正确，系统会显示“无效的客户端”错误。请确保您在访问令牌和刷新令牌调用中使用的 client_secret 值是所用 OAuth 2.0 客户端 ID 的值，如 Google Cloud 凭据页面中所示。

请求无效，缺少必需的范围

在 PCM 中授予权限后，您可能会遇到“无效请求”错误，并显示“缺少必需的参数：范围”。请确保您在授权调用中使用的 scope 值与您为 OAuth 2.0 客户端设置的值相同，该值可在 Google Cloud 凭据页面中找到。

重定向 URI 不匹配

在进行授权时，您可能会遇到“Redirect uri mismatch”错误。请确保您在授权调用中使用的 redirect_uri 值与您为 OAuth 2.0 客户端设置的值相同，该值可在 Google Cloud 凭据页面中找到。

修改账号权限

如需修改授予 Device Access 项目的权限或完全断开连接，请前往 PCM：

https://nestservices.google.com/partnerconnections

此页面会显示与您的账号关联的所有第三方开发者服务（Device Access 项目）。选择要更改的 Device Access 项目。在下一个界面中，根据需要修改权限。

如需仅撤消已授权服务的特定权限，请切换要撤消的权限，然后点击返回箭头以保存。

如需完全断开已获授权的服务的连接，请点击解除 Google 账号关联，以撤消项目已获授权的账号的所有权限和访问令牌。

如果 PCM 未显示所需的服务，您可能需要先进行设备列表调用。

快速参考

您可以使用此参考资料快速实现授权user 并关联其 Google 账号的步骤。

如需使用此快速参考，请将代码示例中的每个占位变量替换为适合您特定集成的值，并根据需要进行复制和粘贴：

1 PCM