Chào mừng bạn đến với Trung tâm nhà phát triển Google Home, điểm đến mới để tìm hiểu cách phát triển các hành động nhà thông minh. Lưu ý: Bạn sẽ tiếp tục xây dựng các hành động trong bảng điều khiển Actions.

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

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 thay đổi hoặc sự kiện quan trọng liên quan đến thiết bị. Bạn có thể triển khai thông báo để người dùng biết kịp thời các sự kiện của thiết bị, chẳng hạn như khi ai đó đứng trước cửa, hoặc báo cáo về sự thay đổi trạng thái của thiết bị được yêu cầu, chẳng hạn như khi bu lông khoá cửa đã được gắn 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: Thông báo cho người dùng về một 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 về thiết bị, chẳng hạn như chuông cửa.

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

Assistant cung cấp các 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 sẽ bị tắt theo mặc định. Người dùng có thể bật hoặc tắt mọi thông báo chủ động từ Google Home app (GHA).

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

Khi sự kiện trên thiết bị xảy ra, quá trình thực hiện Hành động của bạn sẽ gửi 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 các 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 đó.

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

Đặc điểm tính cách Sự kiện
Đối tượng phát hiện 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 tại cửa. Ví dụ: "Alice và Bob đang ở cửa trước."
RunCycle Thiết bị hoàn thành một chu kỳ. Ví dụ: "Chu kỳ của máy giặt đã hoàn tất".
Trạng thái cảm biến Thiết bị phát hiện thấy trạng thái cảm biến được hỗ trợ. Ví dụ: "Đầu báo khói phát hiện thấy khói".
Kiểm soát nhiệt độ Thiết bị đã đạt đến điểm đặt nhiệt độ. Ví dụ: "Lò nướng đã được làm nóng trước đến 350 độ."
ArmDisarm Hệ thống chuyển sang trạng thái báo thức trước với bộ đếm ngược thời gian, được kích hoạt bởi một cửa mở.
Dòng dữ liệu máy ảnh Đường 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 một đối tượng hoặc chuyển động.
Phát hiện chuyển động "Phát hiện thấy chuyển động lúc 12 giờ trưa ngày 1 tháng 7 năm 2020."

Những đặc điểm hỗ trợ các phản hồi tiếp theo:

Đặc điểm tính cách Sự kiện
ArmDisarm Trạng thái hoàn thành và sự thay đổi trạng thái sau khi thực thi lệnh action.devices.commands.ArmDisarm của thiết bị. Ví dụ: "Hệ thống an ninh đã được bật."
Khóa mở khóa Trạng thái hoàn thành và sự thay đổi trạng thái sau khi thực thi lệnh action.devices.commands.LockUnlock của thiết bị. Ví dụ: "Cửa trước đã khoá" hoặc "Cửa trước bị kẹt."
NetworkControl Trạng thái hoàn thành và sự thay đổi trạng thái sau khi thực thi lệnh action.devices.commands.TestNetworkSpeed của thiết bị. 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 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à sự thay đổi trạng thái sau khi thực thi lệnh action.devices.commands.OpenClose của thiết bị. Ví dụ: "Cửa trước đã mở" hoặc "Không thể mở cửa trước."
Bắt đầu Trạng thái hoàn thành và sự thay đổi trạng thái sau khi thực thi lệnh action.devices.commands.StartStop của thiết bị. Ví dụ: "Chân không đã khởi động".

Tất cả các loại thiết bị đều hỗ trợ thông báo về các đặc điểm thích hợp.

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

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

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

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

Cho biết thông báo đã được bật trong ứng dụng của bạn hay chưa

Người dùng có thể chọn 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 cho phép người dùng bật/tắt thông báo một cách rõ ràng, ví dụ như trong phần cài đặt ứng dụng.

Thông báo cho Google biết tính năng thông báo đã được bật trên 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ộ hóa) để 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.

Trong phản hồi SYNC, 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 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 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 tới Google

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

Bật API Google HomeGraph

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

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

Tạo khóa tài khoản dịch vụ

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

Lưu ý: Đả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 một tên miề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 Tài khoản dịch vụ > Trình tạo mã thông báo tài khoản dịch vụ.

  6. Đối với Loại khóa, hãy chọn tùy chọn JSON.

  7. Nhấp vào Tạo. Một tệp JSON chứa khoá tải xuống vào 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 cách sử dụng API devices.reportStateAndNotification. Yêu cầu JSON 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 cho sự kiện kích hoạt thông báo. eventId phải là mã nhận dạng ngẫu nhiên khác nhau mỗi khi bạn gửi 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 hiển thị thông báo. Đối tượng notifications có thể bao gồm nhiều trường tuỳ thuộc vào đặc điểm thiết bị.

Thực hiện theo một trong các đường dẫn sau để đặt trọng tải và gọi API:

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

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

HTTP

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

  1. Sử 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 nội dung Xác thực bằng tài khoản dịch vụ.
  2. Lấy mã truy cập OAuth 2.0 với 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à Thông báo:
  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 với mã thông báo trong yêu cầu POST trong giao thức HTTP của bạn vào đ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. Xem định nghĩa về 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 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 Google API Node.js cung cấp các đường liên kết cho API Home Graph.

  1. Khởi chạy dịch vụ google.homegraph bằng cách sử dụng Thông tin đăng nhập 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

HomeGraph API Client Library for 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 chạy HomeGraphApiService bằng Thông tin đăng nhập 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 nội dung phản hồi tiếp theo

Trọng tải cho phản hồi tiếp theo chứa trạng thái của yêu cầu, mã lỗi cho sự cố lỗi (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 để vẫn còn hiệu lực 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 ví dụ về trọng tải yêu cầu EXECUTE có 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 chỉ sử dụng followUpToken để xuất thông báo trên thiết bị mà người dùng đang tương tác ban đầu và không truyền đến tất cả các thiết bị của người dùng.

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

HTTP

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

  1. Sử 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 nội dung Xác thực bằng tài khoản dịch vụ.
  2. Lấy mã truy cập OAuth 2.0 với 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à Thông báo:
  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 với mã thông báo trong yêu cầu POST trong giao thức HTTP của bạn vào đ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. Xem định nghĩa về 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 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 Google API Node.js cung cấp các đường liên kết cho API Home Graph.

  1. Khởi chạy dịch vụ google.homegraph bằng cách sử dụng Thông tin đăng nhập 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

HomeGraph API Client Library for 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 chạy HomeGraphApiService bằng Thông tin đăng nhập 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ề 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ư được nêu trong Truy cập nhật ký sự kiện bằng Ghi nhật ký trên đám mây. Các nhật ký này sẽ giúp bạn kiểm tra và duy trì chất lượng của thông báo trong Hành động.

Dưới đây là giản đồ của một mục notificationLog:

Tài sản Mô tả
requestId ID 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ể cho thấy lỗi trong tải trọng thông báo. Một vài trong số này có thể chỉ có trên các Hành động chưa ra mắt trong giai đoạn phát hành chính thức.

Ví dụ về trạng thái bao gồm:

Trạng thái Mô tả
EVENT_ID_MISSING Cho biết rằng 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ị thông báo được cung cấp trong SYNC là false.
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ị thông báo trong GHA. Trạng thái này chỉ áp dụng cho những Hành động chưa phát hành phiên bản 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 Nhà/Cấu trúc. Trạng thái này chỉ áp dụng cho những Hành động chưa phát hành phiên bản chính thức.

Ngoài các trạng thái chung này có thể áp dụng cho tất cả cá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).