Après avoir appelé pour répertorier le contenu d'une bibliothèque ou d'un album photo, au lieu de stocker les éléments multimédias affichés, votre application doit stocker leurs ID. 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 d'é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 des autorisations 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 affichés dans la réponse dépend des niveaux d'accès que vous avez demandés.
photoslibrary.readonlypermet d'accéder à tous les éléments multimédias de la bibliothèque de l'utilisateur.photoslibrary.readonly.appcreateddatan'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, qui a été importé dans la bibliothèque Google Photos. Il s'agit d'un objet de niveau supérieur. Ses propriétés peuvent différer 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 stable et permanent utilisé pour identifier l'objet. |
description |
Description de l'élément multimédia tel qu'il apparaît dans Google Photos. |
baseUrl |
Utilisé pour accéder aux octets bruts. Pour en savoir plus, consultez la section URL de base. |
productUrl |
Un lien vers l'image dans Google Photos. Seul l'utilisateur peut ouvrir ce lien. Les URL pointent vers un élément multimédia dans la bibliothèque. Si l'URL a été récupérée à partir d'une recherche dans un 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 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 des informations de l'élément). |
mediaMetadata |
Varie en fonction du type de support sous-jacent, comme 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 Contient 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 contenues dans photo ou video sont basées sur les métadonnées du fichier. Certaines propriétés ne sont peut-être pas présentes. ContributorInfo contient les métadonnées des éléments faisant partie d'un album partagé. Ce champ n'est inclus que lorsque vous listez le contenu d'un album partagé pour lequel l'utilisateur a accordé le champ d'application d'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 d'être utilisé (READY). L'élément 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 d'un élément multimédia de type 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 d'un élément multimédia vidéo se présente comme suit : La propriété "video" contient des métadonnées pour les é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 des métadonnées pour les é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 des métadonnées pour les é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 des métadonnées pour les é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 indiqués dans la requête. Chaque résultat contient un élément MediaItem ou un élément Status en cas d'erreur.
Le nombre maximal d'éléments multimédias que vous pouvez demander dans un appel est de 50. 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 que l'accès aux éléments multimédias a réussi ou échoué. Spécifiez chaque identifiant d'élément multimédia en tant que nouveau paramètre de requête mediaItemIds dans le cadre de 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 au sein de votre application. Les URL de base sont des chaînes incluses dans la réponse lorsque vous répertoriez des albums ou accédez aux éléments multimédias. Ils sont valides pendant 60 minutes et nécessitent des paramètres supplémentaires, car ils ne peuvent pas être utilisés tels quels.
Voici les différentes URL de base:
baseUrl: accéder directement à la photo, à la miniature d'une vidéo ou au téléchargement d'octets vidéo.coverPhotoBaseUrl: accéder directement à la photo de couverture de l'albumprofilePictureBaseUrl: accédez directement à la photo de profil du propriétaire d'unmediaItem.
URL de base d'images
Voici la liste des options que vous pouvez utiliser avec les URL de base d'images:
| Paramètres | |
|---|---|
w, h |
Description Les paramètres width, Pour accéder à un élément multimédia d'image, tel qu'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 mise à l'échelle dans 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 l'exemple d'un élément multimédia dont la largeur et la hauteur ne dépassent pas 2 048 pixels et 1 024 pixels: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Description Paramètre de recadrage Si vous souhaitez recadrer l'image aux dimensions exactes que vous avez spécifiées en termes de largeur et de hauteur, concaténez l'URL de base avec le paramètre facultatif 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, l'image est réduite et recadrée (en conservant ses proportions). Exemples : base-url=wmax-width-hmax-height-c Dans cet exemple, l'application affiche un élément multimédia mesurant exactement 256 x 256 pixels de haut, comme une vignette: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
Description Le paramètre 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 Exemples : base-url=d Dans cet exemple, l'application télécharge une image contenant 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ètres | |
|---|---|
dv |
Description Pour accéder aux octets d'une vidéo Le paramètre dv demande une version transcodée de haute qualité de la vidéo d'origine. Ce paramètre n'est pas compatible avec les paramètres w et h. Le renvoi des octets des URL de base pour les téléchargements de vidéos peut prendre quelques secondes. 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 de l'image. Par défaut, toutes les miniatures de vidéos incluent un bouton de lecture en superposition. Consultez le paramètre -no pour supprimer cette superposition. Exemples : Consultez le tableau des URL de base des images pour obtenir des exemples. |
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, 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 montre une miniature vidéo de 1 280 pixels de large sur 720 pixels 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 d'image ou des URL de base de vidéo pour les requêtes baseUrl de photo animée.
| Paramètres | |
|---|---|
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 |
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'image. |