此页面由 Cloud Translation API 翻译。

对帐号授权

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

关联您的账号

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

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

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

使用您的 Device Access Project 身份证件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"
        }
      ]
    }
  ]
}

如何使用刷新令牌

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

此命令与访问令牌类似，只不过您使用的是不同的 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 帐号关联时，您将收到“Access denied”错误。请务必将该 Google 帐号添加到 OAuth 同意屏幕的测试用户部分。

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

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

此应用未经 Google 验证

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

在授权过程中，您可能会看到“Google 尚未验证此应用”屏幕。如果未在 Google Cloud 的 OAuth 同意屏幕上配置 sdm.service 范围，系统就会显示该屏幕。如需绕过此屏幕，请点击 Advanced 选项，然后点击 Go to Project Name (unsafe)。

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

客户无效

尝试获取访问权限或刷新令牌时，如果提供的 OAuth 2.0 客户端密钥不正确，则会收到“客户端无效”错误。确保您在访问令牌和刷新令牌调用中使用的 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 帐号，以撤消项目为该帐号授予的所有权限和访问令牌。

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

快速参考

使用此参考文档可快速执行授权user 并关联其 Google 帐号的步骤。

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

1 个 PCM

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

使用您的 Device Access Project 身份证件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

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 替换为 Google Cloud 凭据中的 OAuth2 客户端 ID 和客户端密钥
将 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 刷新令牌

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

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

将 oauth2-client-id 和 oauth2-client-secret 替换为 Google Cloud 凭据中的 OAuth2 客户端 ID 和客户端密钥
将 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