Champs d'application des autorisations requis
L'API Library de Google Photos contient plusieurs champs d'application permettant d'accéder aux éléments multimédias et aux albums. Les éléments multimédias affichés par différents appels diffèrent en fonction des champs d'application demandés par le développeur.
Le champ d'application photoslibrary.readonly
permet d'accéder à tous les éléments multimédias de la bibliothèque de l'utilisateur. Le champ d'application photoslibrary.readonly.appcreateddata
n'autorise l'accès qu'aux éléments multimédias créés par l'application. Pour en savoir plus, consultez la section Champs d'application des autorisations.
Présentation
Une utilisation importante de l'API consiste à répertorier les éléments multimédias que l'utilisateur a sauvegardés dans Google Photos. Vous pouvez répertorier les éléments d'un album particulier ou de l'ensemble de la bibliothèque de l'utilisateur (vue par défaut dans l'application Google Photos).
Vous pouvez utiliser des filtres pour sélectionner des photos correspondant à une date, une catégorie de contenu ou un type de contenu spécifique lorsque vous répertoriez des éléments de la bibliothèque de l'utilisateur. Cette fonctionnalité n'est pas disponible lorsque vous répertoriez des éléments d'albums.
Répertorier le contenu des bibliothèques et des albums renvoie une liste d'éléments multimédias.
Les enrichissements faisant partie d'un album ne sont pas inclus. Les éléments multimédias décrivent une photo, une vidéo ou tout autre contenu multimédia. Un élément mediaItem
inclut un lien direct vers l'élément, un lien vers l'élément dans Google Photos et d'autres métadonnées pertinentes. Pour en savoir plus, consultez Accéder aux éléments multimédias et mediaItems
.
Liste des albums
Vous pouvez récupérer la liste des albums de l'utilisateur à l'aide de albums.list.
REST
Voici un exemple de requête :
GET https://photoslibrary.googleapis.com/v1/albums
La requête renvoie le résultat suivant:
{ "albums": [ { "id": "album-id", "title": "album-title", "productUrl": "album-product-url", "coverPhotoBaseUrl": "album-cover-base-url_do-not-use-directly", "coverPhotoMediaItemId": "album-cover-media-item-id", "isWriteable": "whether-you-can-write-to-this-album", "mediaItemsCount": "number-of-media-items-in-album" }, ... ], "nextPageToken": "token-for-pagination" }
Java
try { // Make a request to list all albums in the user's library // Iterate over all the albums in this list // Pagination is handled automatically ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(); for (Album album : response.iterateAll()) { // Get some properties of an album String id = album.getId(); String title = album.getTitle(); String productUrl = album.getProductUrl(); String coverPhotoBaseUrl = album.getCoverPhotoBaseUrl(); // The cover photo media item id field may be empty String coverPhotoMediaItemId = album.getCoverPhotoMediaItemId(); boolean isWritable = album.getIsWriteable(); long mediaItemsCount = album.getMediaItemsCount(); } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all albums in the user's library // Iterate over all the albums in this list // Pagination is handled automatically $response = $photosLibraryClient->listAlbums(); foreach ($response->iterateAllElements() as $album) { // Get some properties of an album $albumId = $album->getId(); $title = $album->getTitle(); $productUrl = $album->getProductUrl(); $coverPhotoBaseUrl = $album->getCoverPhotoBaseUrl(); // The cover photo media item id field may be empty $coverPhotoMediaItemId = $album->getCoverPhotoMediaItemId(); $isWriteable = $album->getIsWriteable(); $totalMediaItems = $album->getTotalMediaItems(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Chaque album renvoyé possède un ID qui permet d'en récupérer le contenu, comme indiqué dans la section Répertorier le contenu des albums. Il inclut également le titre et le nombre d'éléments multimédias qu'il contient.
productUrl
pointe vers l'album dans Google Photos que l'utilisateur peut ouvrir.
coverPhotoMediaItemId
contient l'ID d'élément multimédia qui représente la photo de couverture de cet album. Pour accéder à cette image de couverture, utilisez coverPhotoBaseUrl
. Vous ne devez pas utiliser coverPhotoBaseUrl
directement sans spécifier de paramètres supplémentaires.
Les albums qui ont été créés dans le compte de l'utilisateur ou ajoutés au compte de l'utilisateur et que votre application a partagés incluent une propriété shareInfo
supplémentaire.
Pour en savoir plus, consultez Partager des contenus multimédias.
Les albums peuvent également comporter un indicateur isWriteable
pour indiquer si vous pouvez créer des éléments multimédias dans l'album. Si cet indicateur n'est pas renvoyé, la valeur par défaut est false
. Elle dépend de l'accès accordé à votre application, y compris les suivants:
- l'auteur de l'album ;
- si elles sont partagées ou non ;
- Les champs d'application approuvés par l'utilisateur.
Cet indicateur peut changer si l'un de ces critères change. Pour en savoir plus, consultez Créer des albums. La réponse contient également un nextPageToken
. Pour en savoir plus, consultez la section Pagination.
La réponse pour les albums vides varie dans le sens où mediaItemsCount
et coverPhotoMediaItemId
sont définis sur 0 par défaut et sont omis de la réponse REST. Notez également que coverPhotoBaseUrl
pointe vers une image d'espace réservé par défaut.
Répertorier le contenu de la bibliothèque
Vous pouvez lister tous les éléments multimédias de la bibliothèque Google Photos de l'utilisateur. Les éléments archivés et supprimés sont exclus. Vous pouvez lister les éléments multimédias en fonction de leur contenu, de leur date et d'autres propriétés en appliquant des filtres. Si l'utilisateur n'a pas ajouté à sa bibliothèque un élément disponible dans l'onglet Partage de Google Photos, cet élément n'est pas inclus dans cette liste.
Pour récupérer un élément multimédia, appelez mediaItems.list.
REST
Voici un exemple de requête :
GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
}
La requête GET renvoie la réponse suivante:
{ "mediaItems": [ ... ], "nextPageToken": "token-for-pagination" }
Java
try { // Make a request to list all media items in the user's library // Iterate over all the retrieved media items // Pagination is handled automatically ListMediaItemsPagedResponse response = photosLibraryClient.listMediaItems(); for (MediaItem item : response.iterateAll()) { // Get some properties of a media item String id = item.getId(); String description = item.getDescription(); String mimeType = item.getMimeType(); String productUrl = item.getProductUrl(); String filename = item.getFilename(); } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all media items in the user's library // Iterate over all the retrieved media items // Pagination is handled automatically $response = $photosLibraryClient->listMediaItems(); foreach ($response->iterateAllElements() as $item) { // Get some properties of a media item /* @var $item \Google\Photos\Library\V1\MediaItem */ $id = $item->getId(); $description = $item->getDescription(); $mimeType = $item->getMimeType(); $productUrl = $item->getProductUrl(); $filename = $item->getFilename(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
La réponse contient une liste d'éléments multimédias, classés du plus récent au moins récent.
Pour en savoir plus, consultez mediaItems
. Il contient également un nextPageToken
, décrit plus en détail dans la section Pagination.
Liste du contenu de l'album
Pour répertorier tous les éléments multimédias d'un album, ajoutez le champ albumId
à votre requête de recherche. Pour en savoir plus sur albumId
, consultez Répertorier des albums et Répertorier des albums partagés. Si albumId
n'est pas valide, une erreur Bad Request
est renvoyée. Si l'ID est valide, mais que l'album n'existe pas pour l'utilisateur authentifié, une erreur Not Found
est renvoyée. Pour en savoir plus sur la gestion des erreurs,consultez les conseils sur l'amélioration des performances et les bonnes pratiques.
REST
Voici un exemple de requête :
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
"albumId": "album-id"
}
La requête POST renvoie la réponse suivante:
{ "mediaItems": [ ... ], "nextPageToken": "token-for-pagination" }
Java
try { // Make a request to list all media items in an album // Provide the ID of the album as a parameter in the searchMediaItems call // Iterate over all the retrieved media items SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(albumId); for (MediaItem item : response.iterateAll()) { // ... } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all media items in an album // Provide the ID of the album as a parameter in the searchMediaItems call // Iterate over all the retrieved media items $response = $photosLibraryClient->searchMediaItems(['albumId' => $albumId]); foreach ($response->iterateAllElements() as $item) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
La réponse contient un nextPageToken
et la liste des éléments multimédias. Contrairement à la liste du contenu de la bibliothèque, les éléments multimédias sont renvoyés dans leur ordre dans l'album. Pour en savoir plus, consultez mediaItems
et Pagination. L'utilisateur peut modifier l'ordre dans l'interface Google Photos.
Si albumId
est défini, vous ne pouvez pas appliquer de filtre à la liste des contenus d'albums.
Cela entraîne une erreur Bad Request
.
Répertorier les albums partagés
Vous pouvez récupérer la liste de tous les albums que l'utilisateur a partagés ou qui ont été partagés avec un utilisateur. Cette option est semblable à l'onglet "Partage" de l'application Google Photos.
Les albums partagés que l'utilisateur a ajoutés à sa bibliothèque Google Photos sont également renvoyés dans l'appel Lister les albums. Effectuez l'appel suivant pour répertorier les albums partagés via l'API Library:
REST
Voici un exemple de requête :
GET https://photoslibrary.googleapis.com/v1/sharedAlbums
La requête renvoie le résultat suivant:
{ "sharedAlbums": [...] "nextPageToken": "token-for-pagination" }
Java
try { // Make a request to list all albums that have been shared by the user // Iterate over all the albums in this list // Pagination is handled automatically ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums(); for (Album album : response.iterateAll()) { // .. } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all albums that have been shared by the user // Iterate over all the albums in this list // Pagination is handled automatically $response = $photosLibraryClient->listSharedAlbums(); foreach ($response->iterateAllElements() as $album) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Une liste d'albums est incluse dans sharedAlbums
. Pour en savoir plus, consultez Répertorier des albums. La réponse contient également un nextPageToken
.
Pour en savoir plus, consultez Pagination.
Les albums créés et partagés par votre application incluent une propriété shareInfo
supplémentaire. Pour en savoir plus, consultez Partager des contenus multimédias.
Répertorier les albums créés par l'application
Vous pouvez lister les albums créés par votre application avec excludeNonAppCreatedData
défini sur true
dans les appels suivants:
REST
Voici une demande GET visant à lister tous les albums de la bibliothèque Google Photos de l'utilisateur créés uniquement par votre application:
GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
Voici une demande GET visant à répertorier tous les albums partagés de la bibliothèque Google Photos de l'utilisateur créés uniquement par votre application:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
Java
try { // Make a request to list all albums that have been created by your app boolean excludeNonAppCreatedData = true; // Iterate over all the albums in this list // Pagination is handled automatically ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(excludeNonAppCreatedData); for (Album album : response.iterateAll()) { // .. } } catch (ApiException e) { // Handle error } try { // Make a request to list all shared albums that have been created by your app boolean excludeNonAppCreatedData = true; // Iterate over all the albums in this list // Pagination is handled automatically ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums(excludeNonAppCreatedData); for (Album album : response.iterateAll()) { // .. } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all albums that have been created by your app $response = $photosLibraryClient->listAlbums(['excludeNonAppCreatedData' => true]); // Iterate over all the albums in this list // Pagination is handled automatically foreach ($response->iterateAllElements() as $album) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error } try { // Make a request to list all shared albums that have been created by your app $response = $photosLibraryClient->listSharedAlbums(['excludeNonAppCreatedData' => true]); // Iterate over all the albums in this list // Pagination is handled automatically foreach ($response->iterateAllElements() as $album) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Pagination pour REST
Pour améliorer les performances, les méthodes qui renvoient un grand nombre de résultats (telles que les méthodes de liste) peuvent paginer la réponse. Le nombre maximal de résultats par page est donné par le paramètre pageSize
.
Pour les appels à mediaItems:search
et mediaItems:list
, la taille de page par défaut est de 25 éléments. Nous recommandons cette taille de page, car elle permet d'équilibrer la taille de la réponse et le taux de remplissage. La taille de page maximale pour les requêtes de recherche et de liste d'éléments multimédias est de 100 éléments.
La taille de page par défaut et recommandée pour la création d'une liste d'albums est de 20 albums, avec un maximum de 50 albums.
Lorsque le nombre de résultats disponibles est supérieur à la taille de la page, la réponse inclut une valeur nextPageToken
, qui indique à votre application qu'il y a davantage de résultats à extraire du serveur.
Exemple
Vous devez ajouter nextPageToken
aux requêtes suivantes dans le paramètre pageToken
, comme illustré dans l'exemple suivant. Spécifiez pageToken
avec les autres paramètres requis pour l'opération, dans le corps de la requête ou en tant que paramètre de requête.
Demande n° 1
{ "pageSize": "5", "filters": { … } }
Réponse 1
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
Demande 2
{ "pageSize": "5", "filters": { … }, "pageToken": "page-token" }
Réponse 2
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
Continuez ce schéma jusqu'à ce qu'il n'y ait plus d'objets nextPageToken
.
Le nextPageToken
n'est valide que pour la même requête. Si des paramètres sont modifiés, un nextPageToken
précédemment utilisé ne doit pas être utilisé dans la même requête.