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 une utilisation efficace de 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 d'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 cette id de manière sécurisée et associez-la à vos utilisateurs.

Important :Enregistrez le id. Si vous n'enregistrez pas le id généré par Google, vous ne pourrez pas récupérer ni gérer un appareil plus tard. Cela peut entraîner des appareils abandonnés dans les comptes Google Photos de vos utilisateurs, auxquels votre application ne peut pas accéder ni les nettoyer.

Création d'appareils simplifiée avec OAuth

L'API Ambient propose un flux OAuth simplifié qui peut créer un appareil simultanément avec l'authentification de l'utilisateur. En transmettant le paramètre state supplémentaire dans votre requête OAuth initiale, vous pouvez associer le processus de création d'appareil directement au flux de connexion de l'utilisateur, ce qui simplifie l'expérience utilisateur en réduisant le nombre de codes QR qu'il doit scanner.

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

Limites des 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 un appareil 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 vrai.

Mettre à jour les appareils

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

Remarque :Nous vous recommandons de permettre à l'utilisateur de nommer son appareil avant de le créer. L'utilisateur peut ainsi reconnaître plus facilement son appareil lorsqu'il sélectionne des éléments multimédias dans son compte Google Photos.

Supprimer les appareils

Implémentez une stratégie de suppression des appareils pour un nettoyage et un contrôle appropriés par les utilisateurs. 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 dissocie 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 conservez le requestId utilisé lors de sa 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.

Remarques importantes 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. Tenez compte de la durée pendant laquelle les appareils restent actifs et de la manière dont vous gérerez les actualisations ou les réautorisations de jetons si un appareil devient inactif ou si son jeton expire.
• Gestion des erreurs:implémentez une gestion des erreurs robuste pour tous les appels d'API liés à l'appareil. Préparez-vous à des scénarios comme 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

• Application exemple:notre application exemple 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 à afficher dessus.