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

Une fois qu'un utilisateur a sélectionné des éléments multimédias à l'aide de l'API Picker, vous pouvez récupérer des informations les concernant et accéder à leur contenu. Ce guide décrit le processus de listage et de récupération des éléments multimédias.

Avant de commencer

  • Comprendre le flux:consultez Premiers pas avec l'API Picker pour obtenir une présentation de l'ensemble du processus de sélection des photos.
  • Sélection complète des éléments multimédias:assurez-vous que l'utilisateur a bien sélectionné des éléments multimédias dans sa session. Pour en savoir plus, consultez le guide sur les sessions.
  • Consulter les champs d'application d'autorisation requis: l'utilisation des sessions nécessite le champ d'application photospicker.mediaitems.readonly. Pour en savoir plus sur les champs d'application, consultez la section Champs d'application des autorisations.

Lister les éléments multimédias sélectionnés

  1. Utilisez le point de terminaison mediaItems.list: envoyez une requête GET à https://photospicker.googleapis.com/v1/mediaItems en fournissant sessionId comme paramètre de requête.

  2. Gérer la pagination (si nécessaire):

    Si l'utilisateur sélectionne un grand nombre d'éléments, la réponse peut être paginée. Utilisez nextPageToken dans la réponse pour récupérer les pages de résultats suivantes.

  3. Traiter les éléments multimédias: la réponse contient un tableau d'objets PickedMediaItem, 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.
    • baseUrl: URL de base à partir de laquelle vous pouvez créer des URL pour accéder au contenu de l'élément multimédia dans différentes résolutions.
    • mimeType: type MIME de l'élément multimédia (par exemple, image/jpeg, vidéo/mp4).

Récupérer les éléments multimédias sélectionnés

Assurez-vous de disposer d'un jeton d'accès OAuth 2.0 valide avec le champ d'application https://www.googleapis.com/auth/photospicker.mediaitems.readonly pour autoriser vos requêtes.

  • Construisez l'URL de contenu:utilisez la baseUrl de l'objet PickedMediaItem. Ajoutez la résolution ou le format de fichier à la baseUrl. Pour en savoir plus, consultez la section sur les URL de base.

  • Récupérez le contenu:envoyez une requête GET à l'URL de base de l'élément multimédia. La réponse contient les octets de l'élément multimédia (image ou vidéo). De nombreuses options de baseURL sont disponibles.

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 répertoriez des albums (API Library) ou que vous 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.

Pour l'API Library:

Les URL de base restent actives pendant 60 minutes.

Les différentes URL de base sont les suivantes:

  • baseUrl: permet d'accéder directement à la photo ou à la miniature d'une vidéo, ou de télécharger des vidéos.
  • coverPhotoBaseUrl: accédez directement à la photo de couverture de l'album.
  • profilePictureBaseUrl: accéder directement à la photo de profil du propriétaire d'un mediaItem.

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, comme une photo ou une vignette de vidéo, vous devez spécifier les dimensions que vous prévoyez d'afficher dans votre application (afin que l'image puisse être redimensionnée selon ces dimensions tout en conservant le format). 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 d'affichage d'un élément multimédia dont la largeur ne doit pas dépasser 2 048 px et la hauteur 1 024 px:

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

Description

Le paramètre c est recadré.

Si vous souhaitez recadrer l'image aux dimensions de largeur et de hauteur exactes que vous avez spécifiées, concatenatez l'URL de base avec le paramètre -c facultatif, ainsi que les paramètres w et h obligatoires.

La taille (en pixels) doit être comprise dans la plage [1, 16 383]. Si la largeur ou la hauteur de l'image dépasse la taille demandée, celle-ci est réduite et recadrée (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 vignette:

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, concatenatez 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 baseUrl avec le paramètre dv de téléchargement de la vidéo.

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.

Le retour d'octets pour les URL de base des téléchargements de vidéos peut prendre jusqu'à quelques secondes.

Avant d'utiliser ce paramètre, vérifiez que la valeur du champ mediaMetadata.status de l'élément multimédia est READY. Sinon, si le traitement de votre élément multimédia n'est pas terminé, vous risquez de 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 vignette de la vidéo, utilisez l'un des paramètres d'URL de base d'image.

Par défaut, toutes les miniatures de vidéos incluent un bouton de lecture superposé. 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 pour supprimer la superposition de la vignette.

Si vous souhaitez récupérer la vignette d'une vidéo sans la superposition d'un bouton de lecture, concatenatez 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 présente une miniature de vidéo mesurant exactement 1 280 x 720 pixels de haut et 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 des paramètres à partir des URL de base d'image ou des URL de base de vidéo pour les requêtes baseUrl de photo animée.

Paramètre
dv

Description

Pour récupérer l'élément vidéo d'un élément multimédia photo animée, utilisez le paramètre dv comme pour le téléchargement à partir d'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 photo animée, utilisez le format des URL de base des images.