Lister et récupérer des éléments multimédias

Une fois qu'un utilisateur a configuré son appareil ambiant et sélectionné des sources multimédias dans Google Photos, votre application peut lister et récupérer ces éléments multimédias pour les afficher.

Avant de commencer

• Vérifiez la configuration de l'appareil : assurez-vous d'avoir créé et configuré un appareil pour l'utilisateur.
• Comprendre le flux de l'API Ambient : consultez le flux de l'API Ambient pour comprendre le processus global, en particulier l'étape impliquant l'interrogation de mediaSourcesSet.

Sondage pour mediaSourcesSet

Avant de pouvoir lister des éléments multimédias pour un appareil, l'utilisateur doit avoir sélectionné les photos qu'il souhaite partager avec votre application dans l'application Google Photos. Votre application doit interroger l'appareil pour déterminer quand cette sélection a été effectuée.

Appelez régulièrement la méthode devices.get pour le deviceId spécifique. Surveillez le champ mediaSourcesSet dans la réponse AmbientDevice. Il sera initialement de false. Une fois que l'utilisateur a sélectionné des sources multimédias, 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.

Lister les éléments multimédias

Une fois que mediaSourcesSet est défini sur true pour un appareil, vous pouvez commencer à récupérer les éléments multimédias sélectionnés par l'utilisateur.

1. Utilisez le point de terminaison mediaItems.list : envoyez une requête GET à https://photosambient.googleapis.com/v1/mediaItems en fournissant le deviceId dans le chemin d'accès.

2. Gérez la pagination (si nécessaire) : la réponse peut être paginée. Utilisez le paramètre pageSize pour spécifier le nombre maximal d'éléments à renvoyer, et le paramètre pageToken d'une réponse précédente pour récupérer les pages de résultats suivantes.

3. Traitez les éléments multimédias : la réponse contient un tableau d'objets AmbientMediaItem, chacun représentant un élément multimédia sélectionné. Ces objets incluent des informations essentielles telles que :

   • id : identifiant unique de l'élément multimédia.
   • creationTime : code temporel de la création de l'élément multimédia.
   • mediaFile : objet contenant des informations permettant d'accéder au contenu réel.

Le champ mediaFile inclut baseUrl. C'est ce baseUrl que vous utiliserez pour créer des URL permettant d'accéder au contenu de l'élément multimédia à différentes résolutions ou dans différents formats.

URL de base

Les URL de base des API Google Photos permettent d'accéder aux octets bruts des éléments multimédias, ce qui permet à votre application de les télécharger ou de les afficher. Ces URL sont incluses dans les réponses lorsque vous listez des albums (API Library) ou accédez à des éléments multimédias (API Library et Picker). N'oubliez pas que les URL de base nécessitent des paramètres supplémentaires pour fonctionner correctement.

Pour l'API Picker :

Tous les objets PickedMediaItem.mediaFile incluent un baseUrl.

Les URL de base restent actives pendant 60 minutes, mais peuvent expirer plus tôt si l'utilisateur révoque les autorisations de votre application dans les paramètres de son compte Google.

Remarque : Les requêtes envoyées à une URL de base PickedMediaItem.mediaFile doivent inclure un en-tête d'autorisation avec un jeton de support OAuth 2.0 valide.

Pour l'API Library :

Les URL de base restent actives pendant 60 minutes.

Voici les différentes URL de base :

• baseUrl : accédez directement à la photo ou à la vignette d'une vidéo, ou téléchargez les octets de la vidéo.
• coverPhotoBaseUrl : accédez directement à la photo de couverture de l'album.
• profilePictureBaseUrl : accédez directement à la photo de profil du propriétaire d'un mediaItem.

Avertissement : Si vous utilisez l'URL de base, vous devez spécifier un paramètre de téléchargement, ou à la fois la largeur et la hauteur maximales.

URL de base des images

Voici la liste des options que vous pouvez utiliser avec les URL de base des images :

