Lister les éléments multimédias et les albums créés par l'application

Champs d'application d'autorisation requis

La liste des contenus créés par l'application nécessite la portée photoslibrary.readonly.appcreateddata. Pour en savoir plus sur les champs d'application, consultez la section Champs d'application des autorisations.

Présentation

L'API Library vous permet de lister et d'accéder aux éléments multimédias créés par votre application.

Voici quelques-unes des principales fonctionnalités de la fonctionnalité de mise en ligne d'éléments multimédias :

• Lister les éléments multimédias d'albums spécifiques créés par l'application ou de l'intégralité de la bibliothèque créée par l'application

• Appliquez des filtres (date, catégorie de contenu, type de contenu) lors de la création d'une fiche pour affiner les résultats.

• Récupérez des objets mediaItem avec des informations essentielles telles que des liens directs et des métadonnées.

La liste du contenu de la bibliothèque et des albums renvoie une liste d'éléments multimédias. Les enrichissements qui font 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. Un 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 les pages Accéder aux éléments multimédias et mediaItems.

Lister les albums créés par l'application

Vous pouvez répertorier les albums créés par votre application à l'aide de albums.list.

GET https://photoslibrary.googleapis.com/v1/albums

{
  "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"
}

Chaque album renvoyé est associé à un ID qui permet de récupérer son contenu, comme indiqué dans List album contents (Liste du 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 que l'utilisateur peut ouvrir.

coverPhotoMediaItemId contient l'ID de l'é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.

La réponse contient également un nextPageToken. Pour en savoir plus, consultez la section Pagination.

La réponse pour les albums vides varie dans la mesure 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.

Lister le contenu des bibliothèques créées par l'application

Vous pouvez lister tous les éléments multimédias de la bibliothèque Google Photos de l'utilisateur qui ont été créés par votre application. Il ne prend pas en compte les éléments archivés et supprimés. 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.

Pour lister des éléments multimédias, appelez mediaItems.list.

GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
}

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

La réponse contient une liste d'éléments multimédias, classés du plus récent au plus ancien. Pour en savoir plus, consultez les sections sur mediaItems Il contient également un nextPageToken, décrit plus en détail dans la section Pagination.

Afficher le contenu d'un album

Pour lister 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 des albums. 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 pages Conseils sur l'amélioration des performances et Bonnes pratiques.

POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
  "albumId": "album-id"
}

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

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 l'ordre de l'album. Pour en savoir plus, consultez les sections 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 lorsque vous listez le contenu d'un album. Cela entraîne une erreur Bad Request.

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 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 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 pagination 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 liste des 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 un nextPageToken, qui indique à votre application qu'il existe d'autres résultats à extraire du serveur.

Exemple

Vous devez ajouter nextPageToken aux requêtes ultérieures dans le paramètre pageToken, comme illustré dans l'exemple suivant. Spécifiez pageToken avec les 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.

Requête 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.

L'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.