Trạng thái báo cáo

Report State là một tính năng quan trọng cho phép Google HomeHành động chủ động báo cáo trạng thái mới nhất của thiết bị của người dùng trở lại Google Home Graph thay vì chờ ý định QUERY.

Report State báo cáo cho Google trạng thái của thiết bị người dùng có liên kết với agentUserId được chỉ định (được gửi trong yêu cầu SYNC ban đầu). Khi Google Assistant muốn thực hiện một hành động cần hiểu rõ trạng thái hiện tại của thiết bị, thì chỉ cần tra cứu thông tin trạng thái trong Home Graph thay vì đưa ra ý định QUERY cho nhiều đám mây của bên thứ ba trước khi đưa ra ý định EXECUTE.

Nếu không có Report State, khi có đèn của nhiều nhà cung cấp trong phòng khách, lệnh Ok Google, hãy bật đèn phòng khách sáng hơn yêu cầu phân giải nhiều ý định QUERY được gửi đến nhiều đám mây, thay vì chỉ đơn giản là tra cứu các giá trị độ sáng hiện tại dựa trên những gì đã được báo cáo trước đó. Để mang lại trải nghiệm tốt nhất cho người dùng, Assistant cần có trạng thái hiện tại của thiết bị mà không cần phải thực hiện một lượt khứ hồi đến thiết bị.

Sau SYNC ban đầu cho một thiết bị, nền tảng sẽ gửi một ý định QUERY thu thập trạng thái của thiết bị để điền sẵn Home Graph. Sau thời điểm đó, Home Graph chỉ lưu trữ trạng thái được gửi cùng với Report State.

Khi gọi Report State, hãy nhớ cung cấp dữ liệu trạng thái hoàn chỉnh cho một đặc điểm nhất định. Home Graph cập nhật trạng thái theo từng đặc điểm và ghi đè tất cả dữ liệu cho đặc điểm đó khi thực hiện lệnh gọi Report State. Ví dụ: nếu bạn đang báo cáo trạng thái cho đặc điểm StartStop, thì tải trọng cần bao gồm các giá trị cho cả isRunning và isPaused.

Bắt đầu

Để triển khai Report State, hãy làm theo các bước sau:

• Bật Google HomeGraph API
• Tạo khoá tài khoản dịch vụ
• Gọi API

Bật Google HomeGraph API

1. Trong Google Cloud Console, hãy chuyển đến trang HomeGraph API.

   Chuyển đến 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ụ

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

1. Trong Google Cloud Console, hãy chuyển đến trang Tài khoản dịch vụ.

   Chuyển đến trang Tài khoản dịch vụ.

   Bạn có thể cần chọn một dự án trước khi được chuyển đến trang Tài khoản dịch vụ.

2. Nhấp vào addTạo tài khoản dịch vụ.

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ã nhận dạng.

5. Trong trường Mô tả tài khoản dịch vụ, hãy nhập nội dung mô tả.

6. Nhấp vào Tạo và tiếp tục.

7. Trong trình đơn thả xuống Role (Vai trò), hãy chọn Service Accounts (Tài khoản dịch vụ) > Service Account OpenID Connect Identity Token Creator (Trình tạo mã thông báo danh tính OpenID Connect của tài khoản dịch vụ).

8. Nhấp vào Tiếp tục.

9. Nhấp vào Xong.

10. Chọn tài khoản dịch vụ bạn vừa tạo trong danh sách tài khoản dịch vụ rồi chọn Quản lý khoá trong trình đơn more_vert Thao tác.

11. Chọn Thêm khoá > Tạo khoá mới.

12. Đối với Loại khoá, hãy chọn mục JSON.

13. Nhấp vào Tạo. Một tệp JSON chứa khoá của bạn sẽ được tải xuống máy tính.

Gọi API

Chọn một mục trong các thẻ bên dưới:

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
          }
        }
      }
    }
  }
});
    

  // 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).execute();
}
    

Trạng thái báo cáo thử nghiệm

Để chuẩn bị cho việc tích hợp Cloud-to-cloud được chứng nhận, bạn cần phải thử nghiệm Report State.

Để làm việc này, bạn nên sử dụng công cụ Trình xem Home Graph, một ứng dụng web độc lập không cần tải xuống hoặc triển khai.

Trang tổng quan Report State vẫn hoạt động nhưng không còn được dùng và không còn được hỗ trợ.

Trang tổng quan về trạng thái báo cáo

Điều kiện tiên quyết

Trước khi có thể thử nghiệm việc tích hợp Cloud-to-cloud, bạn cần có Khoá tài khoản dịch vụ và agentUserId. Nếu bạn đã có Khoá tài khoản dịch vụ, hãy agentUserId xem phần Triển khai Trang tổng quan Report State.

Triển khai trang tổng quan Trạng thái báo cáo

Sau khi bạn có Khoá tài khoản dịch vụ và Mã nhận dạng người dùng của nhân viên hỗ trợ cho dự án của mình, hãy tải xuống và triển khai phiên bản mới nhất từ Report State Trang tổng quan. Sau khi tải phiên bản mới nhất xuống, hãy làm theo hướng dẫn trong tệp README.MD đi kèm.

Sau khi bạn triển khai trang tổng quan Report State, hãy truy cập vào trang tổng quan này qua URL sau (thay thế your_project_id bằng mã dự án của bạn):

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

Trên trang tổng quan, hãy làm như sau:

• Chọn tệp khoá tài khoản của bạn
• Thêm agentUserId

