“请求同步”会针对任何 Google 用户向您的执行方式触发 SYNC
请求
具有指定的
关联的 agentUserId
个(您
在原始 SYNC 请求中发送)。这样,您就可以更新用户的设备
而无需解除关联并重新关联他们的账号。关联到此文件夹的所有用户
标识符会收到 SYNC
请求。
你必须在以下情况下触发 SYNC
请求:
- 如果用户添加新设备。
- 如果用户移除现有设备。
- 如果用户重命名现有设备。
- 如果你实现新的设备类型、特征或添加新的设备功能。
使用入门
如需实现请求同步,请按以下步骤操作:
启用 Google HomeGraph API
-
在 Google Cloud Console 中,前往 HomeGraph API 页面。
转到 HomeGraph API 页面 - 选择与您的 smart home 项目 ID 匹配的项目。
- 点击启用。
创建服务账号密钥
请按照以下说明通过 Google Cloud Console 生成服务账号密钥:
注意:请确保你在执行以下步骤时使用的 GCP 项目正确无误。这是与您的 smart home 项目 ID 匹配的项目。
-
在 Google Cloud Console 中,转到创建服务账号密钥页面。
转到“创建服务账号密钥”页面 - 从服务账号列表中,选择创建服务账号。
- 在服务账号名称字段中,输入一个名称。
- 在服务账号 ID 字段中,输入一个 ID。
从角色列表中,依次选择 Service Accounts > Service Account Token Creator。
对于密钥类型,选择 JSON 选项。
- 点击创建。包含密钥的 JSON 文件就会下载到计算机。
调用该 API
HTTP
Home Graph API 提供 HTTP 端点
- 使用下载的服务账号 JSON 文件创建 JSON 网络令牌 (JWT)。如需了解详情,请参阅使用服务账号进行身份验证。
- 使用 oauth2l 获取具有
https://www.googleapis.com/auth/homegraph
范围的 OAuth 2.0 访问令牌: - 使用
agentUserId
创建 JSON 请求。 以下是请求同步的 JSON 请求示例: - 将请求同步 JSON 和 HTTP POST 请求中的令牌合并到 Google Home Graph 端点中。作为测试,以下示例演示了如何在命令行中使用
curl
发出请求:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "agentUserId": "user-123" }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:requestSync"
gRPC
Home Graph API 提供 gRPC 端点
- 获取 Home Graph API 的协议缓冲区服务定义。
- 按照 gRPC 开发者文档进行操作,为其中一种受支持的语言生成客户端存根。
- 调用 RequestSync 方法。
Node.js
Google API Node.js 客户端为 Home Graph API 提供绑定。
- 使用应用默认凭据初始化
google.homegraph
服务。 - 使用 RequestSyncDevicesRequest 调用
requestSync
方法。它会返回包含空 RequestSyncDevicesResponse 的Promise
。
const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.requestSync({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', async: false } });
Java
适用于 Java 的 HomeGraph API 客户端库为 Home Graph API 提供绑定。
- 使用应用默认凭据初始化
HomeGraphApiService
。 - 使用
RequestSyncDevicesRequest
调用requestSync
方法。它会返回一个空的ReportStateAndNotificationResponse
。
// Get Application Default credentials. GoogleCredentials credentials = GoogleCredentials.getApplicationDefault() .createScoped(List.of("https://www.googleapis.com/auth/homegraph")); // Create Home Graph service client. HomeGraphService homegraphService = new HomeGraphService.Builder( GoogleNetHttpTransport.newTrustedTransport(), GsonFactory.getDefaultInstance(), new HttpCredentialsAdapter(credentials)) .setApplicationName("HomeGraphExample/1.0") .build(); // Request sync. RequestSyncDevicesRequest request = new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false); homegraphService.devices().requestSync(request);
错误响应
调用请求同步时,你可能会收到以下某个错误响应。这些响应以 HTTP 状态代码的形式出现。
400 Bad Request
- 服务器无法处理 客户端发送的请求,因为语法无效。常见原因 包含格式错误的 JSON 或使用null
代替 ""指定字符串值。403 Forbidden
- 服务器无法处理 请求agentUserId
,因为在 刷新令牌确保您的 OAuth 端点能够响应 正确刷新令牌请求并检查用户的账号关联 状态。404 Not Found
- 请求的资源无法 但将来可能会提供。通常情况下,这意味着 该用户账号未与 Google 关联,或我们收到的无效agentUserId
。确保agentUserId
与 您的 SYNC 响应,则说明您已正确 处理 DISCONNECT intent。429 Too Many Requests
- 并发同步数量上限 给定agentUserId
的请求数超出请求。来电者 只能发出一个并发同步请求,除非async
标志设置为 true。