Nach dem Aufrufen der Funktion Inhalte einer Fotogalerie oder eines Albums auflisten sollten die IDs der Medienelemente in Ihrer Anwendung gespeichert werden, anstatt die zurückgegebenen Medienelemente zu 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 Bereich 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.
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 Unterkünfte vorhanden.
Wenn es sich um ein Video handelt, muss die Videodatei zuerst verarbeitet werden. mediaItem enthält ein status-Feld in mediaMetadata, das den Verarbeitungsstatus der Videodatei beschreibt. Bei einer neu hochgeladenen Datei wird zuerst die 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.
In der Anfrage wird eine Liste von MediaItemResults in der Reihenfolge der in der Anfrage angegebenen IDs der Medienelemente zurückgegeben. 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 sehen Sie eine GET-Anfrage, die den erfolgreichen und fehlgeschlagenen Zugriff auf Medienelemente anzeigt. 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 Antworten beim Auflisten von Alben (Library API) oder beim Zugriff auf Medienelemente (sowohl Library API als auch Picker API) enthalten. 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.
Für die 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: Hiermit können Sie direkt auf das Titelbild des Albums zugreifen.profilePictureBaseUrl: Direkt auf das Profilbild des Inhabers einermediaItemzugreifen.
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“, Wenn du auf ein Bildmedienelement wie ein Foto oder eine Miniaturansicht eines Videos zugreifen möchtest, musst du die Abmessungen angeben, die in deiner Anwendung angezeigt werden sollen. So kann das Bild unter Beibehaltung des Seitenverhältnisses auf diese Abmessungen skaliert werden. Dazu müssen Sie die Basis-URL mit den erforderlichen Dimensionen zusammenführen, wie in den Beispielen gezeigt. 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 „crop“, Wenn Sie das Bild auf die von Ihnen angegebenen Abmessungen zuschneiden möchten, verknüpfen Sie die Basis-URL mit dem optionalen Parameter 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“, Wenn Sie das Bild herunterladen möchten, das alle EXIF-Metadaten mit Ausnahme der Standortmetadaten behält, verketten Sie die Basis-URL mit dem Parameter 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
Im Folgenden finden Sie eine Liste der Optionen, die Sie mit den Videobasis-URLs verwenden können:
| Parameter | |
|---|---|
dv |
Beschreibung Wenn du auf die Bytes eines Videos zugreifen möchtest, 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 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-Image-URLs. |
no |
Beschreibung Entfernen des Thumbnail-Overlays, Parameter Wenn du die Miniaturansicht eines Videos ohne das Overlay einer Wiedergabeschaltfläche abrufen möchtest, verkettee 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 wird eine Video-Miniaturansicht angezeigt, die genau 1.280 Pixel breit und 720 Pixel hoch ist und kein Wiedergabeschaltflächen-Overlay enthält: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
Basis-URLs von 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-Fotodatei abrufen möchtest, verwende den Parameter |
w, h, c und
d |
Beschreibung Verwende das Format für Bild-Basis-URLs, um das Fotoelement eines Medienelements mit einer Bewegungsaufnahme abzurufen. |