Mediathek-Inhalte, Alben und Medienelemente auflisten

Erforderliche Autorisierungsbereiche

Die Google Photos Library API enthält mehrere Bereiche für den Zugriff auf Medienelemente und Alben. Welche Medienelemente von verschiedenen Aufrufen zurückgegeben werden, hängt davon ab, welche Bereiche vom Entwickler angefordert wurden.

Mit dem Bereich photoslibrary.readonly kann auf alle Medienelemente in der Mediathek des Nutzers zugegriffen werden. Der Bereich photoslibrary.readonly.appcreateddata ermöglicht den Zugriff nur auf Medienelemente, die von der Anwendung erstellt wurden. Weitere Informationen finden Sie unter Autorisierungsbereiche.

Überblick

Die API dient vor allem dazu, Medienelemente aufzulisten, die der Nutzer in Google Fotos gesichert hat. Es können Elemente aus einem bestimmten Album oder aus der gesamten Bibliothek des Nutzers (die Standardansicht in der Google Fotos App) aufgelistet werden.

Sie können Filter verwenden, um Fotos auszuwählen, die einem bestimmten Datum, einer Inhaltskategorie oder einem Medientyp entsprechen, wenn Sie Elemente aus der Fotogalerie des Nutzers auflisten. Diese Funktion wird nicht unterstützt, wenn Sie Elemente aus Alben auflisten.

Wenn Sie den Inhalt der Mediathek und des Albums auflisten, wird eine Liste mit Medienelementen zurückgegeben. Anreicherungen, die Teil eines Albums sind, werden nicht berücksichtigt. Medienelemente beschreiben ein Foto, Video oder andere Medien. Ein 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.

Achtung :Speichern Sie Nutzerfotos und -videos nicht im Cache. Speichern Sie stattdessen das Medienelement id und fordern Sie seine Details bei Bedarf noch einmal an. Bilder können sich ändern. Der direkte Zugriff über die baseUrl läuft nach 60 Minuten ab. Weitere Informationen finden Sie unter Auf Medienelemente zugreifen.

Alben auflisten

Mit albums.list können Sie eine Liste der Alben des Nutzers abrufen.

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 hat eine ID, mit der der Inhalt des Albums abgerufen werden kann (siehe Albuminhalte auflisten). Außerdem sind der Titel und die Anzahl der darin enthaltenen Medienelemente enthalten.

productUrl verweist auf das Album in Google Fotos, das vom Nutzer geöffnet werden kann.

coverPhotoMediaItemId enthält die ID des Medienelements, die das Titelbild des Albums darstellt. Verwenden Sie coverPhotoBaseUrl, um auf dieses Titelbild zuzugreifen. Sie sollten coverPhotoBaseUrl nicht direkt verwenden, ohne zusätzliche Parameter anzugeben.

Alben, die im Konto des Nutzers erstellt oder dem Konto des Nutzers hinzugefügt wurden und die von Ihrer App freigegeben wurden, enthalten eine zusätzliche shareInfo-Property. Weitere Informationen finden Sie unter Medien freigeben.

Alben können auch ein isWriteable-Flag haben, das angibt, ob Sie Medien im Album erstellen können. Dieses Flag ist standardmäßig auf false gesetzt, wenn es nicht zurückgegeben wird. Dazu gehören:

• Wer das Album erstellt hat
• Ob es geteilt wird oder nicht.
• Welche Bereiche der Nutzer genehmigt hat.

Dieses Flag 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 insofern, als dass mediaItemsCount und coverPhotoMediaItemId standardmäßig auf 0 gesetzt sind und in der REST-Antwort ausgelassen werden. Außerdem verweist coverPhotoBaseUrl auf ein Standardplatzhalterbild.

Inhalte der Mediathek auflisten

Sie können sich alle Medienelemente aus der Google Fotos-Galerie des Nutzers anzeigen lassen. Archivierte und gelöschte Elemente sind nicht enthalten. Sie können Medienelemente anhand von Filtern nach Inhalt, Datum und anderen Eigenschaften auflisten. Wenn der Nutzer ein Element, das auf dem Tab Teilen seiner Google Fotos-Galerie nicht verfügbar ist, seiner Bibliothek nicht hinzugefügt hat, ist dieses Element nicht in der Liste enthalten.

Um ein Medienelement abzurufen, 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"
}

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, die in absteigender Reihenfolge sortiert sind. Weitere Informationen finden Sie unter mediaItems. Es enthält auch ein nextPageToken, das unter Paginierung ausführlicher beschrieben wird.

Albuminhalt auflisten

