Erforderliche Autorisierungsbereiche
Für die Auflistung von von Apps erstellten Inhalten ist der Umfang photoslibrary.readonly.appcreateddata erforderlich. Weitere Informationen zu Bereichen finden Sie unter Autorisierungsbereiche.
Übersicht
Mit der Library API können Sie Medienelemente auflisten und auf sie zugreifen, die von Ihrer Anwendung erstellt wurden.
Zu den wichtigsten Funktionen von Medienelementen gehören:
- Medieninhalte aus bestimmten in der App erstellten Alben oder der gesamten App-Bibliothek auflisten
Filter (Datum, Inhaltskategorie, Medientyp) anwenden, um die Ergebnisse einzugrenzen
mediaItem-Objekte mit wichtigen Details wie Direktlinks und Metadaten abrufen
Wenn du die Inhalte der Bibliothek und des Albums auflistest, wird eine Liste der Medienelemente zurückgegeben.
Anreicherungen, die zu einem Album gehören, sind nicht enthalten. Medienelemente beschreiben ein Foto, Video oder andere Medien. Ein mediaItem enthält einen direkten Link zum Artikel, einen Link zum Artikel in Google Fotos und andere relevante Metadaten. Weitere Informationen finden Sie unter Auf Medienelemente zugreifen und mediaItems.
In der App erstellte Alben auflisten
Sie können mit albums.list Alben auflisten, die mit Ihrer App erstellt wurden.
REST
Ein Beispiel für eine Anfrage:
GET https://photoslibrary.googleapis.com/v1/albums
Die Anfrage gibt das folgende Ergebnis zurück:
{
"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"
}Jedes zurückgegebene Album hat eine ID, mit der der Inhalt des Albums abgerufen werden kann (siehe Albuminhalte auflisten). Außerdem enthält er den Titel und die Anzahl der darin enthaltenen Medienelemente.
Der productUrl verweist auf das Album in Google Fotos, das der Nutzer öffnen kann.
coverPhotoMediaItemId enthält die Medienelement-ID, die dem Cover dieses Albums entspricht. Verwenden Sie coverPhotoBaseUrl, um auf dieses Titelbild zuzugreifen.
Sie sollten coverPhotoBaseUrl nicht direkt verwenden, ohne zusätzliche Parameter anzugeben.
Die Antwort enthält auch ein nextPageToken. Weitere Informationen finden Sie unter Paginierung.
Die Antwort für leere Alben unterscheidet sich dadurch, dass mediaItemsCount und coverPhotoMediaItemId standardmäßig auf 0 gesetzt und aus der REST-Antwort entfernt werden. Beachten Sie auch, dass coverPhotoBaseUrl auf ein Standard-Platzhalterbild verweist.
Von der App erstellte Bibliotheksinhalte auflisten
Sie können alle Medienelemente aus der Google Fotos-Mediathek des Nutzers auflisten, die von Ihrer App erstellt wurden. Archivierte und gelöschte Elemente sind davon nicht betroffen. Sie können Medienelemente anhand ihres Inhalts, Datums und anderer Eigenschaften auflisten, indem Sie Filter anwenden.
Wenn Sie Medienelemente auflisten möchten, rufen Sie mediaItems.list auf.
REST
Ein Beispiel für eine Anfrage:
GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
}Die GET-Anfrage gibt die folgende Antwort zurück:
{
"mediaItems": [
...
],
"nextPageToken": "token-for-pagination"
}Die Antwort enthält eine Liste von Medienelementen, die von der neuesten bis zur ältesten sortiert sind.
Weitere Informationen finden Sie unter mediaItems. Außerdem enthält es eine nextPageToken, die im Abschnitt Paginierung genauer beschrieben wird.
Albuminhalt auflisten
Wenn du alle Medienelemente in einem Album auflisten möchtest, füge deiner Suchanfrage das Feld albumId hinzu. Weitere Informationen zu albumId findest du unter Alben auflisten. Wenn albumId ungültig ist, wird ein Bad Request-Fehler zurückgegeben. Wenn die ID gültig ist, das Album für den authentifizierten Nutzer aber nicht vorhanden ist, wird der Fehler Not Found zurückgegeben. Weitere Informationen zur Fehlerbehandlung finden Sie unter Leistungstipps und Best Practices.
REST
Ein Beispiel für eine Anfrage:
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
"albumId": "album-id"
}Die POST-Anfrage gibt die folgende Antwort zurück:
{
"mediaItems": [
...
],
"nextPageToken": "token-for-pagination"
}Die Antwort enthält einen nextPageToken und die Liste der Medienelemente. Im Gegensatz zum Auflisten von Mediathekinhalten werden die Medienelemente in der Reihenfolge zurückgegeben, in der sie im Album angezeigt werden. Weitere Informationen finden Sie unter mediaItems und Paginierung. Der Nutzer kann die Bestellung in der Google Fotos-Benutzeroberfläche bearbeiten.
Wenn albumId festgelegt ist, kannst du beim Auflisten von Albuminhalten keinen Filter anwenden.
Dies führt zum Fehler Bad Request.
Paginierung für REST
Zur Leistungssteigerung kann die Antwort bei Methoden, die eine große Anzahl von Ergebnissen zurückgeben (z. B. Listenmethoden), paginariert werden. Die maximale Anzahl von Ergebnissen auf jeder Seite wird durch den Parameter pageSize angegeben.
Bei Aufrufen von mediaItems.search und mediaItems.list beträgt die Standardseitengröße 25 Elemente. Wir empfehlen diese Seitengröße, da sie ein Gleichgewicht zwischen der Größe der Antwort und der Ausfüllrate schafft. Die maximale Seitengröße für Such- und Listenanfragen für Medienelemente beträgt 100 Elemente.
Die Standard- und empfohlene Seitengröße für Albenlisten ist 20 Alben, maximal 50 Alben.
Wenn die Anzahl der verfügbaren Ergebnisse die Seitengröße überschreitet, enthält die Antwort ein nextPageToken. Dies weist Ihre Anwendung darauf hin, dass noch weitere Ergebnisse vom Server abgerufen werden müssen.
Beispiel
Sie müssen nextPageToken den nachfolgenden Anfragen im Parameter pageToken anhängen, wie im folgenden Beispiel gezeigt. Geben Sie pageToken zusammen mit anderen für den Vorgang erforderlichen Parametern an, entweder im Anfragetext oder als Abfrageparameter.
Anfrage Nr. 1
{
"pageSize": "5",
"filters": { … }
}Antwort 1
{
"mediaItem": [ … ],
"nextPageToken": "next-page-token"
}Anfrage 2
{
"pageSize": "5",
"filters": { … },
"pageToken": "page-token"
}Antwort 2
{
"mediaItem": [ … ],
"nextPageToken": "next-page-token"
}Fahren Sie mit diesem Muster fort, bis keine nextPageToken-Objekte mehr vorhanden sind.
Die nextPageToken ist nur für dieselbe Anfrage gültig. Wenn Parameter geändert werden, sollte in derselben Anfrage kein zuvor verwendeter nextPageToken verwendet werden.