对帐号授权

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

如需查看结构和设备，您必须使用 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 账号。如果是，请选择与您设备关联的 Google 账号 希望为 Device Access授权。
  3. Google Nest 权限界面就是 PCM 本身。您可以在此处授予结构和设备权限。为住宅（第 1 步）和 SDM API 支持的住宅中的所有设备（第 2 步）开启相应权限，然后点击下一步。
  4. 在选择一个账号以继续到 Project Name 页面上（其中 Project Name 是您的 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 参数中所述。如果 访问令牌已过期，请使用刷新令牌获取新令牌。

该命令与访问令牌 1 类似，只不过您使用不同的 grant_type。

  1. 打开终端并运行 以下 curl 命令，替换以下内容：

    1. oauth2-client-id和oauth2-client-secret 使用 OAuth2 客户端 ID 和客户端密钥， Google Cloud 凭据
    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 时遇到的任何错误的帮助，请参阅 Partner Connections Manager (PCM) 错误参考文档。

此应用未经 Google 验证

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

您可能会看到“Google 尚未验证此应用”这条消息屏幕 进程中，如果未配置 sdm.service 范围，系统就会显示此错误 Google Cloud 中的 OAuth 同意屏幕。此屏幕可以 点击高级选项，然后点击转到项目 名称（不安全）。

如需了解详情，请参阅“未验证的应用”屏幕。

客户无效

如果您尝试获取访问令牌或刷新令牌， 客户”错误。确保您在访问令牌和刷新令牌调用中使用的 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 账号的步骤。

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

1 PCM

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

  1. 将project-id 替换为您的 Device Access Project ID
  2. 将 oauth2-client-id 替换为您的 OAuth2 客户端 ID Google Cloud 凭据
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 授权码

系统应该会将您重定向至 https://www.google.com.授权代码作为 code 参数在网址中返回， 应采用以下格式：

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

3 访问令牌

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

打开一个终端并运行 以下 curl 命令进行替换：

  1. oauth2-client-id和oauth2-client-secret 使用 OAuth2 客户端 ID 和客户端密钥， Google Cloud 凭据
  2. 将 authorization-code 替换为您在上一步中收到的代码

Google OAuth 会返回两个令牌，一个是访问令牌，另一个是刷新令牌。

请求

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"
}

4 API 调用

必须先进行授权，然后才能完成授权 你的第一个 devices.list 调用。如果您已设置 Pub/Sub 订阅，此初始调用会完成授权流程并启用事件。

您必须使用 为指定范围列出以完成授权的 API 调用。

sdm.service

设备

如需了解详情，请参阅 devices.list API 参考文档。

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

5 刷新令牌

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

打开一个终端并运行以下 curl 命令，替换以下内容：

  1. oauth2-client-id 和 oauth2-client-secret 使用 Google Cloud 凭据中的 OAuth2 客户端 ID 和客户端密钥
  2. 将 refresh-token 替换为您最初获取访问权限时收到的代码 令牌。

Google OAuth 会返回新的访问令牌。

请求

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"
}
上一页
1. 开始使用
下一页
3. 使用 API