Créer et gérer des appareils

Ce guide explique comment créer, gérer et supprimer des appareils. Une gestion appropriée des appareils permet de créer une expérience utilisateur fluide et d'utiliser efficacement l'API Ambient.

Créer des appareils

Une fois qu'un utilisateur s'est authentifié à l'aide du flux OAuth 2.0 pour les applications TV et les appareils à entrée limitée, créez un appareil dans son compte Google Photos.

Lorsque votre application crée un appareil à l'aide de la méthode devices.create, l'API Ambient renvoie un objet AmbientDevice qui inclut un id généré par Google. Stockez cet id de manière sécurisée et associez-le à vos utilisateurs.

Création simplifiée d'appareils avec OAuth

L'API Ambient propose un flux OAuth simplifié. En transmettant le paramètre state supplémentaire dans votre requête OAuth initiale et en appelant devices.create avec le requestId correspondant, vous pouvez lier le processus de création de l'appareil directement au flux de connexion de l'utilisateur, ce qui simplifie l'expérience utilisateur en réduisant le nombre de codes QR à scanner.

Pour en savoir plus et obtenir un exemple, consultez le guide Flux d'authentification simplifié pour l'API Ambient.

Limites d'appareils

Votre application peut créer jusqu'à 100 appareils par utilisateur. Si cette limite est dépassée, l'API renvoie une erreur RESOURCE_EXHAUSTED.

Gérer les appareils

Une fois qu'un appareil est créé et associé au compte Google Photos d'un utilisateur, vous devrez peut-être gérer son cycle de vie.

Récupérer des appareils

Pour récupérer des informations sur un appareil spécifique, utilisez la méthode devices.get avec son id unique. Cela est utile pour vérifier l'état de l'appareil, par exemple si mediaSourcesSet est défini sur "true".

Mettre à jour les appareils

Vous pouvez mettre à jour certaines propriétés d'un appareil existant, comme son nom d'affichage, à l'aide de la méthode devices.patch. Les utilisateurs peuvent ainsi personnaliser leurs appareils et les identifier plus facilement dans Google Photos.

Supprimer les appareils

Mettez en œuvre une stratégie de suppression des appareils pour un nettoyage approprié et un contrôle utilisateur. Vous pouvez supprimer un appareil à l'aide de la méthode devices.delete.

Voici quelques scénarios de suppression d'appareils :

  • Déconnexion de l'utilisateur : si un utilisateur déconnecte votre application de son compte Google Photos, vous devez supprimer l'appareil correspondant.
  • Appareils orphelins : si vous perdez la trace d'un id, mais que vous disposez toujours du requestId utilisé lors de la création, vous pouvez utiliser le requestId avec devices.delete pour supprimer un appareil orphelin. Cela permet d'éviter les doublons accidentels et de garder le compte de l'utilisateur propre.

Points importants et bonnes pratiques

  • Cycle de vie des appareils et autorisation des utilisateurs : 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 son jeton expire.
  • Gestion des erreurs : mettez en œuvre une gestion robuste des erreurs pour tous les appels d'API liés aux appareils. Préparez-vous à des scénarios tels que les suivants :
    • NOT_FOUND : si un appareil n'existe pas ou n'appartient pas à l'utilisateur.
    • RESOURCE_EXHAUSTED : si vous dépassez la limite d'appareils.
    • ALREADY_EXISTS : si vous essayez de créer un appareil avec un requestId qui existe déjà.

Étapes suivantes

  • Exemple d'application : notre exemple d'application inclut un exemple de création d'un appareil et d'utilisation des données de réponse. Pour en savoir plus, consultez la fonction createDevice.
  • Documentation de référence : consultez la documentation de référence complète sur les appareils pour obtenir des informations détaillées sur toutes les méthodes disponibles, les paramètres de requête et de réponse, ainsi que les codes d'erreur.
  • Lister et récupérer des éléments multimédias : une fois que vous avez créé et géré vos appareils, découvrez comment lister et récupérer des éléments multimédias pour les afficher.