欢迎使用 Google Home 开发者中心,您可以在这里学习有关如何开发智能家居 Action 的新平台。注意:你将继续在 Actions 控制台中构建操作。

智能家居 Action 通知

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

通过通知,你的智能家居 Action 可以使用 Google 助理与用户交流设备相关的重要事件或变化。你可以实现通知来及时向用户提醒设备事件(例如有人正在门口时),也可以报告所请求设备的状态变更(例如门锁舌成功锁定到位或已卡住)。

你的智能家居 Action 可以向用户发送以下类型的通知:

  • 主动通知:在事先没有用户对设备发出任何请求的情况下(例如按门铃),向用户提醒智能家居设备事件。

  • 后续响应:设备命令请求成功或失败的确认,例如在锁门时。请为需要时间才能完成的设备命令使用这些提醒。

Google 助理会在智能音箱和智能显示屏上以通知的形式向用户提供这些通知。主动通知默认处于关闭状态。 用户可以从 Google Home 应用开启或关闭所有主动通知。

会触发通知的事件

当设备事件发生时,你的 Action 执行方式会向 Google 发送通知请求。你的智能家居 Action 所支持的设备特征会决定可用的通知事件类型,以及可以在这些通知中包含的数据。

以下特征支持主动通知:

特征 活动
ObjectDetection 设备检测到的对象,比如在门口检测到熟悉的面孔。例如:“小红和小波在前门门口。”
RunCycle 设备完成一个周期。例如:“洗衣机洗衣程序已结束。”
SensorState 设备检测到受支持的传感器状态。例如:“烟雾检测器检测到烟雾。”
TemperatureControl 设备达到了设定温度。例如:“烤箱已经预热到 350 度。”
ArmDisarm 开门的动作会触发系统进入预警状态,并显示进门倒计时。
CameraStream 设备检测到物体或动作后摄像头直播内容的链接。
MotionDetection “2020 年 7 月 1 日中午 12 点检测到动作。”

以下特征支持后续响应:

特征 活动
ArmDisarm 执行 action.devices.commands.ArmDisarm 设备命令后的完成状态和状态变更。例如:“安防系统已开启。”
LockUnlock 执行 action.devices.commands.LockUnlock 设备命令后的完成状态和状态变更。例如:“前门已被上锁”或“前门卡住了”。
NetworkControl 执行 action.devices.commands.TestNetworkSpeed 设备命令后的完成状态和状态变更。例如:“你的网速测试已完成。办公室路由器的下载速度目前为 80.2 Kbps,上传速度为 9.3 Kbps。”
OpenClose 执行 action.devices.commands.OpenClose 设备命令后的完成状态和状态变更。例如:“前门已打开”或“前门无法打开”。
StartStop 执行 action.devices.commands.StartStop 设备命令后的完成状态和状态变更。例如:“吸尘器已启动。”

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

为智能家居 Action 构建通知

请在以下阶段为你的智能家居 Action 添加通知:

  1. 向 Google 指示你的智能家居设备应用中是否启用了通知功能。如果用户在你的应用中开启或关闭通知,则发送 SYNC 请求来告知 Google 设备发生的变化。
  2. 当相关设备事件或状态更改发生并触发通知时,则通过调用 Report State reportStateAndNotification API 发送通知请求。如果设备状态发生变化,你可以在报告状态和通知调用中同时发送状态和通知载荷。

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

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

通过在 Google Home 应用中启用此功能,用户可以选择是否要接收主动通知。在智能家居设备的应用中,你还可以选择添加可让用户从设备中明确切换通知开关的功能,例如从应用设置中切换。

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

SYNC 响应中,发送以下某个更新:

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

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

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

向 Google 发送通知请求

如需在 Google 助理上触发通知,你的执行方式应通过 Report State and Notification API 调用将通知载荷发送到 Google Home Graph。

启用 Google HomeGraph API

  1. 在 Google Cloud Platform Console 中,转到 HomeGraph API 页面。

    转到 HomeGraph API 页面
  2. 请选择与你的智能家居项目 ID 相匹配的项目。
  3. 点击启用

创建服务帐号密钥

按照以下说明从 GCP Console 生成服务帐号密钥:

注意:请确保你在执行以下步骤时使用的 GCP 项目正确无误。也就是与你的智能家居项目 ID 匹配的项目。
  1. 在 GCP 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 对象可能包含不同的字段,具体取决于设备特征。

按照以下某个路径设置载荷并调用该 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
    
  4. 使用 agentUserId 创建 JSON 请求。 以下是报告状态和通知的 JSON 请求示例:
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
    
  6. 将报告状态和通知 JSON 与你对 Google Home Graph 端点的 HTTP POST 请求中的令牌合并。作为测试,以下示例演示了如何在命令行中使用 curl 发出请求:
  7. 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 方法。它会返回一个包含 ReportStateAndNotificationResponsePromise
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);
    
发送后续响应载荷

后续响应的载荷包含请求的状态、事件失败的错误代码(如果适用),以及在 EXECUTE intent 请求期间提供的有效 followUpToken。必须在五分钟内使用 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
    
  4. 使用 agentUserId 创建 JSON 请求。 以下是报告状态和通知的 JSON 请求示例:
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
    
  6. 将报告状态和通知 JSON 与你对 Google Home Graph 端点的 HTTP POST 请求中的令牌合并。作为测试,以下示例演示了如何在命令行中使用 curl 发出请求:
  7. 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 方法。它会返回一个包含 ReportStateAndNotificationResponsePromise
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);
    

日志记录

智能家居监控和日志记录文档中所述,通知支持事件日志记录。这些日志有助于你在 Action 中测试和维护通知质量。

以下是 notificationLog 条目的架构:

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

status 字段包含可指示通知载荷中错误的各种状态。部分状态可能仅适用于尚未发布正式版的 Action。

状态示例包括:

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

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