智能家居 Action 的通知

通知允许您的 smart home Action 使用 Google Assistant，用于就重要的 与设备相关的事件或更改。您可以通过实现通知来提醒 让用户及时掌握设备事件（例如有人在门口时），或 报告所请求的设备状态更改，例如门锁的门锁被锁 已成功互动或卡住

您的 smart home Action 可以发送以下类型的 通知：

  • 主动通知：向用户发出 smart home 的提醒 没有任何之前用户对其设备请求的情况下发生的设备事件，例如 门铃声。

  • 后续响应：设备命令请求成功或失败的确认，例如在锁门时。将这些提醒用于 需要一些时间才能完成的设备命令后续回复只会 如果从智能音箱和智能音箱发出设备命令请求，支持此功能 。

Assistant会通过以下方式向用户提供这些通知： 智能音箱和智能显示屏上的通知。主动通知 默认处于关闭状态 用户可以在 Google Home app (GHA)。

会触发通知的事件

当发生设备事件时，您的 Action 执行方式会发送通知请求 。你的 smart home Action 的设备特征 决定可用的通知事件类型以及 以便在这些通知中包含的数据

以下特征支持主动通知：

特征 事件
ObjectDetection 设备检测到的对象，比如在门口检测到熟悉的面孔。例如：“小红和小波在前门门口。”
RunCycle 设备完成一个周期。例如：“洗衣机洗衣程序已结束。”
SensorState 设备检测到受支持的传感器状态。例如：“烟雾检测器检测到烟雾。”

以下特征支持后续响应：

特征 事件
LockUnlock 执行 action.devices.commands.LockUnlock 设备命令后的完成状态和状态变更。例如：“前门已被上锁”或“前门卡住了”。
NetworkControl 执行 action.devices.commands.TestNetworkSpeed 设备命令后的完成状态和状态变更。例如：“你的网速测试已完成。办公室路由器的下载速度目前为 80.2 Kbps，上传速度为 9.3 Kbps。”
OpenClose 执行 action.devices.commands.OpenClose 设备命令后的完成状态和状态变更。例如：“前门已打开”或“前门无法打开”。

所有设备类型都支持针对适用特征的通知。

为智能家居 Action 构建通知

请在以下阶段向 smart home 操作添加通知：

  1. 向 Google 指示是否已从您的 smart home 个设备应用。如果用户开启或关闭通知 ，请发送 SYNC 请求，将设备更改告知 Google。
  2. 当发生触发 通过调用 Report State reportStateAndNotification API。如果 设备状态发生变化时，您可以同时发送状态和通知载荷 同时在 Report State 和通知调用中一并调用。

以下部分更详细地介绍了这些步骤。

指示你的应用是否启用了通知

用户可以选择是否要通过以下方式接收主动通知： 在 GHA 中启用此功能。在适合您的应用的应用中 smart home 设备，您还可以选择为 用户可以明确切换设备上的通知，例如，从 应用设置

通过进行请求同步调用来更新设备数据，向 Google 指示已为你的设备启用通知。每当用户在你的应用中更改此设置时，你都应发送 SYNC 请求。

在 SYNC 响应中，发送以下某个更新：

  • 如果用户在你的设备应用中明确开启了通知，或者如果你未提供开关切换选项，请将 devices.notificationSupportedByAgent 属性设置为 true。
  • 如果用户在你的设备应用中明确关闭了通知，请将 devices.notificationSupportedByAgent 属性设置为 false。

以下代码段举例说明了如何设置 SYNC 响应：

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

向 Google 发送通知请求

如需在 Assistant上触发通知，您的 执行方式向 Google Home Graph 发送通知载荷 通过 Report State 和 Notification API 调用实现。

启用 Google HomeGraph API

  1. 在 Google Cloud Console 中，前往 HomeGraph API 页面。

    转到 HomeGraph API 页面
  2. 选择与您的 smart home 项目 ID 匹配的项目。
  3. 点击启用。

