Tạo và quản lý thiết bị

Hướng dẫn này trình bày cách tạo, quản lý và xoá thiết bị. Việc quản lý thiết bị đúng cách giúp tạo ra trải nghiệm mượt mà cho người dùng và sử dụng API Ambient một cách hiệu quả.

Tạo thiết bị

Sau khi người dùng xác thực thành công bằng quy trình OAuth 2.0 cho Ứng dụng trên TV và Thiết bị có đầu vào hạn chế, hãy tạo một thiết bị trong tài khoản Google Photos của họ.

Khi ứng dụng của bạn tạo thành công một thiết bị bằng phương thức devices.create, API Ambient sẽ trả về một đối tượng AmbientDevice bao gồm id do Google tạo. Hãy lưu trữ id này một cách an toàn và liên kết với người dùng của bạn.

Quy trình tạo thiết bị được đơn giản hoá bằng OAuth

API Ambient cung cấp một quy trình OAuth được đơn giản hoá. Bằng cách truyền tham số state bổ sung trong yêu cầu OAuth ban đầu và gọi devices.create bằng requestId phù hợp, bạn có thể liên kết trực tiếp quy trình tạo thiết bị với quy trình đăng nhập của người dùng, giúp đơn giản hoá trải nghiệm người dùng bằng cách giảm số lượng mã QR mà họ cần quét.

Để biết thêm thông tin và ví dụ, hãy xem hướng dẫn Quy trình xác thực được đơn giản hoá cho API Ambient.

Giới hạn thiết bị

Ứng dụng của bạn có thể tạo tối đa 100 thiết bị cho mỗi người dùng. Nếu vượt quá giới hạn này, API sẽ trả về lỗi RESOURCE_EXHAUSTED.

Quản lý thiết bị

Sau khi tạo và liên kết một thiết bị với tài khoản Google Photos của người dùng, bạn có thể cần quản lý vòng đời của thiết bị đó.

Truy xuất thiết bị

Để truy xuất thông tin về một thiết bị cụ thể, hãy sử dụng phương thức devices.get với id duy nhất của thiết bị đó. Điều này hữu ích khi kiểm tra trạng thái của thiết bị, chẳng hạn như mediaSourcesSet có đúng hay không.

Cập nhật thiết bị

Bạn có thể cập nhật một số thuộc tính của thiết bị hiện có, chẳng hạn như tên hiển thị, bằng phương thức devices.patch. Điều này cho phép người dùng cá nhân hoá thiết bị của họ và giúp họ dễ dàng xác định thiết bị trong Google Photos hơn.

Xoá thiết bị

Triển khai chiến lược xoá thiết bị để dọn dẹp đúng cách và kiểm soát người dùng. Bạn có thể xoá một thiết bị bằng phương thức devices.delete.

Hãy cân nhắc các trường hợp sau đây để xoá thiết bị:

  • Người dùng ngắt kết nối: Nếu người dùng ngắt kết nối ứng dụng của bạn khỏi tài khoản Google Photos của họ, bạn nên xoá thiết bị tương ứng.
  • Thiết bị không được liên kết: Nếu bạn không theo dõi được id nhưng vẫn có requestId đã dùng trong quá trình tạo, bạn có thể dùng requestId với devices.delete để xoá thiết bị không được liên kết. Điều này giúp ngăn chặn các bản sao trùng lặp vô tình và giữ cho tài khoản của người dùng được sạch sẽ.

Những điểm cần cân nhắc quan trọng và các phương pháp hay nhất

  • Vòng đời của thiết bị và quá trình uỷ quyền cho người dùng: Bạn cần quản lý vòng đời của thiết bị và mã thông báo uỷ quyền cho người dùng. Hãy cân nhắc thời gian thiết bị hoạt động và cách bạn xử lý việc làm mới mã thông báo hoặc uỷ quyền lại nếu thiết bị không hoạt động hoặc mã thông báo của thiết bị hết hạn.
  • Xử lý lỗi: Triển khai biện pháp xử lý lỗi hữu ích cho tất cả các lệnh gọi API liên quan đến thiết bị. Hãy chuẩn bị cho các trường hợp như:
    • NOT_FOUND: Nếu thiết bị không tồn tại hoặc không thuộc sở hữu của người dùng.
    • RESOURCE_EXHAUSTED: Nếu bạn vượt quá giới hạn thiết bị.
    • ALREADY_EXISTS: Nếu bạn cố gắng tạo một thiết bị có requestId đã tồn tại.

Các bước tiếp theo

  • Ứng dụng mẫu: Ứng dụng mẫu của chúng tôi bao gồm ví dụ về cách tạo thiết bị và làm việc với dữ liệu phản hồi. Hãy xem hàm createDevice để biết thêm thông tin.
  • Tài liệu tham khảo: Xem tài liệu tham khảo toàn diện về thiết bị để biết thông tin chi tiết về tất cả các phương thức hiện có, tham số yêu cầu và phản hồi cũng như mã lỗi.
  • Liệt kê và truy xuất các mục nội dung nghe nhìn: Sau khi tạo và quản lý thiết bị, hãy tìm hiểu cách liệt kê và truy xuất các mục nội dung nghe nhìn để hiển thị trên thiết bị.