Thông báo về các Hành động trong nhà thông minh

Thông báo cho phép Hành động smart home của bạn sử dụng Google Assistant để thông báo cho người dùng về các sự kiện hoặc thay đổi quan trọng liên quan đến thiết bị. Bạn có thể triển khai thông báo để thông báo cho người dùng về các sự kiện kịp thời trên thiết bị, chẳng hạn như khi ai đó đang ở ngoài cửa hoặc để báo cáo về sự thay đổi trạng thái thiết bị được yêu cầu, chẳng hạn như khi khoá cửa đã kích hoạt thành công hoặc bị kẹt.

Hành động smart home của bạn có thể gửi các loại thông báo sau cho người dùng:

  • Thông báo chủ động: Cảnh báo cho người dùng về sự kiện trên thiết bị smart home mà không có yêu cầu nào trước đó của người dùng đối với thiết bị của họ, chẳng hạn như tiếng chuông cửa.

  • Phản hồi tiếp theo: Thông báo xác nhận rằng yêu cầu ra lệnh trên thiết bị đã thành công hoặc không thành công, ví dụ như khi khoá một cửa. Sử dụng những cảnh báo này cho các lệnh thiết bị cần thời gian để hoàn thành. Các câu trả lời tiếp theo chỉ được hỗ trợ khi các yêu cầu lệnh thiết bị được gửi từ loa thông minh và màn hình thông minh.

Assistant đưa ra những thông báo này cho người dùng dưới dạng thông báo trên loa thông minh và màn hình thông minh. Thông báo chủ động được tắt theo mặc định. Người dùng có thể bật hoặc tắt tất cả các thông báo chủ động từ Google Home app (GHA).

Các sự kiện kích hoạt thông báo

Khi các sự kiện trên thiết bị xảy ra, hành động thực hiện Hành động của bạn sẽ gửi một yêu cầu thông báo cho Google. Các đặc điểm thiết bị mà Hành động smart home của bạn hỗ trợ xác định những loại sự kiện thông báo có sẵn và dữ liệu bạn có thể đưa vào các thông báo đó.

Các đặc điểm sau đây hỗ trợ thông báo chủ động:

Đặc điểm Sự kiện
ObjectDetection Các vật thể mà thiết bị phát hiện được, chẳng hạn như khi phát hiện thấy khuôn mặt đã được nhận dạng ở cửa. Ví dụ: "Alice và Bob đang ở cửa trước."
RunCycle Thiết bị hoàn tất một chu kỳ. Ví dụ: "Chu kỳ giặt của máy đã hoàn tất."
SensorState Thiết bị phát hiện thấy trạng thái cảm biến được hỗ trợ. Ví dụ: "Máy phát hiện khói phát hiện thấy khói."
TemperatureControl Thiết bị đạt đến một điểm đặt nhiệt độ. Ví dụ: "Lò đã được làm nóng trước ở 350 độ".
ArmDisarm Hệ thống sẽ chuyển sang trạng thái trước chuông báo với đồng hồ đếm ngược lúc bắt đầu nhập, được kích hoạt bằng một cánh cửa mở.
CameraStream Liên kết đến sự kiện phát trực tiếp của camera sau khi thiết bị phát hiện thấy vật thể hoặc chuyển động.
MotionDetection "Phát hiện thấy chuyển động lúc 12 giờ đêm ngày 1 tháng 7 năm 2020."

Các đặc điểm sau đây hỗ trợ phản hồi theo dõi:

Đặc điểm Sự kiện
ArmDisarm Trạng thái hoàn thành và thay đổi trạng thái sau khi thực thi lệnh thiết bị action.devices.commands.ArmDisarm. Ví dụ: "Hệ thống an ninh đã được bật."
LockUnlock Trạng thái hoàn thành và thay đổi trạng thái sau khi thực thi lệnh thiết bị action.devices.commands.LockUnlock. Ví dụ: "The Front window was lock" (Cửa trước đã bị khoá) hoặc "The trước window is jamed" (Cửa trước bị kẹt).
NetworkControl Trạng thái hoàn thành và thay đổi trạng thái sau khi thực thi lệnh thiết bị action.devices.commands.TestNetworkSpeed. Ví dụ: "Quá trình kiểm tra tốc độ mạng của bạn đã hoàn tất. Tốc độ tải xuống trên bộ định tuyến văn phòng hiện tại là 80,2 Kb/giây và tốc độ tải lên là 9,3 Kb/giây."
OpenClose Trạng thái hoàn thành và thay đổi trạng thái sau khi thực thi lệnh thiết bị action.devices.commands.OpenClose. Ví dụ: "The phía trước cửa đã mở" hoặc "Không thể mở cửa trước".
StartStop Trạng thái hoàn thành và thay đổi trạng thái sau khi thực thi lệnh thiết bị action.devices.commands.StartStop. Ví dụ: "Máy hút bụi đã khởi động".

