Tworzenie urządzeń i zarządzanie nimi

Z tego przewodnika dowiesz się, jak tworzyć urządzenia, nimi zarządzać i je usuwać. Prawidłowe zarządzanie urządzeniami pomaga zapewnić użytkownikom wygodę i efektywnie korzystać z interfejsu Ambient API.

Tworzenie urządzeń

Gdy użytkownik pomyślnie uwierzytelni się za pomocą protokołu OAuth 2.0 dla aplikacji na telewizory i urządzenia z ograniczonymi możliwościami wprowadzania danych utwórz urządzenie na jego koncie Zdjęć Google.

Gdy Twoja aplikacja pomyślnie utworzy urządzenie za pomocą metody devices.create, interfejs Ambient API zwróci obiekt AmbientDevice, który zawiera wygenerowany przez Google id. Bezpiecznie przechowuj ten id i powiąż go z użytkownikami.

Usprawnione tworzenie urządzeń za pomocą protokołu OAuth

Interfejs Ambient API oferuje uproszczony proces OAuth. Przekazując dodatkowy parametr state w początkowym żądaniu OAuth i wywołując metodę devices.create z pasującym parametrem requestId, możesz powiązać proces tworzenia urządzenia bezpośrednio z procesem logowania użytkownika, co uprości korzystanie z aplikacji, ponieważ użytkownik będzie musiał zeskanować mniej kodów QR.

Więcej informacji i przykład znajdziesz w przewodniku Uproszczony proces uwierzytelniania w interfejsie Ambient API.

Limity urządzeń

Twoja aplikacja może utworzyć maksymalnie 100 urządzeń na użytkownika. Jeśli ten limit zostanie przekroczony, interfejs API zwróci błąd RESOURCE_EXHAUSTED.

Zarządzanie urządzeniami

Gdy urządzenie zostanie utworzone i połączone z kontem Zdjęć Google użytkownika, może być konieczne zarządzanie jego cyklem życia.

Pobieranie urządzeń

Aby pobrać informacje o konkretnym urządzeniu, użyj metody devices.get z jego unikalnym id. Jest to przydatne do sprawdzania stanu urządzenia, np. czy mediaSourcesSet ma wartość true.

Aktualizowanie urządzeń

Za pomocą metody devices.patch możesz zaktualizować niektóre właściwości istniejącego urządzenia, np. jego nazwę wyświetlaną. Umożliwia to użytkownikom personalizowanie urządzeń i ułatwia ich identyfikowanie w Zdjęciach Google.

Usuwanie urządzeń

Wdroż strategię usuwania urządzeń, aby zapewnić prawidłowe czyszczenie i kontrolę użytkownika. Urządzenie możesz usunąć za pomocą metody devices.delete.

Oto kilka scenariuszy usuwania urządzeń:

  • Odłączenie użytkownika: jeśli użytkownik odłączy Twoją aplikację od swojego konta Zdjęć Google, musisz usunąć odpowiednie urządzenie.
  • Osierocone urządzenia: jeśli utracisz id, ale nadal masz requestId użyty podczas tworzenia, możesz użyć requestId z devices.delete, aby usunąć osierocone urządzenie. Pomaga to zapobiegać przypadkowym duplikatom i utrzymywać konto użytkownika w czystości.

Ważne kwestie i sprawdzone metody

  • Cykl życia urządzenia i autoryzacja użytkownika: musisz zarządzać cyklem życia urządzeń i tokenami autoryzacji użytkownika. Zastanów się, jak długo urządzenia pozostają aktywne i jak będziesz obsługiwać odświeżanie tokenów lub ponowną autoryzację, jeśli urządzenie stanie się nieaktywne lub jego token wygaśnie.
  • Obsługa błędów: wdróż niezawodną obsługę błędów w przypadku wszystkich wywołań interfejsu API związanych z urządzeniami. Przygotuj się na takie scenariusze jak:
    • NOT_FOUND: jeśli urządzenie nie istnieje lub nie należy do użytkownika.
    • RESOURCE_EXHAUSTED: jeśli przekroczysz limit urządzeń.
    • ALREADY_EXISTS: jeśli spróbujesz utworzyć urządzenie z parametrem requestId , który już istnieje.

Następne kroki

  • Przykładowa aplikacja: nasza przykładowa aplikacja zawiera przykład tworzenia urządzenia i pracy z danymi odpowiedzi. Więcej informacji znajdziesz w funkcji createDevice.
  • Dokumentacja: zapoznaj się z obszerną dokumentacją dotyczącą urządzeń aby uzyskać szczegółowe informacje o wszystkich dostępnych metodach, parametrach żądań i odpowiedzi oraz kodach błędów.
  • Wyświetlanie i pobieranie elementów multimedialnych: gdy utworzysz urządzenia i będziesz nimi zarządzać, dowiedz się, jak wyświetlać i pobierać elementy multimedialne, aby wyświetlać je na urządzeniach.