对帐号授权

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

关联您的账号

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

在本指南中，您既是 user 也是 developer。

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

   1. 将 project-id 替换为您的 Device Access Project ID
   2. 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
   

2. 如果您最近使用多个账号登录过 Google，系统可能会显示初始的选择账号界面，其中列出了您的 Google 账号。如果是，请选择与您要授权使用 Device Access的设备相关联的 Google 账号。
3. Google Nest 权限界面本身就是 PCM。您可以在此处授予住宅和设备权限。开启住宅（第 1 步）和该住宅内受 SDM API 支持的任何设备（第 2 步）的权限，然后点击下一步。
4. 在选择账号以继续项目名称界面上（其中项目名称是您的 Google Cloud 项目的名称），选择您希望授权给 SDM API 的 Google 账号。使用与之前相同的 Google 账号。
5. 选择账号后，您可能会看到一条警告消息，指出 Google 尚未验证此应用。如果看到此消息，请点击高级选项，然后点击前往项目名称（不安全）以继续操作。如需了解详情，请参阅此应用未经 Google 验证。
6. 在授予项目名称权限界面上，点击允许，以授予项目访问您 Google 账号的权限。
7. 在确认您的选择界面上，确保您要授予的权限已勾选，然后点击允许进行确认。

8. 您应重定向到 https://www.google.com。授权代码以网址中的 code 参数形式返回，格式应如下所示：

   https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service
   

9. 复制授权代码。

获取访问令牌

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

1. 打开终端并运行以下 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'

2. 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。

1. 打开终端并运行以下 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'

2. 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 尚未验证此应用”屏幕，如果未在 Google Cloud 的 OAuth 同意屏幕上配置 sdm.service 范围，则会显示此屏幕。您可以点击高级选项，然后点击前往项目名称（不安全）来绕过此屏幕。

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

客户端无效

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

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

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

重定向 URI 不匹配

在进行授权时，您可能会遇到“重定向 URI 不匹配”错误。请确保您在授权调用中使用的 redirect_uri 值与您为 OAuth 2.0 客户端设置的值相同，如 Google Cloud 凭据页面所示。

修改账号权限

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

https://nestservices.google.com/partnerconnections

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

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

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

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

快速参考

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

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

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

https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service

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'

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

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-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'

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