Après avoir effectué des appels pour répertorier le contenu d'un album ou d'une bibliothèque de photos, 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 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, mais, en fonction de votre cas d'utilisation, vous pouvez stocker ou mettre en cache l'ID d'é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 des autorisations suivants. L'accès aux éléments multimédias renvoyés dans la réponse dépend des champs d'application demandés.
photoslibrary.readonlypermet d'accéder à tous les éléments multimédias de la bibliothèque de l'utilisateurphotoslibrary.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 support tel qu'une photo ou une vidéo qui a été importée dans la bibliothèque Google Photos. Il s'agit d'un objet de niveau supérieur et ses propriétés peuvent varier en fonction du type de support sous-jacent.
Le tableau suivant répertorie les propriétés mediaItem:
| Propriétés | |
|---|---|
id |
ID permanent stable permettant d'identifier l'objet. |
description |
Description de l'élément multimédia tel qu'il apparaît dans Google Photos. |
baseUrl |
Permet d'accéder aux octets bruts. Pour en savoir plus, consultez 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 dans l'album. |
mimeType |
Type d'élément multimédia permettant d'identifier facilement le type de support (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 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 dans photo ou video sont basées sur les métadonnées contenues dans le fichier. Il est possible que certaines propriétés ne soient pas présentes. ContributorInfo contient les métadonnées des éléments faisant partie d'un album partagé. Ce champ n'est inclus que lorsqu'il répertorie le contenu d'un album partagé où l'utilisateur a accordé le champ d'application des autorisations 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 la valeur videoProcessingStatus avec la valeur PROCESSING, avant qu'il ne soit utilisé pour 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 à un élément multimédia multimédia 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 à 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 à 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. 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 par appel. 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 montre l'accès réussi et ayant échoué 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 dans l'API Library de Google Photos vous permettent d'accéder aux octets des éléments multimédias. Avec les différentes URL de base, votre application peut télécharger les éléments multimédias ou les afficher. Les URL de base sont des chaînes qui sont incluses dans la réponse lorsque vous répertoriez des albums ou que vous accédez à des éléments multimédias. Elles sont valides 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: permet d'accéder directement à la photo ou à la miniature d'une vidéo ou de télécharger des octets de vidéo.coverPhotoBaseUrl: permet d'accéder directement à la photo de couverture de l'album.profilePictureBaseUrl: permet d'accéder 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ètre | |
|---|---|
w, h |
Description Les paramètres de largeur, Pour accéder à un élément multimédia d'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 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 d'affichage d'un élément multimédia dont la largeur est comprise entre 2 048 pixels et 1 024 pixels: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Description Le paramètre de recadrage Si vous souhaitez recadrer l'image selon la largeur et la hauteur exactes que vous avez spécifiées, concaténez l'URL de base avec les paramètres facultatifs La taille (en pixels) doit être comprise dans la plage [1, 16383]. Si la largeur ou la hauteur de l'image dépasse la taille demandée, l'image est réduite et recadrée (conservée). Exemples : base-url=wmax-width-hmax-height-c Dans cet exemple, l'application affiche un élément multimédia de exactement 256 x 256 pixels de large, tel qu'une vignette: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
Description Le 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, concaténez 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 de la vidéo:
| Paramètre | |
|---|---|
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 transfert des URL de base pour le téléchargement de vidéos peut prendre 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 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éo incluent un bouton de lecture en superposition. Consultez la section concernant le paramètre -no pour supprimer cette superposition. Exemples : Pour obtenir des exemples, reportez-vous au tableau des URL de base des images. |
no |
Description Le paramètre Si vous souhaitez récupérer la miniature d'une vidéo sans bouton de lecture en superposition, concaténez l'URL de base avec le paramètre no. Le paramètre no ne doit pas être utilisé avec au moins un des paramètres d'URL de base d'image. Exemples : base-url=wmax-width-hmax-height-no L'exemple suivant montre une miniature de vidéo d'une largeur de 1 280 x 720 pixels, sans 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 d'URL de base d'images ou d'URL de base de vidéos 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 associé à une 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 associé à une photo animée, utilisez le format des URL de base d'images. |