Medieninhalte auflisten und abrufen

Sobald ein Nutzer sein Bildschirmschonergerät konfiguriert und Medienquellen in Google Fotos ausgewählt hat, kann Ihre App diese Medienelemente auflisten und abrufen, um sie anzuzeigen.

Vorbereitung

Umfrage für mediaSourcesSet

Bevor Sie Medienelemente für ein Gerät auflisten können, muss der Nutzer die Fotos, die er mit Ihrer App teilen möchte, in der Google Fotos App ausgewählt haben. Ihre App muss das Gerät abfragen, um festzustellen, wann diese Auswahl getroffen wurde.

Rufen Sie die Methode devices.get für die jeweilige deviceId regelmäßig auf. Behalte das Feld mediaSourcesSet in der AmbientDevice-Antwort im Auge. Zuerst ist das false. Sobald der Nutzer die Medienquellen ausgewählt hat, ändert sich dieses Feld in true.

Die AmbientDevice-Antwort enthält ein pollingConfig mit einem pollInterval, das Sie als Anhaltspunkt für die Abfragehäufigkeit verwenden sollten.

Medienelemente auflisten

Sobald mediaSourcesSet für ein Gerät true ist, kannst du mit dem Abrufen der vom Nutzer ausgewählten Medienelemente beginnen.

  1. mediaItems.list-Endpunkt verwenden:Senden Sie eine GET-Anfrage an https://photosambient.googleapis.com/v1/mediaItems und geben Sie deviceId im Pfad an.

  2. Paginierung (falls erforderlich) verarbeiten: Die Antwort kann auf mehrere Seiten verteilt sein. Verwenden Sie den Parameter pageSize, um die maximale Anzahl der Elemente anzugeben, die zurückgegeben werden sollen, und das pageToken aus einer vorherigen Antwort, um nachfolgende Seiten mit Ergebnissen abzurufen.

  3. Medienelemente verarbeiten:Die Antwort enthält ein Array von AmbientMediaItem-Objekten, die jeweils ein ausgewähltes Medienelement darstellen. Diese Objekte enthalten wichtige Details wie:

    • id: Die eindeutige Kennung für das Medienelement.
    • creationTime: Der Zeitstempel, der angibt, wann das Medienelement erstellt wurde.
    • mediaFile: Ein Objekt mit Details zum Zugriff auf den eigentlichen Inhalt.

Das Feld mediaFile enthält die baseUrl. Anhand dieser baseUrl kannst du URLs erstellen, um auf die Inhalte des Medienelements in verschiedenen Auflösungen oder Formaten zuzugreifen.

Basis-URLs

Basis-URLs in den Google Fotos APIs bieten Zugriff auf die Rohbytes von Medienelementen, sodass Ihre App sie herunterladen oder anzeigen kann. Diese URLs sind in den Antworten enthalten, wenn Alben aufgelistet (Mediathek API) oder auf Medienelemente zugegriffen wird (sowohl Mediathek- als auch Auswahl-API). Denken Sie daran, dass Basis-URLs zusätzliche Parameter benötigen, damit sie richtig funktionieren.

Für die Picker API:

Alle PickedMediaItem.mediaFile-Objekte enthalten einen baseUrl.

Basis-URLs bleiben 60 Minuten lang aktiv, können aber früher ablaufen, wenn der Nutzer die Berechtigungen Ihrer App über die Einstellungen seines Google-Kontos widerruft.

Library API:

Basis-URLs bleiben 60 Minuten lang aktiv.

Die verschiedenen Basis-URLs sind:

  • baseUrl: Direkt auf ein Foto oder die Miniaturansicht eines Videos zugreifen oder Videobytes herunterladen.
  • coverPhotoBaseUrl: Direkt auf das Cover des Albums zugreifen.
  • profilePictureBaseUrl: Direkt auf das Profilbild des Inhabers einer mediaItem zugreifen.

Basis-URLs für Bilder

Hier sind die Optionen, die Sie mit den Basis-URLs von Bildern verwenden können:

Parameter
w, h

Beschreibung

Die Parameter „width“, w und „height“, h

Wenn Sie auf ein Bildmedium wie ein Foto oder ein Thumbnail für ein Video zugreifen möchten, müssen Sie die Abmessungen angeben, die in Ihrer Anwendung angezeigt werden sollen. So kann das Bild auf diese Abmessungen skaliert werden, wobei das Seitenverhältnis beibehalten wird. Dazu müssen Sie die Basis-URL wie in den Beispielen gezeigt mit den erforderlichen Dimensionen zusammenführen.

Beispiele:

base-url=wmax-width-hmax-height

Hier ist ein Beispiel für die Anzeige eines Medienelements, das nicht breiter als 2.048 Pixel und nicht höher als 1.024 Pixel ist:

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