Wenn Sie alle Medienelemente eines Albums auflisten möchten, fügen Sie der Suchanfrage das Feld albumId hinzu. Weitere Informationen zu albumId finden Sie unter Alben auflisten und Geteilte Alben auflisten. Wenn albumId ungültig ist, wird der Fehler Bad Request 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 Tipps zur Leistungssteigerung 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"
}

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. Im Gegensatz zu Mediathekinhalten werden die Medienelemente in der Reihenfolge ihrer Reihenfolge im Album zurückgegeben. Weitere Informationen finden Sie unter mediaItems und Pagination. Der Nutzer kann die Reihenfolge in der Google Fotos-Benutzeroberfläche bearbeiten.

Wenn albumId festgelegt ist, können Sie beim Auflisten der Albuminhalte 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 mit ihm geteilt wurden. Dies ähnelt dem Tab „Teilen“ in der Google Fotos App.

Geteilte Alben, die der Nutzer seiner Google Fotos-Galerie hinzugefügt hat, werden auch im Aufruf listing album zurückgegeben. Führen Sie den folgenden Aufruf aus, um geteilte Alben über die Library API aufzulisten:

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
}

Eine Liste mit Alben ist in sharedAlbums enthalten. Weitere Informationen finden Sie unter Alben auflisten. Die Antwort enthält auch ein nextPageToken. Weitere Informationen finden Sie unter Seitenumbruch.

Alben, die von Ihrer App erstellt und geteilt wurden, enthalten das zusätzliche Attribut shareInfo. Weitere Informationen finden Sie unter Medien freigeben.

Von der App erstellte Alben werden aufgelistet

Sie können Alben auflisten, die von Ihrer App erstellt wurden, wobei excludeNonAppCreatedData in den folgenden Aufrufen auf true gesetzt ist:

• albums.list
• sharedAlbums.list

REST

Hier ist eine GET-Anfrage, mit der alle Alben aus der Google Fotos-Galerie des Nutzers aufgelistet werden, die nur von deiner App erstellt wurden:

GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

Hier ist eine GET-Anfrage, mit der alle geteilten Alben aus der Google Fotos-Galerie des Nutzers aufgelistet werden, die nur von deiner App erstellt wurden:

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

Bei Methoden, die eine große Anzahl von Ergebnissen zurückgeben (z. B. Listenmethoden), kann die Antwort paginiert werden, um die Leistung zu verbessern. Die maximale Anzahl von Ergebnissen auf jeder Seite wird durch den Parameter pageSize angegeben.

Für Aufrufe 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ührungsrate findet. Die maximale Seitengröße für die Suche nach Medienelementen und Listenanfragen beträgt 100 Elemente.

Die standardmäßige und empfohlene Seitengröße beim Auflisten von Alben beträgt 20 Alben bei maximal 50 Alben.

Wenn die Anzahl der verfügbaren Ergebnisse die Seitengröße überschreitet, enthält die Antwort ein nextPageToken, das Ihre Anwendung darauf hinweist, dass weitere Ergebnisse vom Server abgerufen werden müssen.

Hinweis: Der Parameter pageSize ist ein Maximum. Es können weniger Ergebnisse zurückgegeben werden als angefordert.

Beispiel

Sie müssen nextPageToken an nachfolgende Anfragen im Parameter pageToken anhängen, wie im folgenden Beispiel gezeigt. Geben Sie pageToken zusammen mit anderen Parametern an, die für den Vorgang erforderlich sind, entweder im Text der Anfrage oder als Abfrageparameter.

Anfrage 1

{
  "pageSize": "5",
  "filters": { … }
}

Antwort Nr. 1

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

Anfrage 2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

Antwort Nr. 2

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

Fahren Sie mit diesem Muster fort, bis keine nextPageToken-Objekte mehr vorhanden sind.

nextPageToken gilt nur für dieselbe Anfrage. Wenn Parameter geändert werden, sollte ein zuvor verwendeter nextPageToken nicht in derselben Anfrage verwendet werden.

Hinweis: Das Vorhandensein von nextPageToken ist der einzige Indikator dafür, ob weitere Ergebnisse vom Server abgerufen werden müssen. Die Anzahl der Ergebnisse wird nicht berücksichtigt, um zu bestimmen, ob nextPageToken verwendet werden sollte. Bei einer Anfrage werden möglicherweise weniger Ergebnisse zurückgegeben als für die Seitengröße angefordert. Wenn nextPageToken vorhanden ist, können Sie nach der ursprünglichen Anfrage eine Anfrage für weitere Ergebnisse senden.