Auf von der App erstellte Medienelemente zugreifen

Nachdem Sie Aufrufe gesendet haben, um den Inhalt einer Fotogalerie oder eines Albums aufzulisten, sollte Ihre Anwendung anstelle der zurückgegebenen Medienelemente die IDs der Medienelemente speichern. Das liegt daran, dass sich der Inhalt der Medienelemente ändern kann und die in der Antwort enthaltenen URLs nach einer bestimmten Zeit ablaufen. Die Medienelement-ID identifiziert ein Medienelement wie ein Foto oder Video in der Mediathek eines Nutzers eindeutig.

Erforderliche Autorisierungsbereiche

Für den Zugriff auf von Apps erstellte Medienelemente ist der Umfang photoslibrary.readonly.appcreateddata erforderlich. Weitere Informationen zu Bereichen finden Sie unter Autorisierungsbereiche.

Medienelemente

Ein mediaItem ist eine Darstellung von Medien wie Fotos oder Videos, die in die Google Fotos-Mediathek hochgeladen wurden. Es ist ein Objekt der obersten Ebene und seine Eigenschaften können je nach zugrunde liegendem Medientyp variieren.

In der folgenden Tabelle sind die mediaItem-Attribute aufgeführt:

Attribute
id Eine dauerhafte, stabile ID, die zum Identifizieren des Objekts verwendet wird.
description Beschreibung des Medienelements in Google Fotos
baseUrl Wird für den Zugriff auf die Rohbytes verwendet. Weitere Informationen finden Sie unter Basis-URLs.
productUrl

Ein Link zum Bild in Google Fotos. Dieser Link kann nicht vom Entwickler, sondern nur vom Nutzer geöffnet werden. URLs verweisen auf ein Medienelement in der Mediathek. Wenn die URL aus einer Albumsuche abgerufen wurde, verweist sie auf das Element im Album.

mimeType Der Typ des Medienelements, der die Art der Medien leicht identifiziert (z. B. image/jpg).
filename Der Dateiname des Medienelements, der dem Nutzer in der Google Fotos App im Infobereich des Elements angezeigt wird.
mediaMetadata Variiert je nach zugrunde liegendem Medientyp, z. B. photo oder video. Feldmasken können verwendet werden, um die Nutzlast zu reduzieren.

Medienelement abrufen

Rufe mediaItems.get mit der mediaItemId auf, um ein Medienelement abzurufen. Die Anfrage gibt ein einzelnes Medienelement zurück.

Die mediaItem enthält Eigenschaften wie die ID, die Beschreibung und die URL. Die zusätzlichen Informationen in photo oder video basieren auf den Metadaten in der Datei. Möglicherweise sind nicht alle Properties vorhanden.

Wenn es sich um ein Video handelt, muss die Videodatei zuerst verarbeitet werden. Die mediaItem enthält das Feld status in mediaMetadata, das den Verarbeitungsstatus der Videodatei beschreibt. Bei einer neu hochgeladenen Datei wird zuerst videoProcessingStatus mit dem Wert PROCESSING zurückgegeben, bevor sie für die Verwendung READY ist. Die baseUrl eines Videomedienelements ist erst verfügbar, wenn das Video verarbeitet wurde.

REST

Hier ist eine GET-Anfrage:

GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

Die Antwort für ein Foto-Medienelement sieht so aus: Das Attribut „photo“ enthält Metadaten für Fotoelemente.

{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "photo": {
       "cameraMake": "make-of-the-camera",
       "cameraModel": "model-of-the-camera",
       "focalLength": "focal-length-of-the-camera-lens",
       "apertureFNumber": "aperture-f-number-of-the-camera-lens",
       "isoEquivalent": "iso-of-the-camera",
       "exposureTime": "exposure-time-of-the-camera-aperture"
    }
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}

Die Antwort für ein Videomedienelement sieht so aus: Das Attribut „video“ enthält Metadaten für Videoelemente.

{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "video": {
     "cameraMake": "make-of-the-camera",
     "cameraModel": "model-of-the-camera",
     "fps": "frame-rate-of-the-video",
     "status": "READY"
    },
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}

Mehrere Medienelemente abrufen

Wenn du mehrere Medienelemente anhand ihrer IDs abrufen möchtest, rufe mediaItems.batchGet mit den mediaItemIds auf.

Die Anfrage gibt eine Liste von MediaItemResults zurück, die in der Reihenfolge der in der Anfrage angegebenen Medienelement-IDs sortiert ist. Jedes Ergebnis enthält MediaItem oder Status, wenn ein Fehler aufgetreten ist.

Du kannst maximal 50 Medienelemente in einem Aufruf anfordern. Die Liste der Medienelemente darf keine doppelten IDs enthalten und darf nicht leer sein.

REST

Hier ist eine GET-Anfrage, die den erfolgreichen und fehlgeschlagenen Zugriff auf Medienelemente zeigt. Gib die ID jedes Medienelements als neuen mediaItemIds-Abfrageparameter in der Anfrage an:

GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

Die GET-Anfrage gibt die folgende Antwort zurück:

{
  "mediaItemResults": [
    {
      "mediaItem": {
        "id": "media-item-id",
        ...
      }
    },
    {
      "mediaItem": {
        "id": "another-media-item-id",
        ...
      }
    },
    {
      "status": {
        "code": 3,
        "message": "Invalid media item ID."
      }
    }
  ]
}

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 finden Sie eine Liste der 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 Sie in Ihrer Anwendung anzeigen möchten. 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 maximal 2.048 Pixel breit und 1.024 Pixel hoch ist:

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

Beschreibung

Der Parameter „Zuschneiden“ (c).

Wenn Sie das Bild auf die von Ihnen angegebene Breite und Höhe 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 den Download des Videos.

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, prüfe, 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 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 Bildes 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 Bewegungsaufnahme abzurufen.