Chào mừng bạn đến với Trung tâm nhà phát triển Google Home, một đ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 tạo các hành động trong Bảng điều khiển Actions.

Yêu cầu đồng bộ hóa

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Đồng bộ hoá yêu cầu kích hoạt yêu cầu SYNC đến phương thức thực hiện cho bất kỳ người dùng Google nào với thiết bị có liên kết agentUserId được liên kết với họ (bạn đã gửi yêu cầu Đồng bộ hoá ban đầu). Điều này cho phép bạn cập nhật thiết bị của người dùng mà không cần hủy liên kết và liên kết lại tài khoản của họ. Tất cả người dùng liên kết với giá trị nhận dạng này sẽ nhận được yêu cầu SYNC.

Bạn phải kích hoạt một yêu cầu SYNC:

  • Nếu người dùng thêm một thiết bị mới.
  • Nếu người dùng xoá một thiết bị hiện có.
  • Nếu người dùng đổi tên một thiết bị hiện có.
  • Nếu bạn triển khai một loại thiết bị mới, đặc điểm hoặc thêm một tính năng mới của thiết bị.

Bắt đầu

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

Bật API Google HomeGraph

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

    Truy cập vào 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 một 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ừ GCP Console:

Lưu ý: Hãy đảm bảo 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 GCP Console, hãy chuyển đến trang Tạo khoá tài khoản dịch vụ.

    Chuyển đến trang tạo khoá cho 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ụ > Trình tạo mã thông báo của 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á của bạn được tải xuống máy tính.

Gọi API

HTTP

API 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. 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 Request Sync:
  5. {
      "agentUserId": "user-123"
    }
    
  6. Kết hợp JSON yêu cầu đồng bộ hóa và mã thông báo trong yêu cầu POST HTTP của bạn đến đ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 cách sử dụ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:requestSync"
    

gRPC

API 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 API biểu đồ chính.
  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 RequestSync.

Node.js

Ứng dụng Google API Node.js cung cấp các 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 xác thực mặc định của ứng dụng.
  2. Gọi phương thức requestSync bằng RequestSyncDevicesRequest. Phương thức này trả về một PromiseRequestSyncDevicesResponse trống.
const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.requestSync({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    async: false
  }
});
    

Java

HomeGraph API Client Library cho Java cung cấp các đường liên kết cho API Home Graph.

  1. Khởi động HomeGraphApiService bằng Thông tin xác thực mặc định của ứng dụng.
  2. Gọi phương thức requestSync bằng RequestSyncDevicesRequest. Phương thức này trả về một ReportStateAndNotificationResponse trống.
// 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();

// Request sync.
RequestSyncDevicesRequest request =
    new RequestSyncDevicesRequest().setAgentUserId("PLACEHOLDER-USER-ID").setAsync(false);
homegraphService.devices().requestSync(request);
    

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 Yêu cầu đồng bộ hoá. 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 máy khách 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.
  • 403 Forbidden – Máy chủ không thể xử lý yêu cầu cho agentUserId nhất định do lỗi khi làm mới mã thông báo. Hãy đảm bảo điểm cuối OAuth của bạn phản hồi chính xác để làm mới các yêu cầu mã thông báo và kiểm tra trạng thái liên kết tài khoản của người dùng.
  • 404 Not Found – Không tìm thấy tài nguyên được yêu cầu nhưng có thể sẽ có sau này. Thông thường, điều này 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 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.
  • 429 Too Many Requests – Đã vượt quá số lượng yêu cầu đồng bộ hoá đồng thời tối đa cho agentUserId. Một lệnh gọi chỉ có thể đưa ra một yêu cầu đồng bộ hoá trừ khi cờ async được đặt thành true.