Nachdem Sie die Inhalte einer Fotomediathek oder eines Albums aufgelistet haben, anstatt die zurückgegebenen Medienelemente zu speichern, sollte Ihre App 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. Mit der Medienelement-ID wird ein Medienelement, z. B. ein Foto oder ein Video, in der Mediathek eines Nutzers eindeutig identifiziert.
Ihre Anwendung sollte die Fotos oder Videos eines Nutzers nicht über längere Zeit im Cache speichern. Sie können die Medienelement-ID aber je nach Anwendungsfall so lange wie nötig im Cache speichern oder im Cache speichern. Beachten Sie auch, dass der Zugriff auf Nutzerdaten den Datenschutzverpflichtungen unterliegt.
Erforderliche Autorisierungsbereiche
Für den Zugriff auf Medienelemente muss Ihre App mindestens einen der folgenden Autorisierungsbereiche anfordern. Der Zugriff auf die in der Antwort zurückgegebenen Medienelemente hängt von den angeforderten Bereichen ab.
photoslibrary.readonlyermöglicht den Zugriff auf alle Medienelemente in der Mediathek des Nutzersphotoslibrary.readonly.appcreateddatagestattet nur den Zugriff auf Medienelemente, die von der App erstellt wurden.
Medienelemente
Ein mediaItem ist eine Darstellung von Medien wie Fotos oder Videos, die in die Google Fotos-Galerie 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 zur Identifizierung des Objekts. |
description |
Beschreibung des Medienelements, wie sie in Google Fotos angezeigt wird. |
baseUrl |
Wird für den Zugriff auf die Rohbyte 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 Bibliothek. Falls die URL über eine Albumsuche abgerufen wurde, verweist sie auf das Element im Album. |
mimeType |
Der Typ des Medienelements, mit dem der Medientyp einfach identifiziert werden kann (z. B. image/jpg). |
filename |
Dateiname des Medienelements, das dem Nutzer in der Google Fotos App angezeigt wird (im Infobereich des Objekts). |
mediaMetadata |
Variiert je nach zugrunde liegender Art des Mediums, z. B. photo oder video.
Zur Reduzierung der Nutzlast können Feldmasken verwendet werden.
|
contributorInfo |
Dieses Feld wird nur gefüllt, wenn sich das Medienelement in einem geteilten Album befindet, das von dieser App erstellt wurde, und der Nutzer den Bereich Enthält Informationen zum Beitragenden, der dieses Medienelement hinzugefügt hat. Weitere Informationen finden Sie unter Medien freigeben. |
Medienelement abrufen
Um ein Medienelement abzurufen, rufen Sie mediaItems.get mit der mediaItemId auf. 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. ContributorInfo enthält Metadaten für Elemente, die Teil eines geteilten Albums sind. Dieses Feld ist nur enthalten, wenn Sie die Inhalte eines geteilten Albums auflisten, in dem der Nutzer den Autorisierungsbereich photoslibrary.sharing gewährt hat.
Wenn das Medienelement ein Video ist, muss die Videodatei zuerst verarbeitet werden. mediaItem enthält ein status-Feld in mediaMetadata, das den Verarbeitungsstatus der Videodatei beschreibt. Eine neu hochgeladene Datei gibt zuerst das videoProcessingStatus mit dem Wert PROCESSING zurück, bevor es READY verwendet wird. Das 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 auf ein Medienelement für ein Foto sieht so aus: Die Eigenschaft „foto“ 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 auf ein Video-Mediaelement sieht so aus: Die Property „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"
}
}
Java
Die Eigenschaft „foto“ enthält Metadaten für Fotoelemente.
try {
// Get a media item using its ID
String mediaItemId = "...";
MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
// Get some properties from the retrieved media item
String id = item.getId();
String description = item.getDescription();
String baseUrl = item.getBaseUrl();
String productUrl = item.getProductUrl();
// ...
if (item.hasMediaMetadata()) {
// The media item contains additional metadata, such as the height and width
MediaMetadata metadata = item.getMediaMetadata();
long height = metadata.getHeight();
long width = metadata.getWidth();
Timestamp creationTime = metadata.getCreationTime();
// ...
if (metadata.hasPhoto()) {
// This media item is a photo and has additional photo metadata
Photo photoMetadata = metadata.getPhoto();
String cameraMake = photoMetadata.getCameraMake();
String cameraModel = photoMetadata.getCameraModel();
float aperture = photoMetadata.getApertureFNumber();
int isoEquivalent = photoMetadata.getIsoEquivalent();
// ...
}
}
if (item.hasContributorInfo()) {
// A user has contributed this media item to a shared album
ContributorInfo contributorInfo = item.getContributorInfo();
String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
String displayName = contributorInfo.getDisplayName();
}
} catch (ApiException e) {
// Handle error
}
Die Eigenschaft „video“ enthält Metadaten für Videoelemente.
try {
// Get a media item using its ID
String mediaItemId = "...";
MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
// Get some properties from the retrieved media item
String id = item.getId();
String description = item.getDescription();
String baseUrl = item.getBaseUrl();
String productUrl = item.getProductUrl();
// ...
if (item.hasMediaMetadata()) {
// The media item contains additional metadata, such as the height and width
MediaMetadata metadata = item.getMediaMetadata();
long height = metadata.getHeight();
long width = metadata.getWidth();
Timestamp creationTime = metadata.getCreationTime();
// ...
if (metadata.hasVideo()) {
// This media item is a video and has additional video metadata
Video videoMetadata = metadata.getVideo();
VideoProcessingStatus status = videoMetadata.getStatus();
if (status.equals(VideoProcessingStatus.READY)) {
// This video media item has been processed
String cameraMake = videoMetadata.getCameraMake();
String cameraModel = videoMetadata.getCameraModel();
double fps = videoMetadata.getFps();
// ...
}
}
}
if (item.hasContributorInfo()) {
// A user has contributed this media item to a shared album
ContributorInfo contributorInfo = item.getContributorInfo();
String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
String displayName = contributorInfo.getDisplayName();
}
} catch (ApiException e) {
// Handle error
}
PHP
Die Eigenschaft „foto“ enthält Metadaten für Fotoelemente.
try {
// Get a media item using its ID
$mediaItemId = "...";
$item = $photosLibraryClient->getMediaItem($mediaItemId);
// Get some properties from the retrieved media item
$id = $item->getId();
$description = $item->getDescription();
$baseUrl = $item->getBaseUrl();
$productUrl = $item->getProductUrl();
// ...
$metadata = $item->getMediaMetadata();
if (!is_null($metadata)) {
// The media item contains additional metadata, such as the height and width
$height = $metadata->getHeight();
$width = $metadata->getWidth();
$creationTime = $metadata->getCreationTime();
// ...
$photoMetadata = $metadata->getPhoto();
if (!is_null($photoMetadata)) {
// This media item is a photo and has additional photo metadata
$cameraMake = $photoMetadata->getCameraMake();
$cameraModel = $photoMetadata->getCameraModel();
$aperture = $photoMetadata->getApertureFNumber();
$isoEquivalent = $photoMetadata->getIsoEquivalent();
// ...
}
}
$contributorInfo = $item->getContributorInfo();
if (!is_null($contributorInfo)) {
// A user has contributed this media item to a shared album
$profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
$displayName = $contributorInfo->getDisplayName();
}
} catch (\Google\ApiCore\ApiException $e) {
// Handle error
}
Die Eigenschaft „video“ enthält Metadaten für Videoelemente.
try {
// Get a media item using its ID
$mediaItemId = "...";
$item = $photosLibraryClient->getMediaItem($mediaItemId);
// Get some properties from the retrieved media item
$id = $item->getId();
$description = $item->getDescription();
$baseUrl = $item->getBaseUrl();
$productUrl = $item->getProductUrl();
// ...
$metadata = $item->getMediaMetadata();
if (!is_null($metadata)) {
// The media item contains additional metadata, such as the height and width
$height = $metadata->getHeight();
$width = $metadata->getWidth();
$creationTime = $metadata->getCreationTime();
// ...
$videoMetadata = $metadata->getVideo();
if (!is_null($videoMetadata)) {
// This media item is a video and has additional video metadata
if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) {
// This video media item has been processed
$cameraMake = $videoMetadata->getCameraMake();
$cameraModel = $videoMetadata->getCameraModel();
$fps = $videoMetadata->getFps();
// ...
}
}
}
$contributorInfo = $item->getContributorInfo();
if (!is_null($contributorInfo)) {
// A user has contributed this media item to a shared album
$profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
$displayName = $contributorInfo->getDisplayName();
}
} catch (\Google\ApiCore\ApiException $e) {
// Handle error
}
Mehrere Medienelemente abrufen
Um mehrere Medienelemente anhand ihrer IDs abzurufen, rufen Sie mediaItems.batchGet mithilfe der mediaItemId-Elemente auf.
Die Anfrage gibt eine Liste von MediaItemResults in der Reihenfolge der in der Anfrage angegebenen Medienelement-IDs zurück. Jedes Ergebnis enthält einen MediaItem oder einen Status, falls ein Fehler aufgetreten ist.
Sie können in einem Aufruf maximal 50 Medienelemente anfordern. Die Liste der Medienelemente darf keine doppelten Kennungen enthalten und darf nicht leer sein.
REST
Die folgende GET-Anfrage zeigt den erfolgreichen und nicht erfolgreichen Zugriff von Medienelementen. Geben Sie jede Medienelement-ID als neuen mediaItemIds-Abfrageparameter als Teil 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."
}
}
]
}
Java
try {
// List of media item IDs to retrieve
List<String> mediaItemIds = Arrays
.asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID");
// Get a list of media items using their IDs
BatchGetMediaItemsResponse response = photosLibraryClient
.batchGetMediaItems(mediaItemIds);
// Loop over each result
for (MediaItemResult result : response.getMediaItemResultsList()) {
// Each MediaItemresult contains a status and a media item
if (result.hasMediaItem()) {
// The media item was successfully retrieved, get some properties
MediaItem item = result.getMediaItem();
String id = item.getId();
// ...
} else {
// If the media item is not set, an error occurred and the item could not be loaded
// Check the status and handle the error
Status status = result.getStatus();
// ...
}
}
} catch (ApiException e) {
// Handle error
}
PHP
try {
// List of media item IDs to retrieve
$mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"];
// Get a list of media items using their IDs
$response = $photosLibraryClient->batchGetMediaItems($mediaItemIds);
// Loop over each result
foreach ($response->getMediaItemResults() as $itemResult) {
// Each MediaItemresult contains a status and a media item
$mediaItem = $itemResult->getMediaItem();
if(!is_null($mediaItem)){
// The media item was successfully retrieved, get some properties
$id = $mediaItem->getId();
// ...
} else {
// If the media item is null, an error occurred and the item could not be loaded
}
}
} catch (\Google\ApiCore\ApiException $e) {
// Handle error
}
Basis-URLs
Mit Basis-URLs in der Google Photos Library API können Sie auf die Byte der Medienelemente zugreifen. Mithilfe der verschiedenen Basis-URLs kann Ihre App die Medienelemente entweder herunterladen oder in Ihrer App anzeigen. Basis-URLs sind Strings, die in der Antwort enthalten sind, wenn Sie Alben auflisten oder auf Medienelemente zugreifen. Sie sind 60 Minuten lang gültig und erfordern zusätzliche Parameter, da sie nicht unverändert verwendet werden können.
Die verschiedenen Basis-URLs sind:
baseUrl: Hiermit kannst du direkt auf das Foto oder die Miniaturansicht eines Videos zugreifen oder Videobyte herunterladen.coverPhotoBaseUrl: Hiermit wird direkt auf das Titelbild des Albums zugegriffen.profilePictureBaseUrl: Hiermit kann direkt auf das Profilbild des Inhabers vonmediaItemzugegriffen werden.
Image-Basis-URLs
Im Folgenden finden Sie eine Liste der Optionen, die Sie mit den Basis-URLs von Bildern verwenden können:
| Parameter | |
|---|---|
w, h |
Beschreibung Die Parameter für Breite ( Wenn Sie auf ein Medienelement wie ein Foto oder eine Miniaturansicht für ein Video zugreifen möchten, müssen Sie die Abmessungen angeben, die in Ihrer Anwendung dargestellt werden sollen. So kann das Bild unter Beibehaltung des Seitenverhältnisses in diese Abmessungen skaliert werden. Verketten Sie dazu die Basis-URL mit den erforderlichen Dimensionen, wie in den Beispielen gezeigt. Beispiele: base-url=wmax-width-hmax-height Im folgenden Beispiel wird ein Medienelement angezeigt, 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 Wenn Sie das Bild auf die von Ihnen angegebene Breite und Höhe zuschneiden möchten, verketten Sie die Basis-URL mit dem optionalen 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 (unter Beibehaltung des Seitenverhältnisses). 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. eine Miniaturansicht: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
Beschreibung Der heruntergeladene Parameter Wenn Sie das Bild mit allen EXIF-Metadaten herunterladen möchten, mit Ausnahme der Standortmetadaten, 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 |
Videobasis-URLs
Im Folgenden finden Sie eine Liste der Optionen, die Sie mit den Videobasis-URLs verwenden können:
| Parameter | |
|---|---|
dv |
Beschreibung Für den Zugriff auf die Bytes eines Videos- Mit dem Parameter dv wird eine transcodierte Version des Originalvideos in hoher Qualität angefordert. Der Parameter ist nicht mit den Parametern w und h kompatibel. Bei Basis-URLs für Videodownloads kann es einige Sekunden dauern, bis Bytes zurückgegeben werden. Bevor Sie diesen Parameter verwenden, prüfen Sie, ob das Feld Beispiele: base-url=dv Im folgenden Beispiel siehst du, wie du die Byte eines Videos herunterladen kannst: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w, h, c und d |
Beschreibung Sie können die Miniaturansicht des Videos über einen der Parameter für die Bild-URL (image base url) aufrufen. Standardmäßig enthalten alle Video-Thumbnails ein Overlay einer Wiedergabeschaltfläche. Verwenden Sie den Parameter -no, um dieses Overlay zu entfernen. Beispiele: Beispiele finden Sie in der Tabelle mit den Basis-URLs von Bildern. |
no |
Beschreibung Der Parameter Wenn du das Thumbnail 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 Basis-URL-Parameter für Bilder verwendet werden. Beispiele: base-url=wmax-width-hmax-height-no Im folgenden Beispiel wird ein Video-Thumbnail angezeigt, das genau 1280 Pixel breit und 720 Pixel hoch ist und kein Overlay für die 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 von Basis-URLs für Bilder oder Basis-URLs für Anfragen vom Typ baseUrl mit Bewegtbild verwenden.
| Parameter | |
|---|---|
dv |
Beschreibung Wenn Sie das Videoelement eines Medienelements mit einem Foto mit Bewegtbild abrufen möchten, verwenden Sie den Parameter |
w, h, c und d |
Beschreibung Wenn Sie das Fotoelement eines Medienelements mit Bewegtbild abrufen möchten, verwenden Sie das Format für Bildbasis-URLs. |