Premiers pas avec l'API Ambient

L'API Ambient permet à votre application de connecter des appareils ambiants au compte Google Photos d'un utilisateur et d'afficher les photos qu'il a sélectionnées.

Flux de l'API Ambient

Voici comment l'API Ambient fonctionne pour connecter un appareil, puis récupérer et afficher des éléments multimédias :

  1. Rechercher un appareil existant (recommandé) : avant de créer un appareil, il est recommandé de vérifier si un appareil existe déjà pour l'utilisateur actuel. Votre application doit maintenir un mappage entre votre utilisateur interne et le deviceId fourni par Google pour tous les appareils qu'il crée via votre application. Si un deviceId est trouvé pour l'utilisateur, vous pouvez passer à l'actualisation de son jeton d'autorisation (si nécessaire).

  2. Lancer l'autorisation OAuth 2.0 : commencez le flux OAuth 2.0 pour les téléviseurs et les périphériques d'entrée limitée en demandant un code d'autorisation.

  3. Créer un appareil : votre application crée un appareil dans le compte Google Photos d'un utilisateur en appelant CreateDevice et en fournissant un UUID v4 valide.

    Une fois l'appareil créé, l'API renvoie un objet AmbientDevice contenant un deviceId attribué par Google. Il est essentiel que votre application stocke ce deviceId et l'associe à vos utilisateurs.

  4. Afficher le settingsUri : un objet AmbientDevice inclut un settingsUri. Présentez cet URI à l'utilisateur, généralement sous la forme d'un QR code qu'il peut scanner à l'aide de son appareil mobile. Cet URI redirige l'utilisateur vers l'application Google Photos, où il peut configurer les sources multimédias (par exemple, les albums) qu'il souhaite afficher sur son appareil ambiant.

  5. Interroger mediaSourcesSet : votre application doit appeler régulièrement la méthode GetDevice, en fournissant le deviceId, pour vérifier l'état de l'appareil ambiant. Surveillez le champ mediaSourcesSet dans la réponse AmbientDevice. Il sera initialement défini sur "false".

    Une fois que l'utilisateur a sélectionné des sources multimédias dans l'application Google Photos, ce champ passe à "true".

    La réponse AmbientDevice inclut un pollingConfig avec un pollInterval que vous devez utiliser comme indication pour votre fréquence d'interrogation.

  6. Récupérer des éléments multimédias : lorsque mediaSourcesSet renvoie "true", votre application peut commencer à récupérer les éléments multimédias sélectionnés par l'utilisateur.

    Appelez la méthode ListMediaItems en fournissant le deviceId. L'API renvoie une ListMediaItemsResponse contenant une liste d'objets AmbientMediaItem. Chaque AmbientMediaItem inclut des détails tels qu'un id, un createTime et un objet MediaFile avec des métadonnées supplémentaires. Le MediaFile contient un baseUrl que vous pouvez utiliser pour récupérer les octets réels d'un élément multimédia. Consultez le guide Lister et récupérer des éléments multimédias pour en savoir plus sur les paramètres baseUrl supplémentaires.

  7. Afficher des éléments multimédias : utilisez le baseUrl du MediaFile pour télécharger et afficher le contenu multimédia sur l'appareil ambiant.

Considérations importantes à prendre en compte

Limite et gestion des appareils :

  • Limites d'appareils : tenez compte de la limite de 100 appareils par utilisateur de votre application.
  • Activité de l'appareil et jetons : vous devrez gérer le cycle de vie des appareils et des jetons d'autorisation des utilisateurs. Déterminez la durée pendant laquelle les appareils restent actifs et comment vous gérerez les actualisations ou les réautorisations des jetons si un appareil devient inactif ou si le jeton expire.

Le guide Créer et gérer des appareils contient des informations supplémentaires.

Utiliser des éléments multimédias :

  • Utilisation des éléments multimédias : découvrez comment récupérer et gérer correctement le contenu des éléments multimédias à l'aide du baseUrl, y compris les authentifications ou paramètres nécessaires.
  • Gestion des exceptions : mettez en œuvre une gestion des exceptions robuste pour les appels d'API, y compris dans des scénarios tels que NOT_FOUND pour les appareils, FAILED_PRECONDITION si les sources multimédias ne sont pas définies et RESOURCE_EXHAUSTED si les limites d'appareils sont atteintes.

Le guide Lister et récupérer des éléments multimédias contient des informations supplémentaires, y compris sur le règlement relatif au contenu et le filtrage.

Étapes suivantes