Après avoir effectué des appels pour lister le contenu d'une bibliothèque ou d'un album photo, au lieu de stocker les éléments multimédias renvoyés, votre application doit stocker les ID des éléments multimédias. En effet, le contenu des éléments multimédias peut changer et, après un certain temps, les URL incluses dans la réponse expirent. L'ID de l'élément multimédia identifie de manière unique un élément multimédia, tel qu'une photo ou une vidéo dans la bibliothèque d'un utilisateur.
Champs d'application des autorisations requis
L'accès aux éléments multimédias créés par l'application nécessite la portée photoslibrary.readonly.appcreateddata. Pour en savoir plus sur les champs d'application, consultez la section Champs d'application d'autorisation.
Éléments multimédias
Un mediaItem est une représentation d'un contenu multimédia, comme une photo ou une vidéo, importée dans la bibliothèque Google Photos. Il s'agit d'un objet de premier niveau et ses propriétés peuvent varier en fonction du type de contenu multimédia sous-jacent.
Le tableau suivant répertorie les propriétés mediaItem:
| Propriétés | |
|---|---|
id |
ID permanent et stable utilisé pour identifier l'objet. |
description |
Description de l'élément multimédia dans Google Photos. |
baseUrl |
Permet d'accéder aux octets bruts. Pour en savoir plus, consultez la rubrique URL de base. |
productUrl |
Lien vers l'image dans Google Photos. Ce lien ne peut pas être ouvert par le développeur, mais uniquement par l'utilisateur. Les URL pointent vers un élément multimédia de la bibliothèque. Si l'URL a été récupérée à partir d'une recherche d'album, elle pointe vers l'élément de l'album. |
mimeType |
Type d'élément multimédia permettant d'identifier facilement le type de contenu (par exemple, image/jpg). |
filename |
Nom de fichier de l'élément multimédia présenté à l'utilisateur dans l'application Google Photos (dans la section d'informations de l'élément). |
mediaMetadata |
Varie selon le type sous-jacent du contenu multimédia, par exemple photo ou video.
Pour réduire la charge utile, vous pouvez utiliser des masques de champ.
|
Obtenir un élément multimédia
Pour récupérer un élément multimédia, appelez mediaItems.get à l'aide de mediaItemId. La requête renvoie un seul élément multimédia.
mediaItem contient des propriétés telles que l'ID, la description et l'URL. Les informations supplémentaires dans photo ou video sont basées sur les métadonnées du fichier. Il est possible que certaines propriétés ne soient pas présentes.
Si l'élément multimédia est une vidéo, le fichier vidéo doit être traité en premier. mediaItem contient un champ status dans mediaMetadata, qui décrit l'état de traitement du fichier vidéo. Un fichier nouvellement importé renvoie d'abord videoProcessingStatus avec la valeur PROCESSING, avant qu'il ne soit READY à utiliser. L'baseUrl d'un élément multimédia vidéo n'est pas disponible tant que la vidéo n'a pas été traitée.
REST
Voici une requête GET:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-token
La réponse pour un élément multimédia photo se présente comme suit. La propriété photo contient des métadonnées pour les éléments photo.
{
"id": "media-item-id",
"description": "item-description",
"productUrl": "url-to-open-in-google-photos",
"baseUrl": "base-url_do-not-use-directly",
"mimeType": "mime-type-of-media",
"filename": "item-filename",
"mediaMetadata": {
"width": "media-item-width",
"height": "media-item-height",
"creationTime": "media-item-creation-time",
"photo": {
"cameraMake": "make-of-the-camera",
"cameraModel": "model-of-the-camera",
"focalLength": "focal-length-of-the-camera-lens",
"apertureFNumber": "aperture-f-number-of-the-camera-lens",
"isoEquivalent": "iso-of-the-camera",
"exposureTime": "exposure-time-of-the-camera-aperture"
}
},
"contributorInfo": {
"profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
"displayName": "name-of-user"
}
}
Voici à quoi ressemble la réponse pour un élément multimédia vidéo. La propriété "video" contient les métadonnées des éléments vidéo.
{
"id": "media-item-id",
"description": "item-description",
"productUrl": "url-to-open-in-google-photos",
"baseUrl": "base-url_do-not-use-directly",
"mimeType": "mime-type-of-media",
"filename": "item-filename",
"mediaMetadata": {
"width": "media-item-width",
"height": "media-item-height",
"creationTime": "media-item-creation-time",
"video": {
"cameraMake": "make-of-the-camera",
"cameraModel": "model-of-the-camera",
"fps": "frame-rate-of-the-video",
"status": "READY"
},
},
"contributorInfo": {
"profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
"displayName": "name-of-user"
}
}
Obtenir plusieurs éléments multimédias
Pour récupérer plusieurs éléments multimédias à l'aide de leurs identifiants, appelez mediaItems.batchGet à l'aide des mediaItemId.
La requête renvoie une liste de MediaItemResults dans l'ordre des identifiants d'éléments multimédias fournis dans la requête. Chaque résultat contient un MediaItem ou un Status en cas d'erreur.
Vous ne pouvez pas demander plus de 50 éléments multimédias en une seule fois. La liste des éléments multimédias ne doit pas contenir d'identifiants en double et ne peut pas être vide.
REST
Voici une requête GET qui indique l'accès réussi et non réussi aux éléments multimédias. Spécifiez chaque identifiant d'élément multimédia en tant que nouveau paramètre de requête mediaItemIds dans la requête:
GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id Content-type: application/json Authorization: Bearer oauth2-token
La requête GET renvoie la réponse suivante:
{
"mediaItemResults": [
{
"mediaItem": {
"id": "media-item-id",
...
}
},
{
"mediaItem": {
"id": "another-media-item-id",
...
}
},
{
"status": {
"code": 3,
"message": "Invalid media item ID."
}
}
]
}
URL de base
Les URL de base dans les API Google Photos donnent accès 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.
Pour l'API Library:
Les URL de base restent actives pendant 60 minutes.
Voici les différentes URL de base:
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éder directement à la photo de couverture de l'album.profilePictureBaseUrl: accéder directement à la photo de profil du propriétaire d'unmediaItem.
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, 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 Paramètre de recadrage 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 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 le format). 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, 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 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'un 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 le champ 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 Suppression de la superposition de vignette, paramètre 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 affiche une vignette vidéo de 1 280 x 720 pixels exactement, sans superposition de bouton de lecture: 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 |
w, h, c et d |
Description Pour récupérer l'élément photo d'un élément multimédia de photo animée, utilisez le format des URL de base d'images. |