Tất cả các loại thiết bị đều hỗ trợ thông báo cho các trait có liên quan.

Xây dựng thông báo cho Hành động của nhà thông minh

Thêm thông báo vào Hành động smart home của bạn theo các giai đoạn sau:

  1. Cho Google biết liệu thông báo có được bật trong ứng dụng smart home trên thiết bị hay không. Nếu người dùng bật hoặc tắt thông báo trong ứng dụng của bạn, hãy gửi yêu cầu SYNC để thông báo cho Google về việc thay đổi thiết bị.
  2. Khi một sự kiện liên quan đến thiết bị hoặc sự thay đổi trạng thái xảy ra và kích hoạt một thông báo, hãy gửi yêu cầu thông báo bằng cách gọi API Report State reportStateAndNotification. Nếu trạng thái thiết bị thay đổi, bạn có thể gửi cả trạng thái và trọng tải thông báo trong Report State và lệnh gọi Thông báo.

Các phần sau đây sẽ trình bày chi tiết hơn về các bước này.

Cho biết liệu thông báo có được bật trong ứng dụng của bạn hay không

Người dùng có thể chọn xem họ có muốn nhận thông báo chủ động hay không bằng cách bật tính năng này trong GHA. Trong ứng dụng dành cho thiết bị smart home, bạn cũng có thể tuỳ ý thêm khả năng để người dùng bật/tắt thông báo một cách rõ ràng trên thiết bị, chẳng hạn như trong phần cài đặt ứng dụng.

Cho Google biết rằng thông báo đã được bật cho thiết bị của bạn bằng cách thực hiện lệnh gọi Request SYNC (Yêu cầu đồng bộ hoá) để cập nhật dữ liệu thiết bị. Bạn nên gửi một yêu cầu SYNC như thế này bất cứ khi nào người dùng thay đổi chế độ cài đặt này trong ứng dụng của bạn.

Trong phản hồi SYNC của bạn, hãy gửi một trong những thông tin cập nhật sau:

  • Nếu người dùng đã bật thông báo một cách rõ ràng trong ứng dụng trên thiết bị, hoặc nếu bạn không cung cấp tuỳ chọn bật/tắt, hãy đặt thuộc tính devices.notificationSupportedByAgent thành true.
  • Nếu người dùng đã tắt thông báo một cách rõ ràng trong ứng dụng trên thiết bị, hãy đặt thuộc tính devices.notificationSupportedByAgent thành false.

Đoạn mã sau đây cho thấy ví dụ về cách đặt phản hồi SYNC:

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

Gửi yêu cầu thông báo cho Google

Để kích hoạt thông báo trên Assistant, phương thức thực hiện của bạn sẽ gửi trọng tải thông báo đến Google Home Graph thông qua lệnh gọi Report State và API thông báo.

Bật Google HomeGraph API

  1. Trong Google Cloud Console, hãy truy cập trang HomeGraph API.

    Truy cập trang HomeGraph API
  2. Chọn dự án khớp với mã dự án smart home của bạn.
  3. Nhấp vào BẬT.

Tạo khoá tài khoản dịch vụ

Hãy làm theo các hướng dẫn sau để tạo khoá tài khoản dịch vụ từ Google Cloud Console:

