欢迎使用 Google Home 开发者中心，这是一个学习如何开发智能家居 Action 的新平台。注意：构建 Action 的工作仍需在 Actions 控制台中完成。

此页面由 Cloud Translation API 翻译。

报告状态

Report State 是一项重要功能，可让 Home 操作主动向 Google Home Graph 报告用户设备的最新状态，而不是等待 QUERY intent。

Report State 会向 Google 报告与指定 agentUserId（在原始 SYNC 请求中发送）相关联的用户设备的状态。当 Google Assistant 要执行一项需要了解设备当前状态的操作时，它可以直接在 Home Graph 中查询状态信息，无需先向各种不同的第三方云发出 QUERY intent，然后再发出 EXECUTE intent。

如果不用 Report State，当客厅中有来自多个提供商的灯时，“Ok Google，调亮客厅的灯”命令需要解析发送到多个云的多个 QUERY intent，而不是根据之前报告的内容直接查询当前的亮度值。为了提供最佳用户体验，Assistant 需要知道设备的当前状态，而无需往返设备。

在设备的初始 SYNC 之后，该平台会发送 QUERY intent，用于收集设备的状态来填充 Home Graph。在此之后，Home Graph 仅存储随 Report State 发送的状态。

调用 Report State 时，请务必为给定特征提供完整的状态数据。Home Graph 按特征更新状态，并在进行 Report State 调用时覆盖该特征的所有数据。例如，如果您要报告 StartStop 特征的状态，则载荷需要同时包含 isRunning 和 isPaused 两者的值。

开始使用

如需实现 Report State，请按以下步骤操作：

启用 Google HomeGraph API
创建服务账号密钥
调用该 API

启用 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 提供 HTTP 端点

使用下载的服务账号 JSON 文件创建 JSON 网络令牌 (JWT)。如需了解详情，请参阅使用服务账号进行身份验证。
使用 oauth2l 获取具有 https://www.googleapis.com/auth/homegraph 范围的 OAuth 2.0 访问令牌：

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

使用 agentUserId 创建 JSON 请求。以下是报告状态和通知的 JSON 请求示例：

{
  "requestId": "123ABC",
  "agentUserId": "user-123",
  "payload": {
    "devices": {
      "states": {
        "light-123": {
          "on": true
        }
      }
    }
  }
}

将报告状态和通知 JSON 与你对 Google Home Graph 端点的 HTTP POST 请求中的令牌合并。作为测试，以下示例演示了如何在命令行中使用 curl 发出请求：

curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"

gRPC

Home Graph 提供 gRPC 端点

获取 Home Graph API 的协议缓冲区服务定义。
按照 gRPC 开发者文档进行操作，为其中一种受支持的语言生成客户端存根。
调用 ReportStateAndNotification 方法。

Node.js

Google API Node.js 客户端为 Home Graph API 提供绑定。

使用应用默认凭据初始化 google.homegraph 服务。
使用 ReportStateAndNotificationRequest 调用 reportStateAndNotification 方法。它会返回一个包含 ReportStateAndNotificationResponse 的 Promise。

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        states: {
          "PLACEHOLDER-DEVICE-ID": {
            on: true
          }
        }
      }
    }
  }
});

Java

适用于 Java 的 HomeGraph API 客户端库为 Home Graph API 提供绑定。

使用应用默认凭据初始化 HomeGraphApiService。
使用 ReportStateAndNotificationRequest 调用 reportStateAndNotification 方法。它会返回一个 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();

  // Build device state payload.
  Map<?, ?> states = Map.of("on", true);

  // Report device state.
  ReportStateAndNotificationRequest request =
      new ReportStateAndNotificationRequest()
          .setRequestId("PLACEHOLDER-REQUEST-ID")
          .setAgentUserId("PLACEHOLDER-USER-ID")
          .setPayload(
              new StateAndNotificationPayload()
                  .setDevices(
                      new ReportStateAndNotificationDevice()
                          .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states))));
  homegraphService.devices().reportStateAndNotification(request);
}

测试报告状态

完成此任务的推荐工具