创建服务账号密钥

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

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

  1. 在 Google Cloud Console 中，转到创建服务账号密钥页面。

    转到“创建服务账号密钥”页面
  2. 从服务账号列表中，选择创建服务账号。
  3. 在服务账号名称字段中，输入一个名称。
  4. 在服务账号 ID 字段中，输入一个 ID。

  5. 从角色列表中，依次选择 Service Accounts > Service Account Token Creator。

  6. 对于密钥类型，选择 JSON 选项。

  7. 点击创建。包含密钥的 JSON 文件就会下载到计算机。

发送通知

使用 devices.reportStateAndNotification API。 你的 JSON 请求必须包含 eventId，即你的平台为触发通知的事件生成的唯一 ID。eventId 应是一个随机 ID，每次你发送通知请求时，该 ID 都是不同的。

在你在 API 调用中传递的 notifications 对象中，添加 priority 值来定义应如何显示通知。您的 notifications 对象可能包含不同的字段，具体取决于设备 trait。

按照以下某个路径设置载荷并调用该 API：

发送主动通知载荷

如需调用该 API，请从以下某个标签页中选择一个选项：

HTTP

Home Graph API 提供 HTTP 端点

  1. 使用下载的服务账号 JSON 文件创建 JSON 网络令牌 (JWT)。如需了解详情，请参阅使用服务账号进行身份验证。
  2. 使用 oauth2l 获取具有 https://www.googleapis.com/auth/homegraph 范围的 OAuth 2.0 访问令牌：
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. 使用 agentUserId 创建 JSON 请求。 以下是针对 Report State 和 Notification 的 JSON 请求示例：
    4. {
  "agentUserId": "PLACEHOLDER-USER-ID",
  "eventId": "PLACEHOLDER-EVENT-ID",
  "requestId": "PLACEHOLDER-REQUEST-ID",
  "payload": {
    "devices": {
      "notifications": {
        "PLACEHOLDER-DEVICE-ID": {
          "ObjectDetection": {
            "priority": 0,
            "detectionTimestamp": 1534875126750,
            "objects": {
              "named": [
                "Alice"
              ],
              "unclassified": 2
            }
          }
        }
      }
    }
  }
}
  4. 将 Report State 和通知 JSON 以及您的 HTTP POST 中的令牌合并在一起 发送到 Google Home Graph 端点。这里的示例说明了 在命令行中使用 curl 发出请求，如下所示： 测试：
    5. 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 API 提供 gRPC 端点

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

Node.js

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

  1. 使用应用默认凭据初始化 google.homegraph 服务。
  2. 使用 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',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            ObjectDetection: {
              priority: 0,
              detectionTimestamp: 1534875126750,
              objects: {
                named: ['Alice'],
                unclassified: 2
              }
            }
          }
        }
      }
    }
  }
});

Java

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

  1. 使用应用默认凭据初始化 HomeGraphApiService。
  2. 使用 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 notification payload.
Map<?, ?> notifications =
    Map.of(
        "ObjectDetection",
        Map.of(
            "priority", 0,
            "detectionTimestamp", 1534875126,
            "objects", Map.of("named", List.of("Alice"), "unclassifed", 2)));

// Send notification.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications))));
homegraphService.devices().reportStateAndNotification(request);
发送后续响应载荷

后续响应的载荷包含请求的状态、错误 事件失败的代码（如果有），以及有效的 followUpToken； 在 EXECUTE intent 请求期间提供。必须使用 followUpToken 以确保有效性 并将响应正确关联在一起 原始请求

以下代码段说明了一个带有 followUpToken 字段的 EXECUTE 请求载荷示例。

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
        }],
        "execution": [{
          "command": "action.devices.commands.TestNetworkSpeed",
          "params": {
            "testDownloadSpeed": true,
            "testUploadSpeed": false,
            "followUpToken": "PLACEHOLDER"
          }
        }]
      }]
    }
  }]
};

Google 使用 followUpToken 仅在用户最初与之互动的设备上输出通知，而不会在用户的所有设备上广播。

如需调用该 API，请从以下某个标签页中选择一个选项：

HTTP

