Lister le contenu, les albums et les éléments multimédias de la bibliothèque

Champs d'application des autorisations requis

L'API Library de Google Photos contient plusieurs champs d'application utilisés pour accéder aux éléments multimédias et aux albums. Les éléments multimédias renvoyés à partir de divers appels varient selon les 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 autorise uniquement l'accès aux éléments multimédias créés par l'application. Pour en savoir plus, consultez la section Champs d'application des autorisations.

Présentation

Il est important d'utiliser l'API pour lister les éléments multimédias que l'utilisateur a sauvegardés dans Google Photos. Vous pouvez afficher la liste des éléments d'un album donné ou l'intégralité de la bibliothèque d'un utilisateur (la 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écifié lorsque vous répertoriez des éléments dans la bibliothèque de l'utilisateur. Cette fonctionnalité n'est pas disponible lorsque vous répertoriez des éléments issus d'albums.

La liste du contenu de la bibliothèque et de l'album 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 un autre contenu multimédia. Une propriété mediaItem inclut un lien direct vers l'élément, un lien vers celui-ci dans Google Photos et d'autres métadonnées pertinentes. Pour en savoir plus, consultez Accéder aux éléments multimédias et mediaItems.

Attention:Ne mettez pas en cache les photos et vidéos des utilisateurs. Stockez plutôt l'élément multimédia id et demandez à nouveau ses informations lorsque vous en avez besoin. Les images peuvent changer et l'accès direct via baseUrl expire au bout de 60 minutes. Pour en savoir plus, consultez Accéder aux éléments multimédias.

Répertorier les 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 peut être utilisé pour récupérer le contenu de l'album, comme indiqué dans la section Répertorier le contenu de l'album. Il inclut également le titre et le nombre d'éléments multimédias qu'il contient.

productUrl pointe vers l'album dans Google Photos qui peut être ouvert par l'utilisateur.

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 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 les albums. Cette option est définie par défaut sur false si elle n'est pas renvoyée. Cela dépend de l'accès accordé à votre application, y compris:

• Auteur de l'album
• S'il est partagé ou non.
• Champ d'application que l'utilisateur a approuvé.

Cette option 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 par défaut sur 0 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 répertorier tous les éléments multimédias de la bibliothèque Google Photos de l'utilisateur. Sont exclus les éléments archivés et supprimés. Vous pouvez répertorier des é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é d'élément disponible dans l'onglet Partage de Google Photos à sa bibliothèque, 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, du plus récent au moins récent. Pour en savoir plus, consultez les sections sur mediaItems Il contient également un nextPageToken, décrit plus en détail dans la section Pagination.

Répertorier le contenu des albums

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 l'élément 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 pages Conseils pour l'amélioration des performances et 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 nextPageToken et la liste des éléments multimédias. Contrairement à la liste des contenus de la bibliothèque, les éléments multimédias sont renvoyés selon leur ordre dans l'album. Pour en savoir plus, consultez mediaItems et Pagination. L'utilisateur peut modifier la commande dans l'interface Google Photos.

Si albumId est défini, vous ne pouvez pas appliquer de filtre lorsque vous répertoriez le contenu d'un album. 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 qu'il a partagés avec lui. Il 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 listing albums. Effectuez l'appel suivant pour obtenir la liste des 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
}

sharedAlbums contient une liste d'albums. Pour en savoir plus, consultez la section Répertorier des albums. La réponse contient également un nextPageToken. Pour en savoir plus, consultez la section Pagination.

Les albums que votre application a créés et partagés 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 répertorier les albums créés par votre application avec excludeNonAppCreatedData défini sur true dans les appels suivants:

• albums.list
• sharedAlbums.list

REST

Voici une requête GET permettant de lister tous les albums de la bibliothèque Google Photos de l'utilisateur 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 requête GET permettant de lister tous les albums partagés de la bibliothèque Google Photos de l'utilisateur 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 (par exemple, les méthodes de liste) peuvent paginer la réponse. Le nombre maximal de résultats sur chaque page est indiqué 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 vous recommandons d'utiliser cette taille de page, car elle offre un équilibre entre la taille de la réponse et le taux de remplissage. La taille maximale de la page 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 recommandée 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 réponse nextPageToken, qui indique à votre application qu'il peut extraire davantage de résultats du serveur.

Remarque:Le paramètre pageSize est un nombre maximal. Il est possible que moins de résultats soient renvoyés que ce qui est demandé.

Exemple

Vous devez ajouter nextPageToken aux requêtes suivantes dans le paramètre pageToken, comme illustré dans l'exemple suivant. Spécifiez pageToken avec d'autres paramètres requis pour l'opération, soit dans le corps de la requête, soit en tant que 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 ce modèle jusqu'à ce qu'il n'y ait plus d'objets nextPageToken.

nextPageToken n'est valide que pour la même requête. Si des paramètres sont modifiés, une valeur nextPageToken précédemment utilisée ne doit pas être utilisée dans la même requête.

Remarque : L'existence de nextPageToken est le seul indicateur indiquant si d'autres résultats doivent être récupérés du serveur. Ne comptez pas le nombre de résultats pour déterminer si vous devez utiliser votre nextPageToken. Une requête peut renvoyer moins de résultats que la taille de page demandée. Si un nextPageToken est présent, vous pouvez envoyer une demande de résultats supplémentaires après votre requête initiale.