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 người dùng mượt mà và sử dụng hiệu quả Ambient API.

Tạo thiết bị

Sau khi người dùng xác thực thành công bằng luồng OAuth 2.0 cho TV và ứng dụng thiết bị có phương thức nhập 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, Ambient API sẽ trả về một đối tượng AmbientDevice bao gồm id do Google tạo. Lưu trữ id này một cách an toàn và liên kết với người dùng.

Tạo thiết bị đơn giản bằng OAuth

Ambient API cung cấp một quy trình OAuth đơn giản có thể tạo thiết bị đồng thời với việc xác thực người dùng. Bằng cách truyền tham số state bổ sung trong yêu cầu OAuth ban đầu, bạn có thể liên kết trực tiếp quy trình tạo thiết bị với luồng đăng nhập của người dùng, đơ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 chi tiết và ví dụ, hãy xem hướng dẫn Quy trình xác thực đơn giản cho API môi trường xung quanh.

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 riêng biệt. Điều này rất hữu ích cho việc kiểm tra trạng thái của thiết bị, chẳng hạn như liệu 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 nhất định của thiết bị hiện có, chẳng hạn như tên hiển thị của thiết bị, bằng cách sử dụ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 nhận dạng thiết bị trong Google Photos.

Xóa thiết bị

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

Hãy xem xét 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, bạn nên xoá thiết bị tương ứng.
  • Thiết bị không có chủ sở hữu: Nếu mất dấu vết của một id nhưng vẫn có requestId được sử dụng trong quá trình tạo, bạn có thể sử dụng requestId với devices.delete để xoá một thiết bị không có chủ sở hữu. Đ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 luôn sạch sẽ.

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

  • Vòng đời thiết bị và uỷ quyền 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 người dùng. Hãy cân nhắc thời gian thiết bị vẫn hoạt động và cách bạn sẽ 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 tính năng xử lý lỗi mạnh mẽ cho tất cả lệnh gọi API liên quan đến thiết bị. Hãy chuẩn bị sẵn sàng cho các tình huống 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 một ví dụ về cách tạo thiết bị và xử lý 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 lại 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, tham số yêu cầu và phản hồi cũng như mã lỗi hiện có.
  • Liệt kê và truy xuất mục nội dung nghe nhìn: Sau khi bạn tạo và quản lý thiết bị, hãy tìm hiểu cách liệt kê và truy xuất mục nội dung nghe nhìn để hiển thị trên các thiết bị đó.