Mediathek-Inhalte, Alben und Medienelemente auflisten

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