Lưu ý: Hãy đảm bảo rằng bạn đang sử dụng đúng dự án GCP khi thực hiện các bước này. Đây là dự án khớp với mã dự án smart home của bạn.
  1. Trong Google Cloud Console, hãy chuyển đến trang Tạo khoá tài khoản dịch vụ.

    Chuyển đến trang Tạo khoá tài khoản dịch vụ
  2. Trong danh sách Service account (Tài khoản dịch vụ), hãy chọn New service account (Tài khoản dịch vụ mới).
  3. Trong trường Tên tài khoản dịch vụ, hãy nhập tên.
  4. Trong trường Mã tài khoản dịch vụ, hãy nhập một mã.
  5. Trong danh sách Vai trò, hãy chọn Service Accounts (Tài khoản dịch vụ) > Service Account Token Creator (Người tạo mã thông báo tài khoản dịch vụ).

  6. Đối với Loại khoá, hãy chọn tuỳ chọn JSON.

  7. Nhấp vào Tạo. Tệp JSON chứa khoá bạn đã tải xuống máy tính.

Gửi thông báo

Thực hiện lệnh gọi yêu cầu thông báo bằng API devices.reportStateAndNotification. Yêu cầu JSON của bạn phải bao gồm eventId. Đây là mã nhận dạng duy nhất do nền tảng của bạn tạo ra cho sự kiện kích hoạt thông báo. eventId phải là một mã nhận dạng ngẫu nhiên khác nhau mỗi khi bạn gửi một yêu cầu thông báo.

Trong đối tượng notifications mà bạn truyền vào lệnh gọi API, hãy thêm giá trị priority để xác định cách trình bày thông báo. Đối tượng notifications có thể bao gồm các trường khác nhau tuỳ thuộc vào đặc điểm của thiết bị.

Hãy đi theo một trong các đường dẫn sau để đặt trọng tải và gọi API:

Gửi trọng tải thông báo chủ động

Để gọi API, hãy chọn một tuỳ chọn ở một trong các thẻ sau:

HTTP

API Home Graph cung cấp một điểm cuối HTTP

  1. Dùng tệp JSON của tài khoản dịch vụ đã tải xuống để tạo Mã thông báo web JSON (JWT). Để biết thêm thông tin, hãy xem phần Xác thực bằng tài khoản dịch vụ.
  2. Nhận mã truy cập OAuth 2.0 có phạm vi https://www.googleapis.com/auth/homegraph bằng OAuth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Tạo yêu cầu JSON bằng agentUserId. Dưới đây là yêu cầu JSON mẫu cho Report State và Notification:
  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. Kết hợp Report State và JSON thông báo cũng như mã thông báo trong yêu cầu POST HTTP tới điểm cuối của Google Home Graph. Dưới đây là ví dụ về cách đưa ra yêu cầu trong dòng lệnh bằng curl để kiểm thử:
  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

API Home Graph cung cấp một điểm cuối gRPC

  1. Nhận định nghĩa dịch vụ vùng đệm giao thức cho API Home Graph.
  2. Làm theo tài liệu dành cho nhà phát triển gRPC để tạo mã giả lập ứng dụng cho một trong các ngôn ngữ được hỗ trợ.
  3. Gọi phương thức ReportStateAndNotification.

Node.js

Ứng dụng Node.js API của Google cung cấp các liên kết cho API Home Graph.

  1. Khởi động dịch vụ google.homegraph bằng Thông tin xác thực mặc định của ứng dụng.
  2. Gọi phương thức reportStateAndNotification bằng ReportStateAndNotificationRequest. Phương thức này trả về một Promise với ReportStateAndNotificationResponse.
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

Thư viện ứng dụng API HomeGraph cho Java cung cấp các liên kết cho API Home Graph.

  1. Khởi động HomeGraphApiService bằng cách sử dụng Thông tin xác thực mặc định của ứng dụng.
  2. Gọi phương thức reportStateAndNotification bằng ReportStateAndNotificationRequest. Phương thức này trả về một 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);
    
Gửi tải trọng phản hồi tiếp theo

Tải trọng của phản hồi tiếp theo chứa trạng thái của yêu cầu, mã lỗi cho các sự kiện không thành công (nếu có) và followUpToken hợp lệ được cung cấp trong yêu cầu ý định EXECUTE. Bạn phải sử dụng followUpToken trong vòng 5 phút để duy trì tính hợp lệ và liên kết đúng cách phản hồi với yêu cầu ban đầu.