Paramètre
w, h	Description Paramètres de largeur (w) et de hauteur (h). Pour accéder à un élément multimédia image, tel qu'une photo ou une miniature de vidéo, vous devez spécifier les dimensions que vous prévoyez d'afficher dans votre application (afin que l'image puisse être mise à l'échelle dans ces dimensions tout en conservant les proportions). Pour ce faire, concaténez l'URL de base avec les dimensions requises, comme indiqué dans les exemples. Exemples : base-url=wmax-width-hmax-height Voici un exemple pour afficher un élément multimédia dont la largeur ne dépasse pas 2 048 px et la hauteur ne dépasse pas 1 024 px : https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c	Description Paramètre de recadrage c. Si vous souhaitez recadrer l'image selon les dimensions exactes de largeur et de hauteur que vous avez spécifiées, concaténez l'URL de base avec le paramètre facultatif -c, ainsi qu'avec les paramètres obligatoires w et h. La taille (en pixels) doit être comprise entre 1 et 16 383. Si la largeur ou la hauteur de l'image dépasse la taille demandée, l'image est réduite et recadrée (en conservant les proportions). Exemples : base-url=wmax-width-hmax-height-c Dans cet exemple, l'application affiche un élément multimédia de 256 x 256 pixels, comme une miniature : https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d	Description Paramètre de téléchargement, d. Si vous souhaitez télécharger l'image en conservant toutes les métadonnées Exif, à l'exception des métadonnées de localisation, concaténez l'URL de base avec le paramètre d. Exemples : base-url=d Dans cet exemple, l'application télécharge une image avec toutes les métadonnées, à l'exception des métadonnées de localisation : https://lh3.googleusercontent.com/p/Az....XabC=d

URL de base des vidéos

Voici la liste des options que vous pouvez utiliser avec les URL de base des vidéos :

Paramètre
dv	Description Pour accéder aux octets d'une vidéo mediaItem, concaténez le paramètre baseUrl avec le paramètre de téléchargement de la vidéo dv. Le paramètre dv demande une version transcodée de haute qualité de la vidéo d'origine. Le paramètre n'est pas compatible avec les paramètres w et h. Les URL de base pour les téléchargements de vidéos peuvent mettre quelques secondes à renvoyer des octets. Avant d'utiliser ce paramètre, vérifiez que le champ mediaMetadata.status des éléments multimédias est défini sur READY. Sinon, si votre élément multimédia n'a pas fini d'être traité, vous pouvez recevoir un message d'erreur. Exemples : base-url=dv L'exemple suivant montre comment télécharger les octets d'une vidéo : https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h, c et d	Description Pour accéder à la miniature de la vidéo, utilisez l'un des paramètres d'URL de base de l'image. Par défaut, toutes les miniatures de vidéos incluent un bouton de lecture. Consultez le paramètre -no pour supprimer cette superposition. Exemples : Pour obtenir des exemples, consultez le tableau des URL de base des images.
no	Description Paramètre no permettant de supprimer le calque de miniature. Si vous souhaitez récupérer la miniature d'une vidéo sans le bouton de lecture en superposition, concaténez l'URL de base avec le paramètre no. Le paramètre no doit être utilisé avec au moins l'un des paramètres d'URL de base de l'image. Exemples : base-url=wmax-width-hmax-height-no L'exemple suivant affiche une miniature vidéo de 1 280 px de large sur 720 px de haut, sans bouton de lecture en superposition : https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

URL de base des photos animées

Les photos animées contiennent à la fois des éléments photo et vidéo. Vous pouvez utiliser les paramètres des URL de base des images ou des URL de base des vidéos pour les requêtes baseUrl de photos animées.

Paramètre
dv	Description Pour récupérer l'élément vidéo d'un élément multimédia de photo animée, utilisez le paramètre dv comme vous le feriez pour télécharger des URL de base vidéo.
w, h, c et d	Description Pour récupérer l'élément photo d'un élément multimédia de type photo animée, utilisez le format des URL de base des images.

Règlement et filtrage du contenu

Par défaut, Google Photos applique un filtrage de contenu standard aux images et aux vidéos affichées sur un appareil partagé, comme un téléviseur ou un écran numérique. Ce filtre est conçu pour optimiser l'expérience de visionnage en excluant les contenus tels que :

• Images fonctionnelles (par exemple, captures d'écran, documents, reçus)
• Images qui peuvent s'afficher de manière insatisfaisante sur un grand écran (par exemple, résolution très faible, flou, grain excessif)
• Contenus identifiés comme très personnels ou sensibles, qui ne sont pas forcément destinés à être affichés publiquement dans un environnement partagé.

Le filtrage du contenu est entièrement automatisé. Pour permettre aux utilisateurs de mieux contrôler le contenu affiché, vous pouvez leur permettre de sélectionner et de mettre à jour manuellement les sources multimédias utilisées pour l'écran ambiant.

Étapes suivantes

• Exemple d'application : notre exemple d'application inclut un exemple de liste et de récupération d'éléments multimédias. Pour en savoir plus, consultez les fonctions checkMediaSourcesSet et fetch_media_item_list.
• Documentation de référence : consultez la documentation de référence complète sur les éléments multimédias 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.