Auf Medienelemente zugreifen

Nachdem Sie Aufrufe zum Auflisten des Inhalts einer Fotogalerie oder eines Albums ausgeführt haben, sollte Ihre Anwendung nicht die zurückgegebenen Medienelemente speichern, sondern die IDs der Medienelemente. Das liegt daran, dass der Inhalt der Medienelemente ändern. Nach einer gewissen Zeit laufen die in der Antwort enthaltenen URLs ab. Die Medienelement-ID identifiziert ein Medienelement wie ein Foto oder Video in der Mediathek eines Nutzers eindeutig.

Beachten Sie, dass das Foto oder Video eines Nutzers nicht lange im Cache gespeichert werden sollte. zu verwenden. Je nach Anwendungsfall sollten Sie jedoch oder die Medienelement-ID im Cache speichern, Long as erforderlich. Beachten Sie auch, dass der Zugriff auf Nutzer unterliegen dem Datenschutz Verpflichtungen.

Erforderliche Autorisierungsbereiche

Für den Zugriff auf Medienelemente muss Ihre App mindestens eine der folgenden Anfragen anfordern Autorisierungsbereiche. Der Zugriff auf die in der Antwort zurückgegebenen Medienelemente hängt von den Bereichen ab, die Sie angefordert haben.

  • photoslibrary.readonly gewährt Zugriff auf alle Medienelemente in den des Nutzers Bibliothek
  • photoslibrary.readonly.appcreateddata gewährt nur Zugriff auf Medienelemente, die wurden von der App erstellt

Medienelemente

A mediaItem ist eine Darstellung von Medien, z. B. einem Foto oder Video, das auf Google Fotos-Galerie ansehen. Es ist ein Objekt der obersten Ebene und seine Eigenschaften können unterscheiden sich je nach dem zugrunde liegenden Medientyp.

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

Attribute
id Eine permanente, stabile ID zur Identifizierung des Objekts.
description Innenansicht der Beschreibung des Medienelements Google Fotos
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 Mediathek. Wenn die URL aus einer Albumsuche abgerufen wurde, verweist auf das Element im Album.

mimeType Der Typ des Medienelements, mit dem sich der Medientyp leicht identifizieren lässt (z. B. image/jpg).
filename Der Dateiname des Medienelements, das dem Nutzer in Google Fotos angezeigt wird App (im Infobereich des Artikels).
mediaMetadata Variiert je nach zugrunde liegendem Medientyp, z. B. photo oder video. Zur Reduzierung der Nutzlast können Feldmasken verwendet werden.
contributorInfo

Dieses Feld wird nur ausgefüllt, wenn sich das Medienelement in einem geteilten Album befindet, das von dieser App erstellt wurde, und der Nutzer den Zugriffsumfang photoslibrary.sharing gewährt hat.

Enthält Informationen zum Mitwirkenden, der dieses Medienelement hinzugefügt hat. Weitere Informationen finden Sie unter Medien freigeben.

Medienelement abrufen

Rufen Sie zum Abrufen eines Medienelements mediaItems.get mithilfe der Methode mediaItemId Die Anfrage gibt ein einzelnes Medienelement zurück.

mediaItem enthält Attribute 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. ContributorInfo enthält Metadaten für Elemente, die Teil eines geteilten Albums sind. Dieses Feld ist nur enthalten, wenn Auflistung der Inhalte einer geteiltes Album, in dem der Nutzer photoslibrary.sharing gewährt hat Autorisierungsbereich.

Wenn es sich um ein Video handelt, muss die Videodatei zuerst verarbeitet werden. Die mediaItem enthält ein status-Feld innerhalb von mediaMetadata, das das Verarbeitungsstatus der Videodatei. Eine neu hochgeladene Datei gibt den Fehlerwert videoProcessingStatus mit dem Wert PROCESSING, gefolgt von READY. 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 auf ein Fotomedienelement sieht so aus. Das 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 Videomedienelement sieht so aus. Das Videoelement 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

Das Attribut „photo“ 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 Videoeigenschaft 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

Das Attribut „photo“ 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 Videoeigenschaft 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

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

Die Anfrage gibt eine Liste MediaItemResults in der Reihenfolge der im Antrag angegebenen Mediakosten. 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 von Medienelemente. Geben Sie jede Medienelement-ID als neues Element an. mediaItemIds als Teil der Anfrage:

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

Über Basis-URLs in der Google Fotos-Mediathek-API können Sie auf die Bytes der Medienelemente zugreifen. Mithilfe der verschiedenen Basis-URLs kann Ihre App die Medienelemente entweder herunterladen oder die Medienelemente in Ihrer App anzeigen. Basis-URLs sind Strings, die in der Antwort enthalten, wenn Sie Alben auflisten oder auf Mediendateien zugreifen. Sie sind 60 Minuten lang gültig und erfordern zusätzliche Parameter, da sie nicht direkt verwendet werden können.

Die verschiedenen Basis-URLs sind:

  • baseUrl: Direkt auf ein Foto oder Thumbnail für ein Video zugreifen oder Video-Bytes herunterladen.
  • coverPhotoBaseUrl: Direkt auf das Cover des Albums zugreifen.
  • profilePictureBaseUrl: Direkt auf das Profilbild des Inhabers einer mediaItem zugreifen.

Basis-URLs der Bilder

Im Folgenden finden Sie eine Liste der Optionen, die Sie mit den Basis-URLs des Bildes 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 mit den erforderlichen Dimensionen zusammenführen.

Beispiele:

base-url=wmax-width-hmax-height

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

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

Beschreibung

Der Parameter „crop“, 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 entweder die Breite oder Höhe des Bildes die angeforderte Größe überschreitet, Das Bild wird verkleinert und unter Beibehaltung des Seitenverhältnisses zugeschnitten.

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. Miniaturansicht:

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

Beschreibung

Der Downloadparameter d.

Wenn Sie das Bild unter Beibehaltung aller EXIF-Metadaten herunterladen möchten verketten Sie die Basis-URL mit dem d-Parameter.

Beispiele:

base-url=d

In diesem Beispiel lädt die Anwendung ein Image mit allen Metadaten mit Ausnahme der Standortmetadaten:

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

Basis-URLs des Videos

Im Folgenden finden Sie eine Liste der Optionen, die Sie mit den Videobasis-URLs verwenden können:

Parameter
dv

Beschreibung

Verketten Sie Folgendes, um auf die Bytes eines Videos mediaItem zuzugreifen: die baseUrl mit dem Download-Video dv .

Der Parameter dv fordert eine hohe Qualität an, transcodierten Version des Originalvideos. Der Parameter ist nicht kompatibel mit dem w und h Parameter.

Es kann einige Sekunden dauern, bis Base-URLs für Videodownloads Bytes zurückgeben.

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 die Miniaturansicht 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:

Weitere Informationen finden Sie in der Tabelle mit den Basis-URLs der Bilder. .
no

Beschreibung

Entfernen des Thumbnail-Overlays, Parameter no

Wenn du die Miniaturansicht 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 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 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 baseUrl-Anfragen für animierte Fotos verwenden.

Parameter
dv

Beschreibung

Wenn du das Videoelement eines Medienelements mit einer Motion-Fotodatei 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

Um das Fotoelement eines Medienelements mit Bewegtbild abzurufen, verwenden Sie das Format für Basis-URLs von Bildern.