Beschreibung

Der Parameter „Zuschneiden“ (c).

Wenn Sie das Bild auf die von Ihnen angegebenen Abmessungen zuschneiden möchten, verknüpfen Sie die Basis-URL mit dem optionalen Parameter -c sowie den obligatorischen Parametern w und h.

Die Größe (in Pixeln) muss im Bereich [1, 16383] liegen. Wenn die Breite oder Höhe des Bildes die angeforderte Größe überschreitet, wird das Bild verkleinert und zugeschnitten, wobei das Seitenverhältnis beibehalten wird.

Beispiele:

base-url=wmax-width-hmax-height-c

In diesem Beispiel zeigt die Anwendung ein Medienelement an, das genau 256 Pixel breit und 256 Pixel hoch ist, z. B. ein Thumbnail:

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

Beschreibung

Der Parameter „Herunterladen“, d.

Wenn Sie das Bild mit allen Exif-Metadaten außer den Standortmetadaten herunterladen möchten, verknüpfen Sie die Basis-URL mit dem Parameter d.

Beispiele:

base-url=d

In diesem Beispiel lädt die Anwendung ein Bild mit allen Metadaten außer den Standortmetadaten herunter:

https://lh3.googleusercontent.com/p/Az....XabC=d

Basis-URLs von Videos

Hier findest du eine Liste der Optionen, die du mit den Basis-URLs von Videos verwenden kannst:

Parameter
dv

Beschreibung

Wenn du auf die Bytes eines Videos zugreifen möchtest, mediaItem, konkateniere den Parameter baseUrl mit dem Parameter dv für das heruntergeladene Video.

Mit dem Parameter dv wird eine hochqualitative, transcodierte Version des Originalvideos angefordert. Der Parameter ist nicht mit den Parametern w und h kompatibel.

Es kann einige Sekunden dauern, bis über Basis-URLs für Videodownloads Bytes zurückgegeben werden.

Bevor du diesen Parameter verwendest, musst du prüfen, ob das Feld mediaMetadata.status der Medienelemente READY ist. Andernfalls, wenn die Verarbeitung des Medienelements noch nicht abgeschlossen ist, erhältst du möglicherweise eine Fehlermeldung.

Beispiele:

base-url=dv

Im folgenden Beispiel wird gezeigt, wie du die Bytes eines Videos herunterlädst:

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h, c und d

Beschreibung

Verwende einen der Parameter für die Basis-URL des Bilds, um auf das Thumbnail des Videos zuzugreifen.

Standardmäßig enthalten alle Video-Thumbnails ein Overlay mit einer Wiedergabeschaltfläche. Mit dem Parameter -no können Sie dieses Overlay entfernen.

Beispiele:

Beispiele finden Sie in der Tabelle mit Basis-URLs für Bilder.
no

Beschreibung

Entfernen des Miniaturansicht-Overlays, Parameter no

Wenn du das Thumbnail eines Videos ohne das Overlay einer Wiedergabeschaltfläche abrufen möchtest, verbinde die Basis-URL mit dem Parameter no.

Der Parameter no muss mit mindestens einem der Parameter für die Basis-URL des Bilds verwendet werden.

Beispiele:

base-url=wmax-width-hmax-height-no

Im folgenden Beispiel ist ein Video-Thumbnail zu sehen, das genau 1.280 px breit und 720 px hoch ist und kein Overlay mit einer Wiedergabeschaltfläche enthält:

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

Basis-URLs für Fotos mit Bewegtbild

Fotos mit Bewegtbild enthalten sowohl Foto- als auch Videoelemente. Sie können Parameter aus Bild-Basis-URLs oder Video-Basis-URLs für Anfragen für baseUrl-Aufnahmen mit bewegten Bildern verwenden.

Parameter
dv

Beschreibung

Wenn du das Videoelement eines Medienelements mit einer Motion-Foto-Funktion abrufen möchtest, verwende den Parameter dv, wie du es auch beim Herunterladen von Video-Basis-URLs tun würdest.
w, h, c und d

Beschreibung

Verwende das Format für Bild-Basis-URLs, um das Fotoelement eines Medienelements mit einer Motion-Fotodatei abzurufen.

Nächste Schritte

  • Beispielanwendung:Unsere Beispielanwendung enthält ein Beispiel zum Auflisten und Abrufen von Medienelementen. Weitere Informationen finden Sie in den Funktionen checkMediaSourcesSet und fetch_media_item_list.
  • Referenzdokumentation:In den umfassenden Referenzdokumenten zu Medienelementen finden Sie detaillierte Informationen zu allen verfügbaren Methoden, Anfrage- und Antwortparametern sowie Fehlercodes.