Membuat dan mengelola perangkat

Panduan ini membahas cara membuat, mengelola, dan menghapus perangkat. Pengelolaan perangkat yang tepat membantu menciptakan pengalaman pengguna yang lancar dan penggunaan Ambient API yang efisien.

Membuat Perangkat

Setelah pengguna berhasil diautentikasi menggunakan alur OAuth 2.0 untuk Aplikasi TV dan Perangkat Input Terbatas, buat perangkat di akun Google Foto mereka.

Saat aplikasi Anda berhasil membuat perangkat menggunakan metode devices.create, Ambient API akan menampilkan objek AmbientDevice yang menyertakan id yang dibuat Google. Simpan id ini dengan aman dan kaitkan dengan pengguna Anda.

Penting: Simpan id. Jika tidak menyimpan id yang dibuat Google, Anda tidak akan dapat mengambil atau mengelola perangkat nanti. Hal ini dapat menyebabkan perangkat yang tidak ada pemiliknya di akun Google Foto pengguna, yang tidak dapat diakses atau dibersihkan oleh aplikasi Anda.

Pembuatan Perangkat yang Disederhanakan dengan OAuth

Ambient API menawarkan alur OAuth yang disederhanakan yang dapat membuat perangkat secara bersamaan dengan autentikasi pengguna. Dengan meneruskan parameter state tambahan dalam permintaan OAuth awal, Anda dapat menautkan proses pembuatan perangkat langsung ke alur login pengguna, sehingga menyederhanakan pengalaman pengguna dengan mengurangi jumlah kode QR yang perlu mereka pindai.

Untuk mengetahui detail selengkapnya dan contoh, lihat panduan Alur autentikasi yang disederhanakan untuk Ambient API.

Batas Perangkat

Aplikasi Anda dapat membuat hingga 100 perangkat per pengguna. Jika batas ini terlampaui, API akan menampilkan error RESOURCE_EXHAUSTED.

Mengelola Perangkat

Setelah perangkat dibuat dan ditautkan ke akun Google Foto pengguna, Anda mungkin perlu mengelola siklus prosesnya.

Mengambil Perangkat

Untuk mengambil informasi tentang perangkat tertentu, gunakan metode devices.get dengan id uniknya. Hal ini berguna untuk memeriksa status perangkat, seperti apakah mediaSourcesSet benar.

Memperbarui Perangkat

Anda dapat memperbarui properti tertentu dari perangkat yang ada, seperti nama layarnya, menggunakan metode devices.patch. Hal ini memungkinkan pengguna mempersonalisasi perangkat mereka dan mempermudah identifikasi dalam Google Foto.

Catatan: Praktik yang baik adalah menawarkan kesempatan kepada pengguna untuk memberi nama perangkat mereka sebelum membuatnya. Hal ini akan mempermudah pengguna untuk mengenali perangkat mereka saat memilih item media di akun Google Foto mereka.

Hapus Perangkat

Terapkan strategi untuk menghapus perangkat guna pembersihan dan kontrol pengguna yang tepat. Anda dapat menghapus perangkat menggunakan metode devices.delete.

Pertimbangkan skenario berikut untuk menghapus perangkat:

• Putus koneksi pengguna: Jika pengguna memutuskan koneksi aplikasi Anda dari akun Google Foto mereka, Anda harus menghapus perangkat yang sesuai.
• Perangkat Yatim: Jika Anda kehilangan id, tetapi masih memiliki requestId yang digunakan selama pembuatan, Anda dapat menggunakan requestId dengan devices.delete untuk menghapus perangkat yatim. Tindakan ini membantu mencegah duplikat yang tidak disengaja dan menjaga akun pengguna tetap bersih.

Pertimbangan Penting dan Praktik Terbaik

• Siklus proses perangkat dan otorisasi pengguna: Anda harus mengelola siklus proses perangkat dan token otorisasi pengguna. Pertimbangkan berapa lama perangkat tetap aktif dan cara Anda menangani pembaruan token atau otorisasi ulang jika perangkat menjadi tidak aktif atau tokennya habis masa berlakunya.
• Penanganan Error: Terapkan penanganan error yang andal untuk semua panggilan API terkait perangkat. Bersiaplah untuk skenario seperti:
  • NOT_FOUND: Jika perangkat tidak ada atau tidak dimiliki oleh pengguna.
  • RESOURCE_EXHAUSTED: Jika Anda melebihi batas perangkat.
  • ALREADY_EXISTS: Jika Anda mencoba membuat perangkat dengan requestId yang sudah ada.

Langkah Berikutnya

• Contoh Aplikasi: Contoh aplikasi kami menyertakan contoh pembuatan perangkat dan penggunaan data respons. Lihat fungsi createDevice untuk mengetahui info selengkapnya.
• Dokumentasi Referensi: Tinjau dokumen referensi yang komprehensif tentang perangkat untuk mengetahui informasi mendetail tentang semua metode yang tersedia, parameter permintaan dan respons, serta kode error.
• Mencantumkan dan mengambil item media: Setelah membuat dan mengelola perangkat, pelajari cara mencantumkan dan mengambil item media untuk ditampilkan di perangkat.