Đoạn mã sau đây cho thấy một ví dụ về tải trọng yêu cầu EXECUTE với trường followUpToken.

{
  "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 sử dụng followUpToken để chỉ xuất thông báo trên thiết bị mà người dùng đã tương tác ban đầu và không phát đi thông báo trên tất cả các thiết bị của người dùng.

Để gọi API, hãy chọn một tuỳ chọn ở một trong các thẻ sau:

HTTP

API Home Graph cung cấp một điểm cuối HTTP

  1. Dùng tệp JSON của tài khoản dịch vụ đã tải xuống để tạo Mã thông báo web JSON (JWT). Để biết thêm thông tin, hãy xem phần Xác thực bằng tài khoản dịch vụ.
  2. Nhận mã truy cập OAuth 2.0 có phạm vi https://www.googleapis.com/auth/homegraph bằng OAuth2l:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. Tạo yêu cầu JSON bằng agentUserId. Dưới đây là yêu cầu JSON mẫu cho Report State và Notification:
  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. Kết hợp Report State và JSON thông báo cũng như mã thông báo trong yêu cầu POST HTTP tới điểm cuối của Google Home Graph. Dưới đây là ví dụ về cách đưa ra yêu cầu trong dòng lệnh bằng curl để kiểm thử:
  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

API Home Graph cung cấp một điểm cuối gRPC

  1. Nhận định nghĩa dịch vụ vùng đệm giao thức cho API Home Graph.
  2. Làm theo tài liệu dành cho nhà phát triển gRPC để tạo mã giả lập ứng dụng cho một trong các ngôn ngữ được hỗ trợ.
  3. Gọi phương thức ReportStateAndNotification.

Node.js

Ứng dụng Node.js API của Google cung cấp các liên kết cho API Home Graph.

  1. Khởi động dịch vụ google.homegraph bằng Thông tin xác thực mặc định của ứng dụng.
  2. Gọi phương thức reportStateAndNotification bằng ReportStateAndNotificationRequest. Phương thức này trả về một Promise với ReportStateAndNotificationResponse.
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

Thư viện ứng dụng API HomeGraph cho Java cung cấp các liên kết cho API Home Graph.

  1. Khởi động HomeGraphApiService bằng cách sử dụng Thông tin xác thực mặc định của ứng dụng
  2. Gọi phương thức reportStateAndNotification bằng ReportStateAndNotificationRequest. Phương thức này trả về một 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);
    

Logging

Thông báo hỗ trợ ghi nhật ký sự kiện như đã nêu trong phần Truy cập nhật ký sự kiện bằng tính năng ghi nhật ký trên đám mây. Các nhật ký này rất hữu ích để kiểm thử và duy trì chất lượng thông báo trong Hành động của bạn.

Sau đây là giản đồ của một mục notificationLog:

Tài sản Nội dung mô tả
requestId Mã yêu cầu thông báo.
structName Tên của cấu trúc thông báo, chẳng hạn như "ObjectDetection".
status Cho biết trạng thái của thông báo.

Trường status bao gồm nhiều trạng thái có thể chỉ ra lỗi trong tải trọng thông báo. Một số tính năng trong số này có thể chỉ có trên những Hành động chưa được phát hành chính thức.

Ví dụ về trạng thái:

Trạng thái Nội dung mô tả
EVENT_ID_MISSING Cho biết trường eventId bắt buộc bị thiếu.
PRIORITY_MISSING Cho biết trường priority bị thiếu.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Cho biết rằng thuộc tính notificationSupportedByAgent của thiết bị mà bạn cung cấp trong SYNC là sai.
NOTIFICATION_ENABLED_BY_USER_FALSE Cho biết người dùng chưa bật thông báo trên thiết bị gửi thông báo trong GHA. Trạng thái này chỉ xuất hiện đối với những Hành động chưa được phát hành chính thức.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Cho biết người dùng chưa chỉ định thiết bị thông báo cho một Nhà/Nhà. Trạng thái này chỉ xuất hiện đối với những Hành động chưa được phát hành chính thức.

Ngoài các trạng thái chung này có thể áp dụng cho tất cả thông báo, trường status cũng có thể bao gồm các trạng thái cụ thể theo đặc điểm nếu có (ví dụ: OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).