Korzystanie z interfejsu Ambient API

Interfejs Ambient API umożliwia aplikacji łączenie urządzeń obsługujących tryb nieaktywny z kontem Zdjęć Google użytkownika i wyświetlanie wybranych zdjęć.

Przepływ danych w ramach interfejsu Ambient API

Oto jak Ambient API łączy urządzenie, a następnie pobiera i wyświetla elementy multimedialne:

  1. Sprawdź, czy istnieje już urządzenie (zalecane): przed utworzeniem nowego urządzenia zalecamy sprawdzenie, czy urządzenie dla bieżącego użytkownika już istnieje. Aplikacja powinna utrzymywać mapowanie między użytkownikiem wewnętrznym a deviceId dostarczonym przez Google dla wszystkich urządzeń utworzonych przez użytkownika za pomocą aplikacji. Jeśli dla użytkownika zostanie znaleziony deviceId, możesz odświeżyć jego token autoryzacji (w razie potrzeby).

  2. Rozpocznij autoryzację OAuth 2.0 (i opcjonalnie utwórz urządzenie): rozpocznij proces OAuth 2.0 na potrzeby telewizorów i urządzeń z ograniczonym wejściem, prosząc o kod autoryzacji.

  3. Tworzenie nowego urządzenia: aplikacja tworzy urządzenie na koncie Google Photos użytkownika, wywołując funkcję CreateDevice i podając prawidłowy identyfikator UUID w wersji 4.

    Po utworzeniu urządzenia interfejs API zwróci obiekt AmbientDevice zawierający przypisany przez Google identyfikator deviceId. Twoja aplikacja musi przechowywać te deviceId i kojarzyć je z użytkownikami.

  4. Wyświetlanie settingsUri: obiekt AmbientDevice zawiera element settingsUri. Udostępnij ten identyfikator URI użytkownikowi, zwykle w postaci kodu QR, który użytkownik może zeskanować za pomocą urządzenia mobilnego. Ten identyfikator URI kieruje użytkownika do aplikacji Zdjęcia Google, w której może skonfigurować źródła multimediów (np. albumy), które chce wyświetlać na urządzeniu z funkcją wygaszacza.

  5. Ankieta mediaSourcesSet: aplikacja powinna okresowo wywoływać metodę GetDevice, podając deviceId, aby sprawdzić stan urządzenia peryferyjnego. Sprawdź pole mediaSourcesSet w odpowiedzi AmbientDevice. Początkowo ma wartość fałsz.

    Gdy użytkownik wybierze źródła multimediów w aplikacji Zdjęcia Google, to pole zmieni się na „true” (prawda).

    Odpowiedź AmbientDevice zawiera pollingConfig z pollInterval, który powinien służyć jako wskazówka dotycząca częstotliwości ankietowania.

  6. Pobieranie elementów multimedialnych: gdy mediaSourcesSet zwróci wartość „prawda”, aplikacja może zacząć pobierać elementy multimedialne wybrane przez użytkownika.

    Wywołaj metodę ListMediaItems, podając parametr deviceId. Interfejs API zwróci obiekt ListMediaItemsResponse zawierający listę obiektów AmbientMediaItem. Każdy element AmbientMediaItem zawiera szczegóły, takie jak id, createTime i obiekt MediaFile z dodatkowymi metadanymi. MediaFile zawiera baseUrl, którego możesz użyć do pobrania rzeczywistych bajtów elementu multimedialnego. Szczegółowe informacje o dodatkowych parametrach baseUrl znajdziesz w przewodniku Listowanie i pobieranie multimediów.

  7. Wyświetlanie elementów multimedialnych: baseUrl z MediaFile służy do pobierania i wyświetlania treści multimedialnych na urządzeniu z funkcją Ambient.

Istotne kwestie

Limit urządzeń i zarządzanie nimi:

  • Limity urządzeń: pamiętaj, że użytkownik aplikacji może mieć maksymalnie 100 urządzeń.
  • Aktywność i tokeny urządzeń: musisz zarządzać cyklem życia urządzeń oraz tokenami autoryzacji użytkowników. Zastanów się, jak długo urządzenia mają pozostać aktywne i jak będziesz zarządzać odświeżaniem tokenów lub ponownym autoryzowaniem, jeśli urządzenie stanie się nieaktywne lub token wygaśnie.

Więcej informacji znajdziesz w przewodniku Tworzenie urządzeń i zarządzanie nimi.

Praca z elementami multimedialnymi:

  • Korzystanie z elementu multimedialnego: dowiedz się, jak prawidłowo pobierać i przetwarzać treści elementu multimedialnego za pomocą interfejsu baseUrl, w tym jakie są wymagane parametry uwierzytelniania.
  • Obsługa błędów: wdrożenie niezawodnej obsługi błędów w przypadku wywołań interfejsu API, w tym w takich scenariuszach jak NOT_FOUND w przypadku urządzeń, FAILED_PRECONDITION, jeśli nie są ustawione źródła multimediów, oraz RESOURCE_EXHAUSTED, jeśli osiągnięto limity urządzeń.

Więcej informacji znajdziesz w przewodniku na temat wyświetlania i pobierania multimediów.

Następne kroki