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

Champs d'application des autorisations requis

Répertorier le contenu créé par l'application nécessite l'photoslibrary.readonly.appcreateddata le champ d'application. Pour en savoir plus sur les champs d'application, consultez la section Autorisation champs d'application.

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

• Appliquer des filtres (date, catégorie de contenu, média) type) pour affiner la recherche résultats

• Récupérer mediaItem objets contenant des détails essentiels tels que des liens directs et des métadonnées.

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

Lister les albums créés par une application

Vous pouvez répertorier les albums qui ont été créés par votre application en utilisant 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é possède un ID qui peut être utilisé pour récupérer le contenu de 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.

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 couverture photo de cet album. Pour accéder à cette image de couverture, utilisez coverPhotoBaseUrl. Vous ne devez pas utiliser coverPhotoBaseUrl directement sans spécifier paramètres supplémentaires.

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.

Lister le contenu de la bibliothèque créée par l'application

Vous pouvez lister tous les éléments multimédias de la bibliothèque Google Photos de l'utilisateur créés par votre application. Cela exclut les éléments archivés et supprimés. Toi peut répertorier des éléments multimédias en fonction de leur contenu, de leur date et d'autres propriétés l'application de 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 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 :

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 Lister 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 les erreurs des performances,consultez les 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 aux cas 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.

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 cette taille de page, car elle offre un équilibre entre 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 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 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.