Erforderliche Autorisierungsbereiche
Die Google Photos Library API umfasst mehrere Bereiche für den Zugriff auf Medienelemente und Alben. Die von verschiedenen Aufrufen zurückgegebenen Medienelemente unterscheiden sich je nach Umfang vom Entwickler angefordert wurden.
Der Bereich photoslibrary.readonly
ermöglicht den Zugriff auf alle Medienelemente im
in der Bibliothek des Nutzers. Der Bereich photoslibrary.readonly.appcreateddata
ermöglicht Zugriff
die von der App erstellt wurden. Weitere Informationen finden Sie unter
Autorisierungsbereiche.
Übersicht
Eine wichtige Verwendung der API besteht darin, Medienelemente aufzulisten, die der Nutzer gesichert hat in Google Fotos hochladen. Elemente in einem bestimmten Album oder aus dem gesamten Fotogalerie (Standardansicht in der Google Fotos App) aufgelistet werden.
Sie können Fotos mithilfe von Filtern auswählen. die einem bestimmten Datum, einer bestimmten Inhaltskategorie oder einem Medientyp entsprechen. aus der Bibliothek des Nutzers. Diese Funktion wird nicht unterstützt, wenn Sie Artikel auflisten aus Alben.
Wenn Sie die Bibliotheks- und Albuminhalte auflisten, wird eine Liste der Medienelemente zurückgegeben.
Anreicherungen, die Teil eines Albums sind
enthalten sind. Medienelemente beschreiben ein Foto, ein Video oder andere Medien. A
mediaItem
enthält einen direkten Link zum Element, einen Link zum Element in
Google Fotos und andere relevante Metadaten. Weitere Informationen finden Sie unter
Auf Medienelemente zugreifen und
mediaItems
Alben auflisten
Sie können eine Liste der Alben des Nutzers mithilfe von albums.list.
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" }
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 }
Jedes zurückgegebene Album verfügt über eine ID, die zum Abrufen des Inhalts der wie unter Albuminhalte auflisten dargestellt. Außerdem den Titel und die Anzahl der darin enthaltenen Medienelemente enthält.
Das productUrl
verweist auf das Album in Google Fotos, das ein
die der Nutzer öffnet.
coverPhotoMediaItemId
enthält das Medienelement
ID, die
steht für das Titelbild dieses Albums. Um auf dieses Titelbild zuzugreifen, verwende
coverPhotoBaseUrl
Sie sollten die coverPhotoBaseUrl
nicht direkt verwenden, ohne
unter Angabe zusätzlicher zusätzlicher
Parameter.
Alben, die im Konto des Nutzers erstellt oder zum Konto des Nutzers hinzugefügt wurden
Konto und die deine App freigegeben hat, füge eine zusätzliche shareInfo
-Property hinzu.
Weitere Informationen
Alben können auch mit einem isWriteable
-Flag versehen sein, um anzugeben, ob Sie Medien erstellen können.
Elemente im Album. Dieses Flag ist standardmäßig auf false
gesetzt, wenn es nicht zurückgegeben wird. Es ist
abhängig von den Zugriffsrechten, die Ihrer Anwendung gewährt wurden, darunter:
- Wer hat das Album erstellt?
- Ob es freigegeben ist oder nicht
- Was umfasst der Nutzer? genehmigt wurde.
Diese Markierung kann sich ändern, wenn sich eines dieser Kriterien ändert. Weitere Informationen finden Sie unter
Alben erstellen Die
Antwort enthält auch ein nextPageToken
. Weitere Informationen finden Sie unter
Paginierung:
Die Antwort für leere Alben variiert in dieser Hinsicht: mediaItemsCount
und
coverPhotoMediaItemId
sind standardmäßig auf 0 gesetzt und werden in der REST weggelassen.
Antwort. Beachten Sie außerdem, dass coverPhotoBaseUrl
auf einen Standardplatzhalter verweist
Bild.
Bibliotheksinhalte auflisten
Sie können alle Medienelemente aus der Google Fotos-Galerie des Nutzers auflisten. Archivierte und gelöschte Elemente sind nicht enthalten. Sie können Medienelemente anhand ihrer Inhalte, Datum und andere Eigenschaften zu erstellen, Filter. Wenn der Nutzer kein das auf dem Tab Teilen ihrer Google Fotos verfügbar ist, Bibliothek befindet, ist dieser Artikel nicht in dieser Liste enthalten.
Rufen Sie zum Abrufen eines Medienelements mediaItems.list.
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" }
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 }
Die Antwort enthält eine Liste von Medienelementen, sortiert vom neuesten zum aktuellsten.
Weitere Informationen finden Sie unter mediaItems
. Außerdem
enthält ein nextPageToken
, das ausführlicher beschrieben wird unter
Paginierung:
Albuminhalte auflisten
Wenn Sie alle Medienelemente in einem Album auflisten möchten, fügen Sie das Feld albumId
zu Ihrem
Suchanfrage. Weitere Informationen zu albumId
finden Sie unter Liste
Alben und Geteilte Alben auflisten. Wenn
wenn albumId
ungültig ist, wird der Fehler Bad Request
zurückgegeben. Wenn die ID gültig ist,
aber das Album für den authentifizierten Nutzer nicht vorhanden ist, wird der Fehler Not Found
angezeigt.
zurückgegeben. Weitere Informationen zur Fehlerbehandlung finden Sie unter Leistung
Tipps und Beste
.
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" }
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 }
Die Antwort enthält ein nextPageToken
und die Liste der Medienelemente. Gefällt mir nicht, wenn
Bibliotheksinhalte aufgelistet, werden die Medienelemente in ihrer Reihenfolge im
Album. Weitere Informationen finden Sie unter
mediaItems
und Paginierung. Der Nutzer kann die Bestellung im
Google Fotos-Benutzeroberfläche
Wenn albumId
festgelegt ist, können Sie beim Auflisten von Albuminhalten keinen Filter anwenden.
Dies führt zum Fehler Bad Request
.
Geteilte Alben auflisten
Sie können eine Liste aller Alben abrufen, die der Nutzer freigegeben hat oder die die für einen Nutzer freigegeben wurden. Dies ähnelt dem Tab "Teilen" im Google Fotos App.
Geteilte Alben, die der Nutzer seiner Google Fotos-Galerie hinzugefügt hat werden auch im Aufruf listing album zurückgegeben. Machen Sie die folgenden Aufruf zum Auflisten freigegebener Alben über die Library API:
REST
Ein Beispiel für eine Anfrage:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums
Die Anfrage gibt das folgende Ergebnis zurück:
{ "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 }
In sharedAlbums
ist eine Liste mit Alben enthalten. Weitere Informationen finden Sie unter
Alben auflisten Die Antwort enthält auch ein nextPageToken
.
Weitere Informationen finden Sie unter Paginierung.
Alben, die von deiner App erstellt und geteilt wurden, enthalten zusätzliche shareInfo
Property. Weitere Informationen finden Sie unter Freigeben
Medien.
Erstellte Alben der App auflisten
Sie können Alben auflisten, die von Ihrer App erstellt wurden.
excludeNonAppCreatedData
wurde in den folgenden Aufrufen auf true
gesetzt:
REST
Hier ist eine GET-Anfrage zum Auflisten aller Alben aus dem Nur von Ihrer App erstellte Google Fotos-Galerie:
GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
Hier ist eine GET-Anfrage zum Auflisten aller geteilten Alben aus dem Nur von Ihrer App erstellte Google Fotos-Galerie:
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 }
Paginierung für REST
Zur Verbesserung der Leistung sollten Methoden, die eine große Anzahl von Ergebnissen zurückgeben (z. B.
list-Methoden) können die Antwort paginieren. Die maximale Anzahl der Ergebnisse pro
Seite wird durch den Parameter pageSize
angegeben.
Für Aufrufe von mediaItems:search
und mediaItems:list
ist die Standardseitengröße
25 Elemente. Wir empfehlen diese Seitengröße, da sie ein Gleichgewicht zwischen der
die Größe der Antwort und die Ausführungsrate. Die maximale Seitengröße für Medienelemente
Such- und Listenanfragen
100 Elemente enthalten.
Die standardmäßige und empfohlene Seitengröße beim Auflisten von Alben beträgt 20 Alben, wobei Maximal 50 Alben.
Ist die Anzahl der verfügbaren Ergebnisse größer als die Seitengröße, wird die Antwort
enthält ein nextPageToken
, das Ihrer Anwendung anzeigt, dass
zum Abrufen weiterer Ergebnisse vom Server.
Beispiel
Sie müssen den nextPageToken
an nachfolgende Anfragen im Parameter anhängen.
pageToken
, wie im folgenden Beispiel gezeigt. pageToken
zusammen angeben
mit anderen für den Vorgang erforderlichen Parametern, entweder im Text des
-Anforderung oder als Abfrageparameter verwendet werden.
Anfrage Nr. 1
{ "pageSize": "5", "filters": { … } }
Antwort 1
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
Anfrage Nr. 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 wurde, sollte eine zuvor verwendete nextPageToken
nicht im selben