Kitaplık içeriklerini, albümleri ve medya öğelerini listeleme

Gerekli yetkilendirme kapsamları

Google Fotoğraflar Kitaplığı API'si, medya öğelerine ve albümlere erişmek için kullanılan birden fazla kapsam içerir. Çeşitli çağrılardan döndürülen medya öğeleri, geliştirici tarafından istenen kapsamlara bağlı olarak değişiklik gösterir.

photoslibrary.readonly kapsamı, kullanıcının kitaplığındaki tüm medya öğelerine erişim sağlar. photoslibrary.readonly.appcreateddata kapsamı, yalnızca uygulama tarafından oluşturulan medya öğelerine erişim sağlar. Daha fazla bilgi için Yetkilendirme kapsamları bölümüne bakın.

Genel bakış

Kullanıcının Google Fotoğraflar'a yedeklediği medya öğelerini listelemek, API'nin önemli bir kullanımıdır. Belirli bir albümdeki veya kullanıcının kitaplığının tamamından (Google Fotoğraflar uygulamasındaki varsayılan görünüm) öğeler listelenebilir.

Kullanıcının kitaplığındaki öğeleri listelerken belirli bir tarih, içerik kategorisi veya medya türüyle eşleşen fotoğrafları seçmek için filtreleri kullanabilirsiniz. Albümlerden öğe listelediğinizde bu özellik desteklenmez.

Kitaplık ve albüm içeriklerini listelemek medya öğelerinin listesini döndürür. Albümün bir parçası olan zenginleştirmeler dahil edilmez. Medya öğeleri bir fotoğrafı, videoyu veya diğer medyayı tanımlar. mediaItem doğrudan öğenin bağlantısını, öğenin Google Fotoğraflar'daki bağlantısını ve diğer ilgili meta verileri içerir. Daha fazla bilgi için Medya öğelerine erişme ve mediaItems bölümlerine bakın.

Dikkat: Kullanıcı fotoğraflarını ve videolarını önbelleğe almayın. Bunun yerine, id medya öğesini depolayın ve ihtiyaç duyduğunuzda ayrıntılarını tekrar isteyin. Resimler değişebilir ve baseUrl üzerinden doğrudan erişim 60 dakika sonra sona erer. Daha fazla bilgi için Medya öğelerine erişme bölümünü inceleyin.

Giriş albümleri

albums.list'i kullanarak kullanıcının albümlerinin listesini alabilirsiniz.

REST

Aşağıda örnek bir istek verilmiştir:

GET https://photoslibrary.googleapis.com/v1/albums

İstek aşağıdaki sonucu döndürür:

{
  "albums": [
    {
      "id": "album-id",
      "title": "album-title",
      "productUrl": "album-product-url",
      "coverPhotoBaseUrl": "album-cover-base-url_do-not-use-directly",
      "coverPhotoMediaItemId": "album-cover-media-item-id",
      "isWriteable": "whether-you-can-write-to-this-album",
      "mediaItemsCount": "number-of-media-items-in-album"
    },
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all albums in the user's library
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums();

  for (Album album : response.iterateAll()) {
    // Get some properties of an album
    String id = album.getId();
    String title = album.getTitle();
    String productUrl = album.getProductUrl();
    String coverPhotoBaseUrl = album.getCoverPhotoBaseUrl();
    // The cover photo media item id field may be empty
    String coverPhotoMediaItemId = album.getCoverPhotoMediaItemId();
    boolean isWritable = album.getIsWriteable();
    long mediaItemsCount = album.getMediaItemsCount();
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums in the user's library
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // Get some properties of an album
        $albumId = $album->getId();
        $title = $album->getTitle();
        $productUrl = $album->getProductUrl();
        $coverPhotoBaseUrl = $album->getCoverPhotoBaseUrl();
        // The cover photo media item id field may be empty
        $coverPhotoMediaItemId = $album->getCoverPhotoMediaItemId();
        $isWriteable = $album->getIsWriteable();
        $totalMediaItems = $album->getTotalMediaItems();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Döndürülen her albümün, albüm içeriğini Albüm albümünü listeleme bölümünde gösterildiği şekilde almak için kullanılabilecek bir kimliği vardır. Ayrıca, başlığı ve içerdiği medya öğelerinin sayısını da içerir.

productUrl, Google Fotoğraflar'da kullanıcıları açabilecek olan albüme işaret eder.

coverPhotoMediaItemId, bu albümün kapak fotoğrafını temsil eden medya öğesi kimliğini içerir. Bu kapak resmine erişmek için coverPhotoBaseUrl özelliğini kullanın. Ek parametreler belirtmeden doğrudan coverPhotoBaseUrl öğesini kullanmanız gerekir.

Kullanıcının hesabında oluşturulan veya kullanıcının hesabına eklenen ve uygulamanızın paylaştığı albümler ek bir shareInfo özelliği içerir. Daha ayrıntılı bilgi için Medya paylaşma başlıklı makaleye bakın.

Albümlerde, albümde medya öğeleri oluşturup oluşturamayacağınızı belirtmek için bir isWriteable işareti de bulunabilir. Bu işaret, döndürülmezse varsayılan olarak false değerine ayarlanır. Bu durum, aşağıdakiler dahil olmak üzere başvurunuza verilen erişime bağlıdır:

• Albümü kimin oluşturduğu.
• Paylaşılıp paylaşılmadığı.
• Kullanıcının hangi kapsamları onayladığını belirtir.

Bu ölçütlerden biri değişirse bu işaret değişebilir. Daha fazla bilgi için Albüm oluşturma bölümünü inceleyin. Yanıtta ayrıca bir nextPageToken da yer almaktadır. Daha fazla bilgi için Sayfalara ayırma bölümüne bakın.

Boş albümlere verilen yanıtlar değişiklik gösterir. mediaItemsCount ve coverPhotoMediaItemId, varsayılan olarak 0 olarak ayarlanır ve REST yanıtından çıkarılır. Ayrıca coverPhotoBaseUrl öğesinin varsayılan yer tutucu resme işaret ettiğini unutmayın.

Giriş kitaplığı içeriği

Kullanıcının Google Fotoğraflar kitaplığındaki tüm medya öğelerini listeleyebilirsiniz. Arşivlenen ve silinen öğeleri hariç tutar. Filtreleri uygulayarak medya öğelerini içeriklerine, tarihlerine ve diğer özelliklerine göre listeleyebilirsiniz. Kullanıcı Google Fotoğraflar'daki Paylaşım sekmesinde mevcut olan bir öğeyi kitaplığına eklemediyse bu öğe bu listeye dahil edilmez.

Bir medya öğesini almak için mediaItems.list çağrısı yapın.

REST

Aşağıda örnek bir istek verilmiştir:

GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
}

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

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all media items in the user's library
  // Iterate over all the retrieved media items
  // Pagination is handled automatically
  ListMediaItemsPagedResponse response = photosLibraryClient.listMediaItems();
  for (MediaItem item : response.iterateAll()) {
    // Get some properties of a media item
    String id = item.getId();
    String description = item.getDescription();
    String mimeType = item.getMimeType();
    String productUrl = item.getProductUrl();
    String filename = item.getFilename();
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all media items in the user's library
    // Iterate over all the retrieved media items
    // Pagination is handled automatically
    $response = $photosLibraryClient->listMediaItems();
    foreach ($response->iterateAllElements() as $item) {
        // Get some properties of a media item
        /* @var $item \Google\Photos\Library\V1\MediaItem */
        $id = $item->getId();
        $description = $item->getDescription();
        $mimeType = $item->getMimeType();
        $productUrl = $item->getProductUrl();
        $filename = $item->getFilename();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Yanıt, en sık kullanılandan en yeniye doğru sıralanmış medya öğelerinin listesini içerir. Daha fazla bilgi için mediaItems konusuna bakın. Ayrıca, Sayfalara ayırma bölümünde daha ayrıntılı bir şekilde açıklanan bir nextPageToken bulunur.

Albüm içeriğini listeleme

Bir albümdeki tüm medya öğelerini listelemek için arama isteğinize albumId alanını ekleyin. albumId hakkında daha fazla bilgi için Albümleri listeleme ve Paylaşılan albümleri listeleme bölümlerine bakın. albumId geçersizse bir Bad Request hatası döndürülür. Kimlik geçerliyse ancak kimlik doğrulaması yapılmış kullanıcı için albüm mevcut değilse Not Found hatası döndürülür. Hata işleme hakkında daha fazla bilgi için Performans ipuçları ve En iyi uygulamalar bölümlerini inceleyin.

REST

Aşağıda örnek bir istek verilmiştir:

POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
  "albumId": "album-id"
}

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

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all media items in an album
  // Provide the ID of the album as a parameter in the searchMediaItems call
  // Iterate over all the retrieved media items
  SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(albumId);

  for (MediaItem item : response.iterateAll()) {
    // ...
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all media items in an album
    // Provide the ID of the album as a parameter in the searchMediaItems call
    // Iterate over all the retrieved media items
    $response = $photosLibraryClient->searchMediaItems(['albumId' => $albumId]);
    foreach ($response->iterateAllElements() as $item) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Yanıtta bir nextPageToken ve medya öğelerinin listesi yer alıyor. Kitaplık içeriği listelenirken aksine, medya öğeleri albümdeki sıralamalarına göre döndürülür. Daha fazla bilgi için mediaItems ve Sayfalara ayırma'ya bakın. Kullanıcı, siparişi Google Fotoğraflar arayüzünde düzenleyebilir.

albumId ayarlanmışsa albüm içeriğini listelerken filtre uygulayamazsınız. Bunu yapmak Bad Request hatasıyla sonuçlanır.

Paylaşılan albümleri listeleme

Kullanıcının paylaştığı veya bir kullanıcıyla paylaşılan tüm albümlerin listesini alabilirsiniz. Bu, Google Fotoğraflar uygulamasındaki Paylaşım sekmesine benzer.

Kullanıcının Google Fotoğraflar kitaplığına eklediği paylaşılan albümler, listeleme albümleri çağrısında da döndürülür. Paylaşılan albümleri Library API üzerinden listelemek için aşağıdaki çağrıyı yapın:

REST

Aşağıda örnek bir istek verilmiştir:

GET https://photoslibrary.googleapis.com/v1/sharedAlbums

İstek aşağıdaki sonucu döndürür:

{
  "sharedAlbums": [...]
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all albums that have been shared by the user
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums();

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums that have been shared by the user
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listSharedAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Albümler listesi sharedAlbums içindedir. Daha fazla bilgi için Albümleri listeleme bölümüne bakın. Yanıtta ayrıca bir nextPageToken yer alıyor. Daha fazla bilgi için Sayfalara ayırma konusuna bakın.

Uygulamanızın oluşturup paylaştığı albümler ek bir shareInfo özelliği içerir. Daha ayrıntılı bilgi için Medya paylaşma bölümüne bakın.

Uygulama tarafından oluşturulan albümleri listeleme

Aşağıdaki aramalarda excludeNonAppCreatedData tarafından true olarak ayarlanmış olup uygulamanız tarafından oluşturulan albümleri listeleyebilirsiniz:

• albums.list
• sharedAlbums.list

REST

Kullanıcının Google Fotoğraflar kitaplığındaki tüm albümlerin yalnızca uygulamanız tarafından oluşturulmuş GET isteği burada listelenir:

GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

Kullanıcının yalnızca uygulamanızın oluşturduğu Google Fotoğraflar kitaplığındaki tüm paylaşılan albümleri listelemek için GET isteğini şu şekilde alabilirsiniz:

GET https://photoslibrary.googleapis.com/v1/sharedAlbums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

Java

try {
  // Make a request to list all albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

try {
  // Make a request to list all shared albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response =
      photosLibraryClient.listSharedAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums that have been created by your app
    $response = $photosLibraryClient->listAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

try {
    // Make a request to list all shared albums that have been created by your app
    $response = $photosLibraryClient->listSharedAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

REST için sayfalara ayırma

Performansı artırmak için çok sayıda sonuç döndüren yöntemler (liste yöntemleri gibi) yanıtı sayfalara ayırabilir. Her sayfadaki maksimum sonuç sayısı, pageSize parametresiyle verilir.

mediaItems:search ve mediaItems:list çağrıları için varsayılan sayfa boyutu 25 öğedir. Yanıtın boyutu ile doluluk oranı arasında bir denge kurduğu için bu sayfa boyutunu öneririz. Medya öğesi arama ve liste istekleri için maksimum sayfa boyutu 100 öğedir.

Albümleri listelerken varsayılan ve önerilen sayfa boyutu 20 albüm olup maksimum 50 albümdür.

Mevcut sonuçların sayısı sayfa boyutundan büyük olduğunda yanıt, sunucudan alınacak daha fazla sonuç olduğunu gösteren bir nextPageToken içerir.

Not: pageSize parametresi bir maksimum değerdir. İstenenden daha az sonuç döndürülebilir.

Örnek

nextPageToken öğesini, aşağıdaki örnekte gösterildiği gibi pageToken parametresinde sonraki isteklere eklemelisiniz. pageToken değerini, işlem için gereken diğer parametrelerle birlikte isteğin gövdesinde veya bir sorgu parametresi olarak belirtin.

İstek No. 1

{
  "pageSize": "5",
  "filters": { … }
}

Yanıt 1

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

İstek #2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

2. Yanıt

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

Bu kalıp, başka nextPageToken nesne kalmayıncaya kadar devam eder.

nextPageToken yalnızca aynı istek için geçerlidir. Herhangi bir parametre değiştirilirse daha önce kullanılan bir nextPageToken, aynı istekte kullanılmamalıdır.

Not: Sunucudan getirilecek daha fazla sonuç olup olmadığının tek göstergesi nextPageToken varlığıdır. nextPageToken kullanmanız gerekip gerekmediğini belirlemek için sonuç sayısını saymayın. Bir istek, sayfa boyutunda istenenden daha az sonuç döndürebilir. nextPageToken mevcutsa ilk isteğinizden sonra daha fazla sonuç için istek gönderebilirsiniz.