Sau đó, hãy nhấp vào Danh sách.

Tất cả thiết bị của bạn đều được liệt kê. Sau khi danh sách được điền sẵn, bạn có thể sử dụng nút Refresh (Làm mới) để cập nhật trạng thái thiết bị. Nếu có thay đổi về trạng thái thiết bị, hàng sẽ được đánh dấu bằng màu xanh lục.

Báo cáo sự khác biệt về trạng thái

Độ chính xác của trạng thái báo cáo dựa trên truy vấn đo lường mức độ khớp giữa trạng thái báo cáo mới nhất của một thiết bị với trạng thái của thiết bị khi người dùng truy vấn. Giá trị này dự kiến sẽ ở mức 99,5%. Để biết thêm thông tin chi tiết về trạng thái hiện tại của Độ chính xác của trạng thái báo cáo của dự án, hãy xem Tình trạng thiết bị – Độ chính xác của trạng thái. Bạn cũng có thể xem thông tin chi tiết về Nhật ký chênh lệch trạng thái báo cáo trong Trình khám phá nhật ký.

Sau đây là ví dụ về Nhật ký về sự khác biệt trong trạng thái báo cáo:

{
  "insertId": "abcdefgh",
  "jsonPayload": {
    "reportStateLog": {
      "result": "INACCURATE",
      "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_INACCURATE",
      "isOffline": false,
      "queriedTime": "2026-01-17T03:22:01.732938Z",
      "reportedTime": "2024-11-30T15:24:34.052751Z",
      "agentId": "google-smart-home-agent-id-example",
      "requestId": "84920571364829501736",
      "queryReportStateDifferences": {
        "queryState": "on_off \t {\n  on: true\n}\n",
        "reportState": "on_off \t {\n  on: false\n}\n"
      },
      "traitName": "TRAIT_ON_OFF",
      "snapshotTime": "2026-01-17T03:22:01.732938Z",
      "isMissingField": false,
      "deviceType": "action.devices.types.OUTLET",
      "stateName": "on",
      "deviceId": "sample-device-id",
      "accuracy": "INACCURATE"
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "google-smart-home-agent-id-example"
    }
  },
  "timestamp": "2026-01-17T07:16:13.712708257Z",
  "severity": "ERROR",
  "logName": "projects/google-smart-home-agent-id-example/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2026-01-17T07:16:13.712708257Z"
}

Định nghĩa về các trường trong Nhật ký về sự khác biệt về trạng thái báo cáo

Phản hồi lỗi

Bạn có thể nhận được một trong các phản hồi lỗi sau đây khi gọi Report State. Những phản hồi này có dạng mã trạng thái HTTP.

400 Yêu cầu không hợp lệ

Máy chủ không thể xử lý yêu cầu do ứng dụng gửi vì cú pháp không hợp lệ. Các nguyên nhân phổ biến bao gồm JSON không đúng định dạng hoặc sử dụng null thay vì "" cho giá trị chuỗi.

404 Không tìm thấy

Không tìm thấy tài nguyên được yêu cầu nhưng có thể tài nguyên này sẽ có trong tương lai. Thông thường, điều này có nghĩa là chúng tôi không tìm thấy thiết bị được yêu cầu. Điều này cũng có thể có nghĩa là tài khoản người dùng không được liên kết với Google hoặc chúng tôi đã nhận được một agentUserId không hợp lệ. Đảm bảo rằng agentUserId khớp với giá trị được cung cấp trong phản hồi SYNC và bạn đang xử lý đúng cách ý định DISCONNECT.

Khi lệnh gọi ReportState không thành công và có lỗi 404 NOT_FOUND, điều này cho biết có sự không khớp đồng bộ hoá giữa đám mây của bạn và Home Graph. Điều này có thể xảy ra nếu một thiết bị bị xoá khỏi Home Graph hoặc nếu người dùng huỷ liên kết tài khoản của họ.

Để xử lý lỗi 404 từ Report State, hãy làm theo quy trình sau:

1. Kiểm tra trạng thái tài khoản người dùng: Gọi devices.sync cho agentUserId đã trả về lỗi 404. Việc này giúp xác định xem lỗi xảy ra cho toàn bộ tài khoản người dùng hay một thiết bị cụ thể.
   • Nếu SYNC trả về lỗi 404, thì tài khoản người dùng không còn được liên kết với Google nữa. Ngừng gửi Report State và Request Sync cho thiết bị của người dùng này.
   • Nếu SYNC trả về 200 OK, thì tài khoản người dùng vẫn được liên kết, nghĩa là lỗi 404 là lỗi dành riêng cho thiết bị.
2. Đối chiếu danh sách thiết bị: Nếu SYNC trả về 200 OK, bạn cần xác định(các) thiết bị nào không còn được Google biết đến. Bạn nên so sánh danh sách thiết bị mà Google có cho người dùng với cơ sở dữ liệu thiết bị của bạn, đồng thời xác định những thiết bị trong hệ thống của bạn không có trong danh sách của Google. Nếu một thiết bị cần được đồng bộ hoá với Google nhưng chưa được chia sẻ với Google, hãy sử dụng SYNC để đảm bảo thiết bị được đồng bộ hoá với Google. Nếu một thiết bị cần được huỷ liên kết khỏi Google, hãy ngừng báo cáo trạng thái cho thiết bị cụ thể đó và tiếp tục báo cáo cho các thiết bị hợp lệ khác trong agentUserId đó.

Báo cáo trạng thái trực tuyến và ngoại tuyến

"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }