Medya öğelerine erişme

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Döndürülen medya öğelerini depolamak yerine bir fotoğraf kitaplığının veya albümün içeriğini listelemek için arama yaptıktan sonra uygulamanız, medya öğelerinin kimliklerini saklamalıdır. Bunun nedeni, medya öğelerinin içeriğinin değişebilmesi ve belirli bir süre sonra yanıta dahil edilen URL'lerin süresinin dolmasıdır. Medya öğesi kimliği, kullanıcının kitaplığındaki fotoğraf veya video gibi bir medya öğesini benzersiz şekilde tanımlar.

Uygulamanızın, kullanıcının fotoğrafını veya videosunu uzun süre boyunca önbelleğe almaması gerektiğini hatırlatmak isteriz. Bununla birlikte, kullanım alanınıza bağlı olarak medya öğesi kimliğini gerektiği kadar depolayabilir veya önbelleğe alabilirsiniz. Ayrıca, kullanıcı verilerine erişimin gizlilik yükümlülüklerine tabi olduğunu unutmayın.

Gerekli yetkilendirme kapsamları

Uygulamanız, medya öğelerine erişmek için aşağıdaki yetkilendirme kapsamlarından en az birini istemelidir. Yanıtta döndürülen medya öğelerine erişim, istediğiniz kapsamlara bağlıdır.

  • photoslibrary.readonly, kullanıcının kitaplığındaki tüm medya öğelerine erişim izni verir
  • photoslibrary.readonly.appcreateddata yalnızca uygulamanın oluşturduğu medya öğelerine erişim izni verir

Medya öğeleri

mediaItem Google Fotoğraflar kitaplığına yüklenen fotoğraf veya video gibi medyanın temsilidir. Bu, üst düzey bir nesnedir ve özellikleri, temel alınan medya türüne göre değişebilir.

Aşağıdaki tabloda mediaItem özellikleri listelenmiştir:

Özellikler
id Nesneyi tanımlamak için kullanılan kalıcı ve kararlı bir kimlik.
description Medya öğesinin Google Fotoğraflar'da görünen açıklaması.
baseUrl Ham baytlara erişmek için kullanılır. Daha fazla bilgi için Temel URL'ler başlıklı makaleyi inceleyin.
productUrl

Google Fotoğraflar'daki resmin bağlantısı. Bu bağlantı yalnızca kullanıcı tarafından geliştirici tarafından açılamaz. URL'ler kitaplıktaki bir medya öğesini işaret ediyor. URL, bir albüm aramasından alınmışsa albüm içindeki öğeye işaret eder.

mimeType Medya türünün kolayca tanımlanmasına yardımcı olacak medya öğesinin türü (örneğin: image/jpg).
filename Google Fotoğraflar uygulamasında kullanıcıya gösterilen medya öğesinin dosya adı (öğenin bilgi bölümündedir).
mediaMetadata Medyanın temel türüne (photo veya video gibi) bağlı olarak değişiklik gösterir. Yükü azaltmak için alan maskeleri kullanılabilir.
contributorInfo

Bu alan, yalnızca medya öğesi bu uygulama tarafından oluşturulan paylaşılan bir albümdeyse ve kullanıcı photoslibrary.sharing kapsamını belirlediyse doldurulur.

Bu medya öğesini ekleyen katkıda bulunanla ilgili bilgileri içerir. Daha ayrıntılı bilgi için Medya paylaşma başlıklı makaleye bakın.

Medya öğesi alın

Bir medya öğesini almak için mediaItemId özelliğini kullanarak mediaItems.get çağrısı yapın. İstek tek bir medya öğesi döndürür.

mediaItem; kimlik, açıklama ve URL gibi özellikleri içerir. photo veya video içindeki ek bilgiler, dosya içindeki meta verilere dayalıdır. Bazı özellikler mevcut olmayabilir. ContributorInfo, paylaşılan bir albümün parçası olan öğelerin meta verilerini içerir. Bu alan yalnızca kullanıcının photoslibrary.sharingyetkilendirme kapsamını verdiği durumlarda, paylaşılan bir albümün içeriği listelenirken dahil edilir.

