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

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

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

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

Sau SYNC ban đầu của 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ị nhằm điền Home Graph. Sau thời điểm đó, Home Graph chỉ lưu trữ trạng thái được gửi bằng Report State.

Khi gọi Report State, hãy nhớ cung cấp dữ liệu trạng thái đầy đủ cho một trait cụ thể. Home Graph cập nhật trạng thái trên cơ sở mỗi trait 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ì trọng tải cần phải 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 API Google HomeGraph
• Tạo khoá tài khoản dịch vụ
• Gọi API

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:

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 API

Chọn một tùy chọn từ các tab 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);
}
    

Trạng thái báo cáo kiểm tra

Để sẵn sàng cho hành động chứng nhận, bạn cần phải kiểm thử Report State.

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

Trang tổng quan Report State vẫn có sẵn, nhưng đã ngừng hoạt động và không còn được hỗ trợ.

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

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

Trước khi có thể thử nghiệm hành động, bạn cần có Khóa tài khoản dịch vụ và agentUserId của mình. Nếu bạn đã có Khóa tài khoản dịch vụ và agentUserId, hãy 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ó Khóa tài khoản dịch vụ và Mã nhận dạng người dùng đại lý 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 trên 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 trang tổng quan từ URL sau (thay thế your_project_id bằng mã dự án):

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

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

• Chọn tệp khóa tài khoản của bạn
• Thêm nhân viên hỗ trợ của bạn

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

Tất cả thiết bị của bạn đều có trong danh sách. 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 của thiết bị. Nếu có thay đổi về trạng thái thiết bị, hàng sẽ có màu xanh lục.

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 Bad Request – Máy chủ không thể xử lý yêu cầu do ứng dụng gửi đi do 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 Not Found – Không thể tìm thấy tài nguyên đã yêu cầu nhưng có thể có trong tương lai. Thông thường, điều này có nghĩa là chúng tôi không thể 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 chưa 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ị đã cung cấp trong phản hồi SYNC và bạn đang xử lý đúng các ý định DISCONNECT.