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 trạng thái mới nhất của thiết bị của người dùng về cho 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ị 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 Google Assistant muốn thực hiện một hành động yêu cầu phải hiểu trạng thái hiện tại của thiết bị, ứng dụng 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, do ánh sáng của nhiều nhà cung cấp trong phòng khách được cung cấp, lệnh Ok Google, làm sáng phòng khách của tôi yêu cầu phải giải quyết nhiều ý định QUERY được gửi đến nhiều đám mây, thay vì chỉ cần tra cứu giá trị độ sáng hiện tại dựa trên những gì đã báo cáo trước đó. Để mang lại 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 yêu cầu phải đi 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 vào 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 nhất định. Home Graph cập nhật các trạng thái theo từng giai đoạn và ghi đè mọi 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 tính năng 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.

   Truy cập trang API HomeGraph
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 những hướng dẫn sau để tạo khoá tài khoản dịch vụ trên 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 Tài khoản dịch vụ, hãy chọn 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 Tài khoản dịch vụ > 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 JSON.

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

Gọi API

Chọn một tuỳ chọn 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);
}
    

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

Để chuẩn bị hành động của bạn cho quy trình chứng nhận, bạn cần kiểm thử Report State.

Để làm 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 của Report State vẫn có sẵn nhưng đã ngừng hoạt động và không còn được hỗ trợ nữa.

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

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

Để có thể thử nghiệm hành động của mình, 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ụ và agentUserId, hãy xem phần Triển khai Report State Trang tổng quan.

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 tác nhân cho dự án, hãy tải và triển khai phiên bản mới nhất trên Report State Trang tổng quan. Sau khi bạn 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 từ 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
• Thêm agentUserId của bạn

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

Mọi 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 thiết bị. Nếu có sự thay đổi về trạng thái thiết bị, hàng đó sẽ được đánh dấu bằng 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. Các 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 do cú pháp không hợp lệ. Các nguyên nhân thường gặp bao gồm JSON không đúng định dạng hoặc sử dụng null thay vì "" cho một giá trị chuỗi.
• 404 Not Found – Không thể tìm thấy tài nguyên bạn yêu cầu nhưng có thể sẽ truy cập đượ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 được liên kết với Google hoặc chúng tôi đã nhận được agentUserId không hợp lệ. Hãy đả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ý ý định DISCONNECT đúng cách.