为了让您的 Action 为认证做好准备，请务必测试 Report State。

为此，我们建议使用 Home Graph 查看器工具，这是一个独立的 Web 应用，无需下载或部署。

Report State 信息中心仍然可用，但已被弃用且不再受支持。

报告状态信息中心

前提条件

你需要服务账号密钥和 agentUserId 才能测试 Action。如果您已拥有服务账号密钥和 agentUserId，请参阅部署 Report State 信息中心。

如何创建服务账号密钥

按照以下说明从 Google Cloud Console 生成服务账号密钥：

注意：请确保你在执行以下步骤时使用的 GCP 项目正确无误。这是与您的 smart home 项目 ID 匹配的项目。

在 Google Cloud Console 中，前往创建服务账号密钥页面。
转到“创建服务账号密钥”页面
从服务账号列表中，选择创建服务账号。
在服务账号名称字段中，输入一个名称。
在服务账号 ID 字段中，输入一个 ID。
从角色列表中，依次选择 Service Accounts > Service Account Token Creator。
对于密钥类型，选择 JSON 选项。
点击创建。包含密钥的 JSON 文件就会下载到计算机。

如何检索 agentUserId

请按照以下步骤检索你的 agentUserId：

打开 OAuth Playground 工具。
点击右上角的齿轮图标，打开 OAuth 2.0 configuration 对话框。
在 OAuth endpoints 字段中，选择 Custom。
使用你在创建智能家居项目时在 Actions 控制台中设置的值，指定以下账号关联参数。点击 Close 保存你的更改。
- Authorization endpoint：将此参数设置为控制台中的授权网址。
- Token endpoint：将此参数设置为控制台中的令牌网址。
- OAuth client ID：将此参数设置为与控制台中的值相同的值。
- OAuth client secret：将此参数设置为与控制台中的值相同的值。
图 1：设置 OAuth 2.0 配置。
展开 Step 1 - Select & authorize APIs。在显示“Input your own scopes”的文本字段中，输入“devices”，然后点击 Authorize APIs。
注意：如果你在控制台中指定了其他范围，则还应在 Step 1 中指定这些范围。
如果上一步成功，系统会将你重定向到 OAuth 端点。使用你要测试的用户账号登录。成功登录后，系统会将你重定向回 OAuth Playground，并展开 Step 2 和填充为你生成的授权代码。
点击 Exchange authorized code for tokens，获取刷新令牌和访问令牌。
在 Step 3 - Configure request to API 中，请按以下步骤操作：
1. 将 HTTP Method 设置为 POST。
2. 将 Request URI 设置为你的执行方式网址。
3. 点击 Enter request body 并添加以下示例输入：
```
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.SYNC"
  }]
}
        
```
4. 点击 Send the request。
在响应中找到“agentUserId”字段的值。

部署报告状态信息中心

获取项目的服务账号密钥和代理用户 ID 后，从 Report State 信息中心下载并部署最新版本。下载最新版本后，请按照随附的 README.MD 文件的说明进行操作。

部署 Report State 信息中心后，您可以通过以下网址访问信息中心（将 your_project_id 替换为您的项目 ID）：

http://<your-project-id>.appspot.com

在该信息中心内，执行以下操作：

选择你的账号密钥文件
添加你的 agentUserId

然后，点击 List。

系统会列出你的所有设备。系统填充列表后，你可以使用 Refresh 按钮更新设备状态。如果设备状态发生更改，则该行会以绿色突出显示。

错误响应

调用 Report State 时，您可能会收到以下某个错误响应。这些响应以 HTTP 状态代码的形式出现。

400 Bad Request - 由于语法无效，服务器无法处理客户端发送的请求。常见原因包括 JSON 格式错误，或针对字符串值使用 null 而非 ""。
404 Not Found - 未找到请求的资源，但未来可能提供这些资源。通常情况下，这意味着我们找不到所请求的设备。这也可能意味着用户账号未与 Google 关联，或我们收到的 agentUserId 无效。请确保 agentUserId 与 SYNC 响应中提供的值一致，并且您处理 DISCONNECT intent 的方式正确无误。

Request sync

Send notifications