Home Graph API 提供 HTTP 端点

  1. 使用下载的服务账号 JSON 文件创建 JSON 网络令牌 (JWT)。如需了解详情，请参阅使用服务账号进行身份验证。
  2. 使用 oauth2l 获取具有 https://www.googleapis.com/auth/homegraph 范围的 OAuth 2.0 访问令牌：
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. 使用 agentUserId 创建 JSON 请求。 以下是针对 Report State 和 Notification 的 JSON 请求示例：
    4. {
  "agentUserId": "PLACEHOLDER-USER-ID",
  "eventId": "PLACEHOLDER-EVENT-ID",
  "requestId": "PLACEHOLDER-REQUEST-ID",
  "payload": {
    "devices": {
      "notifications": {
        "PLACEHOLDER-DEVICE-ID": {
          "NetworkControl": {
            "priority": 0,
            "followUpResponse": {
              "status": "SUCCESS",
              "followUpToken": "PLACEHOLDER",
              "networkDownloadSpeedMbps": 23.3,
              "networkUploadSpeedMbps": 10.2
            }
          }
        }
      }
    }
  }
}
  4. 将 Report State 和通知 JSON 以及您的 HTTP POST 中的令牌合并在一起 发送到 Google Home Graph 端点。这里的示例说明了 在命令行中使用 curl 发出请求，如下所示： 测试：
    5. 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 API 提供 gRPC 端点

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

Node.js

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

  1. 使用应用默认凭据初始化 google.homegraph 服务。
  2. 使用 ReportStateAndNotificationRequest 调用 reportStateAndNotification 方法。它会返回一个包含 ReportStateAndNotificationResponse 的 Promise。
const followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken;

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',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            NetworkControl: {
              priority: 0,
              followUpResponse: {
                status: 'SUCCESS',
                followUpToken,
                networkDownloadSpeedMbps: 23.3,
                networkUploadSpeedMbps: 10.2,
              }
            }
          }
        }
      }
    }
  }
});

Java

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

  1. 使用应用默认凭据初始化 HomeGraphApiService
  2. 使用 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();

// Extract follow-up token.
ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0];
String followUpToken =
    (String)
        executeInputs
            .getPayload()
            .getCommands()[0]
            .getExecution()[0]
            .getParams()
            .get("followUpToken");

// Build device follow-up response payload.
Map<?, ?> followUpResponse =
    Map.of(
        "NetworkControl",
        Map.of(
            "priority",
            0,
            "followUpResponse",
            Map.of(
                "status",
                "SUCCESS",
                "followUpToken",
                followUpToken,
                "networkDownloadSpeedMbps",
                23.3,
                "networkUploadSpeedMbps",
                10.2)));

// Send follow-up response.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse))));
homegraphService.devices().reportStateAndNotification(request);

日志记录

通知支持事件日志记录，如使用 Cloud Logging 访问事件日志中所述。 这些日志有助于你在 Action 中测试和维护通知质量。

以下是 notificationLog 条目的架构：

属性 说明
requestId 通知请求 ID。
structName 通知结构体的名称，例如“ObjectDetection”。
status 指示通知的状态。

status 字段包含各种状态，可能指示 通知载荷。部分功能可能仅适用于 尚未发布为正式版

状态示例包括：

状态 说明
EVENT_ID_MISSING 表示缺少必要的 eventId 字段。
PRIORITY_MISSING 表示缺少 priority 字段。
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE 表示 SYNC 中提供的通知设备的 notificationSupportedByAgent 属性为 false。
NOTIFICATION_ENABLED_BY_USER_FALSE 表示用户未在 GHA 中的通知设备上启用通知。此状态仅适用于尚未发布正式版的 Action。
NOTIFYING_DEVICE_NOT_IN_STRUCTURE 表示用户没有将通知设备分配给住宅/结构。此状态仅适用于尚未发布正式版的 Action。

除了这些适用于所有通知的常规状态外，在适用的情况下，status 字段还可能包含特征特有的状态（例如 OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING）。

上一页
Implement Report State
下一页
Test and share Actions