Medya öğesi bir videoysa, önce video dosyası işlenmelidir. mediaItem, mediaMetadata içinde video dosyasının işleme durumunu açıklayan bir status alanı içerir. Yeni yüklenen bir dosya, kullanım için READY olmadan önce PROCESSING değerine sahip videoProcessingStatus değerini döndürür. Bir video medya öğesinin baseUrl öğesi, video işlenene kadar kullanılabilir olmaz.

REST

GET isteği:

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

Bir fotoğraf medya öğesinin yanıtı şu şekildedir. Fotoğraf özelliği, fotoğraf öğelerine ilişkin meta verileri içerir.

{
  "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"
  }
}

Bir video medya öğesinin yanıtı şu şekildedir. Video özelliği, video öğelerine ilişkin meta verileri içerir.

{
  "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

Fotoğraf özelliği, fotoğraf öğelerine ilişkin meta verileri içerir.

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
}

Video özelliği, video öğelerine ilişkin meta verileri içerir.

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

Fotoğraf özelliği, fotoğraf öğelerine ilişkin meta verileri içerir.

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
}

Video özelliği, video öğelerine ilişkin meta verileri içerir.

  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
}

Birden fazla medya öğesi alma

Tanımlayıcılarına göre birden fazla medya öğesini almak için mediaItems.batchGet öğesini mediaItemId kullanarak çağırın.

İstek, istekte sağlanan medya öğesi tanımlayıcılarının sırasına göre bir MediaItemResults listesi döndürür. Her sonuç, hata varsa MediaItem veya Status içerir.

Bir görüşmede talep edebileceğiniz maksimum medya öğesi sayısı 50'dir. Medya öğeleri listesi, yinelenen tanımlayıcılar içermemelidir ve boş olamaz.

REST

Medya öğelerine başarılı ve başarısız erişimi gösteren GET isteğini burada bulabilirsiniz. Her medya öğesi tanımlayıcısını isteğin bir parçası olarak yeni bir mediaItemIds sorgu parametresi olarak belirtin:

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

GET isteği aşağıdaki yanıtı döndürür:

{
  "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
}

Temel URL'ler

Google Fotoğraflar Kitaplığı API'sındaki temel URL'ler, medya öğelerinin baytlarına erişmenize olanak tanır. Çeşitli temel URL'leri kullanarak uygulamanız, medya öğelerini indirebilir veya medya öğelerini uygulamanızda gösterebilir. Temel URL'ler, albümleri listelerken veya medya öğelerine eriştiğinizde yanıta dahil edilen dizelerdir. Bu kodlar 60 dakika boyunca geçerlidir ve olduğu gibi kullanılamadığı için ek parametreler gerektirir.

Çeşitli temel URL'ler şunlardır:

  • baseUrl: Fotoğraf veya küçük resme doğrudan erişebilir ya da video baytlarını indirebilirsiniz.
  • coverPhotoBaseUrl: Albümün kapak fotoğrafına doğrudan erişin.
  • profilePictureBaseUrl: mediaItem sahibinin profil fotoğrafına doğrudan erişin.

Resim temel URL'leri

Resim temel URL'leriyle kullanabileceğiniz seçeneklerin listesi aşağıda verilmiştir:

Parametre
w, h

Açıklama

Genişlik, w ve yükseklik, h parametreleri.

Bir video için fotoğraf veya küçük resim gibi bir resim medya öğesine erişmek için uygulamanızda görüntülemeyi planladığınız boyutları belirtmeniz gerekir (böylece, resim en boy oranı korunarak bu boyutlara ölçeklenebilir). Bunun için, temel URL'yi örneklerde gösterildiği gibi gerekli boyutlarla birleştirin.

