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

Gerekli yetkilendirme kapsamları

Google Photos Library API, medya öğelerine ve albümlere erişmek için kullanılan birden çok kapsam içerir. Çeşitli çağrılardan döndürülen medya öğeleri, geliştirici tarafından istenen kapsamlara göre farklılık 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ış

API'nin önemli bir kullanımı, kullanıcının Google Fotoğraflar'a yedeklediği medya öğelerinin listelenmesidir. Belirli bir albümdeki veya kullanıcının tüm kitaplığındaki (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 filtrelerden yararlanabilirsiniz. Albümlerdeki öğeleri listelediğinizde bu özellik desteklenmez.

Kitaplığın ve albüm içeriğinin listelenmesi, medya öğelerinin bir listesini döndürür. Bir albümün parçası olan zenginleştirmeler dahil edilmez. Medya öğeleri bir fotoğrafı, videoyu veya başka bir medyayı tanımlar. mediaItem; öğenin doğrudan bağlantısını, Google Fotoğraflar'daki bağlantısını ve diğer ilgili meta verileri içerir. Daha fazla bilgi için Medya öğelerine erişim ve mediaItems konularına bakın.

Dikkat: Kullanıcı fotoğraflarını ve videolarını önbelleğe almayın. Bunun yerine, id medya öğesini depolayın ve ihtiyacınız olduğunda bu öğenin 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şim bölümüne bakın.

Albümleri listeleme

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, Listeleme albüm içeriği bölümünde gösterildiği gibi albümün içeriğini 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'daki kullanıcı tarafından açılabilen albümü 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. coverPhotoBaseUrl özelliğini ek parametreler belirtmeden doğrudan kullanmamalısınız.

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 mülkü içerir. Daha fazla ayrıntı için Medya paylaşma başlıklı makaleyi inceleyin.

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

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

Bu ölçütlerden herhangi biri değişirse bu işaret de değişebilir. Daha fazla bilgi için Albüm oluşturma konusuna bakın. Yanıtta nextPageToken de yer alıyor. Daha fazla bilgi için Sayfaları numaralandırma bölümüne bakın.

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

Kitaplık içeriklerini listeleme

Kullanıcının Google Fotoğraflar kitaplığındaki tüm medya öğelerini listeleyebilirsiniz. Arşivlenen ve silinen öğeler buna dahil değildir. Medya öğelerini filtreler uygulayarak içeriklerine, tarihlerine ve diğer özelliklerine göre listeleyebilirsiniz. Kullanıcı Google Fotoğraflar'ın Paylaşım sekmesinde bulunan bir öğeyi kitaplığına eklemediyse söz konusu öğe bu listeye dahil edilmez.

Bir medya öğesini almak için mediaItems.list öğesini çağırı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 yeniden en eskiye doğru sıralanmış medya öğelerinin bir listesini içerir. Daha fazla bilgi için mediaItems adresini inceleyin. Ayrıca, Sayfaları numaralandırma bölümünde daha ayrıntılı olarak açıklanan bir nextPageToken içerir.

Listeleme albümü içeriği

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 konularına bakın. albumId geçersizse Bad Request hatası döndürülür. Kimlik geçerliyse ancak kimliği doğrulanmış kullanıcı için albüm yoksa Not Found hatası döndürülür. Hata giderme hakkında daha fazla bilgi için Performans ipuçları ve En iyi uygulamalar bölümlerine bakın.

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ıt, bir nextPageToken ve medya öğelerinin listesini içerir. Kitaplık içeriklerinin listelenmesinin aksine, medya öğeleri albümdeki sıralarına göre döndürülür. Daha fazla ayrıntı için mediaItems ve Sayfalara ayırma sayfalarına göz atın. Kullanıcı, siparişi Google Fotoğraflar arayüzünde düzenleyebilir.

albumId ayarlandıysa albüm içeriklerini listelerken filtre uygulayamazsınız. Bu işlem, Bad Request hatasına neden olur.

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 de albümleri listeleme çağrısında döndürülür. Library API aracılığıyla paylaşılan albümleri 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üm listesi sharedAlbums içinde mevcut. Daha fazla bilgi için Albümleri listeleme bölümüne bakın. Yanıtta nextPageToken de yer alıyor. Daha fazla bilgi için Sayfaları numaralandırma konusuna bakın.

Uygulamanızın oluşturduğu ve paylaştığı albümler ek bir shareInfo mülkü içerir. Daha fazla bilgi için Medya paylaşımı bölümüne bakın.

Listeleme uygulaması tarafından oluşturulan albümler

Uygulamanız tarafından oluşturulan albümleri excludeNonAppCreatedData aşağıdaki çağrılarda true olarak ayarlanmış şekilde listeleyebilirsiniz:

• albums.list
• sharedAlbums.list

REST

Kullanıcının Google Fotoğraflar kitaplığında bulunan, yalnızca uygulamanız tarafından oluşturulan tüm albümlerin listelenmesi için bir GET isteği gönderin:

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

Kullanıcının Google Fotoğraflar kitaplığında bulunan ve yalnızca uygulamanız tarafından oluşturulan tüm paylaşılan albümlerin listelenmesi için bir GET isteği gönderin:

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

Çok sayıda sonuç döndüren yöntemler (liste yöntemleri gibi) performansı iyileştirmek için yanıtı sayfalara ayırabilir. Her sayfadaki maksimum sonuç sayısı pageSize parametresi tarafından 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 denge sağladığından bu sayfa boyutunu öneririz. Medya öğesi arama ve liste istekleri için maksimum sayfa boyutu 100 öğedir.

Albümler listelenirken varsayılan ve önerilen sayfa boyutu en fazla 50 albüm olmak üzere 20 albümdür.

Kullanılabilir sonuçların sayısı sayfa boyutundan büyük olursa yanıtta bir nextPageToken bulunur. Bu, uygulamanıza sunucudan getirilecek daha fazla sonuç olduğunu belirtir.

Not: pageSize parametresi 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 eklemeniz gerekir. pageToken öğesini, işlem için gereken diğer parametrelerle birlikte isteğin gövdesinde veya bir sorgu parametresi olarak belirtin.

1. İstek

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

Yanıt 1

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

2. İstek

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

Yanıt 2

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

Başka nextPageToken nesne kalmayıncaya kadar bu desene devam edin.

nextPageToken yalnızca aynı istek için geçerlidir. Herhangi bir parametre değiştirilirse daha önce kullanılmış olan 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 öğenizi 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 varsa ilk isteğinizden sonra daha fazla sonuç için istek gönderebilirsiniz.