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 zapewnia użytkownikom płynne działanie i skuteczne korzystanie z interfejsu Ambient API.

Tworzenie urządzeń

Po uwierzytelnieniu użytkownika za pomocą ścieżki OAuth 2.0 na potrzeby aplikacji na urządzenia z ograniczoną liczbą wejść i telewizory utwórz urządzenie na jego koncie Zdjęć Google.

Gdy aplikacja utworzy urządzenie za pomocą metody devices.create, interfejs Ambient API zwróci obiekt AmbientDevice, który zawiera wygenerowany przez Google identyfikator id. Bezpiecznie przechowuj te id i połącz je z użytkownikami.

Ważne: zapisz id. Jeśli nie zapiszesz wygenerowanego przez Google id, nie będziesz mieć możliwości późniejszego odzyskania urządzenia ani zarządzania nim. Może to spowodować pojawienie się na kontach użytkowników w Google Photos urządzeń bez właściciela, do których aplikacja nie będzie mieć dostępu ani których nie będzie można wyczyścić.

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

Interfejs API Ambient oferuje uproszczony proces OAuth, który może tworzyć urządzenie jednocześnie z uwierzytelnianiem użytkownika. Przekazując dodatkowy parametr state w pierwszym żądaniu OAuth, możesz połączyć proces tworzenia urządzenia bezpośrednio z procesem logowania użytkownika, upraszczając w ten sposób obsługę poprzez zmniejszenie liczby kodów QR, które użytkownik musi zeskanować.

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

Limity urządzeń

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

Po utworzeniu urządzenia i połączeniu go 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 użyciem unikalnego identyfikatora id. Jest to przydatne do sprawdzania stanu urządzenia, na przykład tego, czy mediaSourcesSet ma wartość Prawda.

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ą na ekranie. Dzięki temu użytkownicy mogą personalizować swoje urządzenia i łatwiej je rozpoznawać w Zdjęciach Google.

Uwaga: dobrym rozwiązaniem jest umożliwienie użytkownikowi nadania nazwy urządzeniu przed jego utworzeniem. Dzięki temu użytkownik łatwiej rozpozna swoje urządzenie podczas wybierania multimediów na koncie Zdjęć Google.

Usuń urządzenia

Wdrocz strategię usuwania urządzeń, aby zapewnić odpowiednie oczyszczanie i kontrolę użytkowników. Urządzenie możesz usunąć, korzystając z metody devices.delete.

Rozważ te scenariusze usuwania urządzeń:

• Odłączenie przez użytkownika: jeśli użytkownik odłączy Twoją aplikację od swojego konta Zdjęć Google, powinieneś usunąć odpowiednie urządzenie.
• Urządzenia obce: jeśli tracisz kontrolę nad id, ale nadal masz requestId użyte podczas tworzenia, możesz użyć requestId z devices.delete, aby usunąć obce urządzenie. Pomaga to uniknąć przypadkowych duplikatów i utrzymuje 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 mają pozostawać aktywne i jak będziesz zarządzać odświeżaniem tokenów lub ponownym autoryzowaniem, jeśli urządzenie stanie się nieaktywne lub jego token wygaśnie.
• Obsługa błędów: zaimplementuj niezawodną obsługę błędów we wszystkich wywołaniach interfejsu API związanych z urządzeniami. Przygotuj się na takie scenariusze:
  • 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 próbujesz utworzyć urządzenie o identyfikatorze 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 pełną dokumentacją na temat urządzeń, aby uzyskać szczegółowe informacje o dostępnych metodach, parametrach żądań i odpowiedzi oraz kodach błędów.
• Wyświetlanie listy multimediów i pobieranie multimediów: gdy utworzysz urządzenia i zaczniesz nimi zarządzać, dowiedz się, jak wyświetlać listę multimediów i pobierać multimediów.