Après avoir effectué des appels pour répertorier 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 de ces éléments. En effet, le contenu des éléments multimédias peut changer et, au bout d'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.
Notez que votre application ne doit pas mettre en cache la photo ou la vidéo d'un utilisateur pendant de longues périodes. Toutefois, selon votre cas d'utilisation, vous pouvez stocker ou mettre en cache l'ID de l'élément multimédia aussi longtemps que nécessaire. Notez également que l'accès aux données utilisateur est régi par des obligations de confidentialité.
Champs d'application d'autorisation requis
Pour accéder aux éléments multimédias, votre application doit demander au moins l'un des champs d'application d'autorisation suivants. L'accès aux éléments multimédias renvoyés dans la réponse dépend des portées que vous avez demandées.
photoslibrary.readonly
permet d'accéder à tous les éléments multimédias de la bibliothèque de l'utilisateur.photoslibrary.readonly.appcreateddata
n'autorise l'accès qu'aux éléments multimédias créés par l'application
Éléments multimédias
Un mediaItem
est une représentation d'un contenu multimédia, tel qu'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 telle qu'elle apparaît dans Google Photos. |
baseUrl |
Permet d'accéder aux octets bruts. Pour en savoir plus, consultez la section URL de base. |
productUrl |
Lien vers l'image dans Google Photos. Ce lien ne peut être ouvert que par l'utilisateur, et non par le développeur. 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 de l'élément multimédia pour faciliter l'identification du type de contenu multimédia (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 en fonction du type de support sous-jacent, tel que photo ou video .
Pour réduire la charge utile, vous pouvez utiliser des masques de champ.
|
contributorInfo |
Ce champ n'est renseigné que si l'élément multimédia se trouve dans un album partagé créé par cette application et que l'utilisateur a accordé le champ d'application Inclut des informations sur le contributeur qui a ajouté cet élément multimédia. Pour en savoir plus, consultez Partager des contenus multimédias. |
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. ContributorInfo
contient les métadonnées des éléments d'un album partagé. Ce champ n'est inclus que lors de la liste du contenu d'un album partagé pour lequel l'utilisateur a accordé l'champ d'application de l'autorisation photoslibrary.sharing
.
Si l'élément multimédia est une vidéo, le fichier vidéo doit d'abord être traité. 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" } }
La réponse pour un élément multimédia vidéo se présente comme suit. 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" } }
Java
La propriété "photo" contient les métadonnées des éléments photo.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasPhoto()) { // This media item is a photo and has additional photo metadata Photo photoMetadata = metadata.getPhoto(); String cameraMake = photoMetadata.getCameraMake(); String cameraModel = photoMetadata.getCameraModel(); float aperture = photoMetadata.getApertureFNumber(); int isoEquivalent = photoMetadata.getIsoEquivalent(); // ... } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
La propriété "video" contient des métadonnées pour les éléments vidéo.
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasVideo()) { // This media item is a video and has additional video metadata Video videoMetadata = metadata.getVideo(); VideoProcessingStatus status = videoMetadata.getStatus(); if (status.equals(VideoProcessingStatus.READY)) { // This video media item has been processed String cameraMake = videoMetadata.getCameraMake(); String cameraModel = videoMetadata.getCameraModel(); double fps = videoMetadata.getFps(); // ... } } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
PHP
La propriété "photo" contient les métadonnées des éléments photo.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $photoMetadata = $metadata->getPhoto(); if (!is_null($photoMetadata)) { // This media item is a photo and has additional photo metadata $cameraMake = $photoMetadata->getCameraMake(); $cameraModel = $photoMetadata->getCameraModel(); $aperture = $photoMetadata->getApertureFNumber(); $isoEquivalent = $photoMetadata->getIsoEquivalent(); // ... } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
La propriété "video" contient les métadonnées des éléments vidéo.
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $videoMetadata = $metadata->getVideo(); if (!is_null($videoMetadata)) { // This media item is a video and has additional video metadata if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) { // This video media item has been processed $cameraMake = $videoMetadata->getCameraMake(); $cameraModel = $videoMetadata->getCameraModel(); $fps = $videoMetadata->getFps(); // ... } } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Obtenir plusieurs éléments multimédias
Pour récupérer plusieurs éléments multimédias en fonction 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." } } ] }
Java
try { // List of media item IDs to retrieve List<String> mediaItemIds = Arrays .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"); // Get a list of media items using their IDs BatchGetMediaItemsResponse response = photosLibraryClient .batchGetMediaItems(mediaItemIds); // Loop over each result for (MediaItemResult result : response.getMediaItemResultsList()) { // Each MediaItemresult contains a status and a media item if (result.hasMediaItem()) { // The media item was successfully retrieved, get some properties MediaItem item = result.getMediaItem(); String id = item.getId(); // ... } else { // If the media item is not set, an error occurred and the item could not be loaded // Check the status and handle the error Status status = result.getStatus(); // ... } } } catch (ApiException e) { // Handle error }
PHP
try { // List of media item IDs to retrieve $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"]; // Get a list of media items using their IDs $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds); // Loop over each result foreach ($response->getMediaItemResults() as $itemResult) { // Each MediaItemresult contains a status and a media item $mediaItem = $itemResult->getMediaItem(); if(!is_null($mediaItem)){ // The media item was successfully retrieved, get some properties $id = $mediaItem->getId(); // ... } else { // If the media item is null, an error occurred and the item could not be loaded } } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
URL de base
Les URL de base de l'API Library de Google Photos vous permettent d'accéder aux octets des éléments multimédias. À l'aide des différentes URL de base, votre application peut télécharger les éléments multimédias ou les afficher dans votre application. Les URL de base sont des chaînes qui sont incluses dans la réponse lorsque vous listez des albums ou accédez à des éléments multimédias. Elles sont valables pendant 60 minutes et nécessitent des paramètres supplémentaires, car elles ne peuvent pas être utilisées telles quelles.
Les différentes URL de base sont les suivantes:
baseUrl
: accédez directement à la photo, à la miniature d'une vidéo ou au téléchargement d'octets de vidéo.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 Le paramètre 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. Les URL de base des téléchargements de vidéos peuvent mettre quelques secondes à renvoyer des octets. Avant d'utiliser ce paramètre, vérifiez que la valeur du 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 miniature 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é. Reportez-vous au 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 Si vous souhaitez récupérer la miniature d'une vidéo sans la superposition d'un bouton de lecture, 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 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 les paramètres d'URL de base d'image ou d'URL de base de vidéo pour les requêtes de photos animées baseUrl
.
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. |