此页面由 Cloud Translation API 翻译。

对帐号授权

创建 Google Cloud 和设备访问权限项目后，可以使用受支持的 Google Nest 设备授权某个 Google 账号使用 SDM API。

关联您的账号

如需查看结构和设备，您必须将 Google 账号与您的 Device Access 项目。 PCM 可让 user 授权以下用户：允许 developer访问其结构和设备数据。

在本指南中，您同时充当 user 和 developer。

在网页上打开以下链接替换以下内容：

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

如果您最近使用多个账号登录 Google，您可能会：初始显示的选择账号屏幕，其中列出了 Google 账号。如果是，请选择与您设备关联的 Google 账号希望为 Device Access授权。
Google Nest 权限屏幕本身就是 PCM。您可以在此处授予结构和设备权限。开启该住宅（第 1 步）以及该住宅中（第 2 步），然后点击下一步。
在选择一个账号以继续前往项目名称屏幕上，其中 项目名称是您的 Google Cloud 项目的名称，请选择您希望授权 Google 账号访问 SDM API。请使用原先的 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 （通过您的 OAuth2 客户端 ID 和客户端密钥） Google Cloud 凭据
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 参数中所述。如果访问令牌已过期，请使用刷新令牌获取新令牌。

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

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

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

查看未经验证的应用屏幕。

客户无效

如果您尝试获取访问令牌或刷新令牌，客户”错误。确保您在访问令牌和刷新令牌调用中使用的 client_secret 值是所使用的 OAuth 2.0 客户端 ID（可在 Google Cloud 凭据页面。

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

在 PCM 中授予权限后，您可能会遇到 “请求无效”“缺少必需参数：范围”错误。确保您在授权调用中使用的 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 Account（账号）撤消针对该项目的所有权限和访问令牌权限。

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

快速参考

使用此参考可以快速实现向 user 并关联其 Google 账号，了解所有最新动态。

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

1 个 PCM

在网页上打开以下链接替换以下内容：

将project-id 替换为您的 Device Access Project ID
将 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 命令进行替换：

oauth2-client-id和oauth2-client-secret （通过您的 OAuth2 客户端 ID 和客户端密钥） Google Cloud 凭据
将 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 命令，替换以下内容：

oauth2-client-id和oauth2-client-secret （通过您的 OAuth2 客户端 ID 和客户端密钥） Google Cloud 凭据
将 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