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 renvoyés par les différents appels diffèrent selon les champs d'application ont été demandées par le développeur.
Le champ d'application photoslibrary.readonly
permet d'accéder à tous les éléments multimédias dans
bibliothèque de l'utilisateur. Le niveau d'accès photoslibrary.readonly.appcreateddata
autorise l'accès
uniquement aux éléments multimédias
créés par l'application. Pour en savoir plus, consultez
Champs d'application des autorisations
Présentation
L'API permet notamment de lister les éléments multimédias sauvegardés par l'utilisateur. à Google Photos. Éléments d'un album spécifique ou de l'intégralité de l'album de l'utilisateur bibliothèque (vue par défaut dans l'application Google Photos).
Vous pouvez utiliser des filtres pour sélectionner des photos. qui correspondent à une date, une catégorie de contenu ou un type de support spécifique lorsque vous répertoriez des éléments de la bibliothèque de l'utilisateur. Cette fonctionnalité n'est pas disponible lorsque vous affichez des éléments depuis albums.
L'affichage du contenu de la bibliothèque et de l'album renvoie une liste d'éléments multimédias.
Enrichissements faisant partie d'un album
ne sont pas incluses. Les éléments multimédias décrivent une photo, une vidéo ou un autre contenu multimédia. A
mediaItem
inclut un lien direct vers l'élément, un lien vers l'élément dans
Google Photos et 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 en utilisant 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 identifiant qui peut être utilisé pour récupérer le contenu de album, comme indiqué dans la section Consulter le contenu des albums. Il y a aussi inclut le titre et le nombre d'éléments multimédias qu'il contient.
Le productUrl
pointe vers l'album dans Google Photos qui peut être un
ouvert par l'utilisateur.
coverPhotoMediaItemId
contient l'élément multimédia.
ID 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
en spécifiant des
paramètres.
Les albums créés ou ajoutés au compte de l'utilisateur
et partagée par votre application, ajoutez 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 contenus multimédias
éléments de l'album. Si cet indicateur n'est pas renvoyé, la valeur par défaut est false
. Il est
dépend de l'accès accordé à votre application, y compris:
- l'auteur de l'album ;
- S'il est partagé ou non.
- les champs d'application auxquels l'utilisateur s'applique ; a approuvé.
Cet indicateur peut changer si l'un de ces critères change. Pour en savoir plus, consultez
Créer des albums La
La réponse contient également un nextPageToken
. Pour en savoir plus, consultez
Pagination :
La réponse pour les albums vides varie dans la mesure où mediaItemsCount
et
Les champs coverPhotoMediaItemId
sont définis sur 0 par défaut et sont omis de l'API REST
de réponse. Notez également que coverPhotoBaseUrl
pointe vers un espace réservé par défaut.
l'image.
Répertorier le contenu de la bibliothèque
Vous pouvez répertorier tous les éléments multimédias de la bibliothèque Google Photos de l'utilisateur. Il exclut les éléments archivés et supprimés. Vous pouvez répertorier des éléments multimédias en fonction de leur le contenu, la date et d'autres propriétés en appliquant filtres. Si l'utilisateur n'a pas ajouté de disponible dans l'onglet Partage de son compte Google Photos bibliothèque, cet article ne figure pas 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 les sections sur mediaItems
Il y a aussi
contient un nextPageToken
, décrit plus en détail dans
Pagination :
Lister le 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 Liste
albums et Liste 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é. Pour en savoir plus sur la gestion des erreurs,consultez la section Performances
conseils 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. Je n'aime plus
listant le contenu de la bibliothèque, les éléments multimédias sont renvoyés par ordre d'affichage dans le
album. Pour en savoir plus, consultez
mediaItems
et Pagination. L'utilisateur peut modifier la commande dans le
Interface Google Photos.
Si albumId
est défini, vous ne pouvez pas appliquer de filtre lorsque vous listez le contenu d'un album.
Cela entraîne une erreur Bad Request
.
Liste des 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. Cet onglet est similaire à celui de l'onglet "Partage" Application Google Photos.
Albums partagés que l'utilisateur a ajoutés à sa bibliothèque Google Photos sont également renvoyées dans l'appel listing albums. Faites en sorte que le 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
Lister des albums : La réponse contient également un nextPageToken
.
Pour en savoir plus, consultez la section Pagination.
Les albums créés et partagés par votre application incluent un shareInfo
supplémentaire
. Pour en savoir plus, consultez la section Partager
médias.
Lister les albums créés par une application
Vous pouvez répertorier les albums qui ont été créés par votre application avec
excludeNonAppCreatedData
défini sur true
dans les appels suivants:
REST
Voici une demande GET pour lister tous les albums du Bibliothèque Google Photos créée 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 pour répertorier tous les albums partagés du compte Bibliothèque Google Photos créée 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 (comme
méthodes list) peuvent paginer la réponse. Le nombre maximal de résultats dans chaque
est fournie par le paramètre pageSize
.
Pour les appels à mediaItems:search
et mediaItems:list
, la taille de page par défaut est
25 articles. Nous vous recommandons d'utiliser cette taille de page, car elle permet de trouver le juste équilibre
la taille de la réponse et le taux de remplissage. Taille de page maximale pour l'élément multimédia
requêtes de recherche et de liste
est de 100 éléments.
Lors de la création d'une liste d'albums, la taille de page par défaut et recommandée est de 20 albums, avec une 50 albums au maximum.
Lorsque le nombre de résultats disponibles est supérieur à la taille de la page, la réponse
inclut un nextPageToken
, qui indique à votre application qu'il existe
plus 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 les pageToken
ensemble.
avec les autres paramètres requis pour l'opération, soit dans le corps de la
une requête ou un paramètre de requête.
Demande n° 1
{ "pageSize": "5", "filters": { … } }
Réponse 1
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
Demande n° 2
{ "pageSize": "5", "filters": { … }, "pageToken": "page-token" }
Réponse 2
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
Continuez ainsi jusqu'à ce qu'il n'y ait plus d'objets nextPageToken
.
Le champ nextPageToken
n'est valide que pour la même requête. Si des paramètres sont
modifié, un élément nextPageToken
précédemment utilisé ne doit pas être utilisé dans le même
requête.