Örnekler:

base-url=wmax-width-hmax-height

Aşağıda, 2048 pikselden daha geniş ve 1024 pikselden uzun olmayan medya öğesi görüntülemek için bir örnek verilmiştir:

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

Açıklama

Kırpma, c parametresi.

Resmi tam olarak belirttiğiniz genişlik ve yükseklik boyutlarına göre kırpmak istiyorsanız temel URL'yi zorunlu w ve h parametreleriyle birlikte isteğe bağlı -c parametresiyle birleştirin.

Boyut (piksel cinsinden) [1, 16383] aralığında olmalıdır. Resmin genişliği veya yüksekliği istenen boyutu aşıyorsa resim küçültülüp kırpılır (en boy oranı korunur).

Örnekler:

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

Bu örnekte, uygulama tam olarak 256 piksel genişliğinde ve 256 piksel yüksekliğinde bir küçük resim gibi bir medya öğesi görüntülemektedir:

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

Açıklama

İndirme, d parametresi.

Konum meta verileri hariç tüm EXIF meta verilerini tutan resmi indirmek isterseniz ana URL'yi d parametresiyle birleştirin.

Örnekler:

base-url=d

Bu örnekte uygulama, konum meta verileri hariç tüm meta verileri içeren bir resim indirir:

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

Video temel URL'leri

Video tabanlı URL'lerle kullanabileceğiniz seçeneklerin listesi aşağıda verilmiştir:

Parametre
dv

Açıklama

mediaItem adlı videonun baytlarına erişmek için baseUrl dosyasını indirme videosu ile dv parametresiyle birleştirin.

dv parametresi, orijinal videonun kodu dönüştürülmüş yüksek kaliteli sürümünü ister. Parametre, w ve h parametreleriyle uyumlu değildir.

Video indirmelerinin temel URL'lerinin baytları döndürmesi birkaç saniye kadar sürebilir.

Bu parametreyi kullanmadan önce medya öğelerinin mediaMetadata.status alanının READY olduğundan emin olun. Aksi takdirde, medya öğeniz işlenmeyi tamamlamadıysa bir hata alabilirsiniz.

Örnekler:

base-url=dv

Aşağıdaki örnekte bir videonun baytlarını nasıl indirebileceğiniz gösterilmektedir:

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

Açıklama

Videonun küçük resmine erişmek için resim taban URL'si parametrelerinden birini kullanın.

Varsayılan olarak, tüm video küçük resimlerine oynatma düğmesi yer paylaşımı eklenir. Bu yer paylaşımını kaldırmak için -no parametresine bakın.

Örnekler:

Örnekler için resim temel URL'leri tablosuna bakın.

no

Açıklama

Küçük resim yer paylaşımını kaldır, no parametresi.

Bir videonun küçük resmini, oynatma düğmesi yer paylaşımı olmadan almak isterseniz temel URL'yi no parametresiyle birleştirin.

no parametresi, image base url parametrelerinden en az biri ile kullanılmalıdır.

Örnekler:

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

Aşağıdaki örnekte tam olarak 1280 piksel genişliğinde ve 720 piksel yüksekliğinde olan ve bir oynatma düğmesi yer paylaşımı içermeyen bir video küçük resmi gösterilmektedir:

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

Hareketli fotoğraf tabanı URL'leri

Hareketli fotoğraflar hem fotoğraf hem de video öğesi içerir. Hareketli fotoğraf baseUrl istekleri için resim temel URL'lerindeki veya video taban URL'lerindeki parametreleri kullanabilirsiniz.

Parametre
dv

Açıklama

Hareketli fotoğraf medya öğesinin video öğesini almak için video taban URL'lerinden indirirken olduğu gibi dv parametresini kullanın.

w, h, c ve d

Açıklama

Hareketli fotoğraf medya öğesinin fotoğraf öğesini almak için resim temel URL'leri biçimini kullanın.