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 trên thiết bị của người dùng cho Google Home Graph thay vì chờ ý định QUERY.

Report State báo cáo cho Google trạng thái thiết bị của người dùng và agentUserId được chỉ định liên kết với 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 thao tác yêu cầu 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 đèn từ nhiều nhà cung cấp trong phòng khách cung cấp, 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 tới nhiều đám mây, thay vì chỉ tra cứu giá trị độ sáng hiện tại dựa trên những gì đã 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 yêu cầu thiết bị di chuyển khứ hồi.

Theo 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 hoàn chỉnh cho một trait 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 trait đó 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 trait StartStop, 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

  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 API

Chọn một lựa chọn trong các thẻ bên dưới:

HTTP

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
  3. Tạo yêu cầu JSON bằng agentUserId. Dưới đây là yêu cầu JSON mẫu cho Trạng thái và Thông báo báo cáo:
    4. {
  "requestId": "123ABC",
  "agentUserId": "user-123",
  "payload": {
    "devices": {
      "states": {
        "light-123": {
          "on": true
        }
      }
    }
  }
}
  4. Kết hợp Trạng thái báo cáo 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ử:
    5. 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

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 Home Graph API.
  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',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        states: {
          "PLACEHOLDER-DEVICE-ID": {
            on: true
          }
        }
      }
    }
  }
});

Java

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

  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 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

Các công cụ nên dùng cho nhiệm vụ này

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

Để làm điều 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òn hoạt động nhưng không còn được dùng và không còn được hỗ trợ nữa.

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

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

Để có thể kiểm thử thao tác, bạn cần có Khoá tài khoản dịch vụ và agentUserId của mình. Nếu bạn đã có Khoá 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ó 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, hãy tải và triển khai phiên bản mới nhất từ Trang tổng quan Report State. 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 trang tổng quan từ URL sau (thay 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êmAgentUserId 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ể 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 này 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 xuất hiện ở 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 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 tìm thấy tài nguyên bạn yêu cầu nhưng có thể sẽ sử dụng đượ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ị mà bạn 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ệ. Đả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 các ý định DISCONNECT.
Trước
Yêu cầu đồng bộ hoá
Tiếp
Gửi thông báo