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 fazla kapsam içerir. Çeşitli çağrılardan döndürülen medya öğeleri, hangi kapsamlara bağlı olarak farklılık gösterir? için istekte bulunuldu.

photoslibrary.readonly kapsamı, şuradaki tüm medya öğelerine erişim izni verir: kullanıcının kitaplığı. photoslibrary.readonly.appcreateddata kapsamı erişime izin verir yalnızca uygulama tarafından oluşturulan medya öğeleriyle uyumludur. Daha fazla bilgi için bkz. Yetkilendirme kapsamları.

Genel Bakış

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

Fotoğrafları seçmek için filtreleri kullanabilirsiniz içerik kategorisi veya ortam türüyle eşleşen kullanıcının kitaplığından kaldırın. Bu özellik, tıklayın.

Kitaplığın ve albüm içeriğinin listelenmesi, bir medya öğeleri listesi döndürür. Bir albümün parçası olan zenginleştirmeler dahil edilmez. Medya öğeleri bir fotoğrafı, videoyu veya diğer medyaları açıklar. CEVAP mediaItem, öğenin doğrudan bağlantısını ve Google Fotoğraflar ve diğer ilgili meta veriler. Daha fazla bilgi için bkz. Medya öğelerine erişin ve mediaItems.

Dikkat: Kullanıcı fotoğraflarını ve videolarını önbelleğe almayın. Bunun yerine, medya öğesini depola id ve ihtiyacınız olduğunda ayrıntılarını tekrar isteyebilirsiniz. Resimler değişebilir ve baseUrl üzerinden doğrudan erişimin süresi 60 dakika sonra dolar. Daha fazla bkz. Medya öğelerine erişin.

Albümleri listeleme

Kullanıcının albümlerinin listesini şu komutla alabilirsiniz: albums.list.

REST

Örnek bir istek:

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, şuradaki içeriği almak için kullanılabilecek bir kimliğe sahiptir: Albüm içeriği listeleme bölümünde gösterildiği gibi. Aynı zamanda başlığı ve içerdiği medya öğelerinin sayısını gösterir.

productUrl, Google Fotoğraflar'daki şu olabilecek albümü işaret eder: kullanıcı tarafından açıldı.

coverPhotoMediaItemId, medya öğesini içerir Kimliği bu albümün kapak fotoğrafını temsil eder. Bu kapak resmine erişmek için şunu kullanın: coverPhotoBaseUrl coverPhotoBaseUrl özelliğini belirtmek için ek parametrelerini kullanın.

Kullanıcının hesabında oluşturulan veya kullanıcının albümüne eklenen albümler hesabınızın ve uygulamanızın paylaştığı mülklere ait veriler, ek bir shareInfo mülkü içerir. Daha fazla bilgi için Medya paylaşma konusuna bakın.

Albümlerde, medya oluşturup oluşturamayacağınızı belirten bir isWriteable işareti de bulunabilir öğe var. Bu işaret döndürülmezse varsayılan olarak false olur. Evet uygulamanıza verilen erişime bağlıdır. Buna şunlar da dahildir:

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

Bu ölçütlerden herhangi biri değişirse bu işaret değişebilir. Daha fazla bilgi için bkz. Albüm oluşturun. İlgili içeriği oluşturmak için kullanılan yanıt da bir nextPageToken içeriyor. Daha fazla bilgi için bkz. Sayfaları numaralandırma.

Boş albümlerin yanıtı şuna göre değişir: mediaItemsCount ve coverPhotoMediaItemId varsayılan olarak 0 değerine ayarlanır ve REST'ten çıkarılır. tıklayın. Ayrıca coverPhotoBaseUrl değerinin varsayılan bir yer tutucuya işaret ettiğini unutmayın görüntüsüdür.

Kitaplık içeriklerini listeleme

Kullanıcının Google Fotoğraflar kitaplığındaki tüm medya öğelerini listeleyebilirsiniz. Arşivlenen ve silinen öğeler dahil değildir. Medya öğelerini içerik, tarih ve diğer özellikleri uygulayarak filtreleri hakkında daha fazla bilgi edinin. Kullanıcı bir Google Fotoğraflar'daki Paylaşım sekmesinde bulunan öğeyi söz konusu öğe bu listede yer almaz.

Bir medya öğesini almak için şu numarayı arayın: mediaItems.list.

REST

Örnek bir istek:

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 az yeniye doğru sıralanmış bir medya öğesi listesini içerir. Daha fazla bilgi için bkz. mediaItems. Aynı zamanda Aşağıdaki bölümde daha ayrıntılı açıklanan bir nextPageToken içerir: Sayfaları numaralandırma.

Albüm içeriğini listeleme

Bir albümdeki tüm medya öğelerini listelemek için albumId alanını arama isteği. albumId hakkında daha fazla bilgi için bkz. Giriş albümleri ve Paylaşılan albümleri listeleme'yi tıklayın. Eğer albumId geçersizse Bad Request hatası döndürülür. Kimlik geçerliyse ancak kimliği doğrulanan kullanıcı için albüm mevcut değilse Not Found hatası geri döndü. Hata işlemeyle ilgili daha fazla bilgi için Performans ipuçları ve En iyi uygulamalar.

REST

Örnek bir istek:

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. Beğenmeme durumu: kitaplık içeriklerini listelediğinde, medya öğeleri albümünüz. Daha fazla bilgi için bkz. mediaItems ve Sayfaları numaralandırma. Kullanıcı siparişi şurada düzenleyebilir: Google Fotoğraflar arayüzü.

albumId ayarlanırsa 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 daha önce paylaşmış olduğu tüm albümlerin listesini bir kullanıcıyla paylaşıldı. Bu, Google Fotoğraflar uygulaması.

Kullanıcının Google Fotoğraflar kitaplığına eklediği paylaşılan albümler albümleri listeleme çağrısında da döndürülür. Şunu yapın: paylaşılan albümleri Library API aracılığıyla listelemek için gerçekleştirilen aşağıdaki çağrı:

REST

Örnek bir istek:

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
}

sharedAlbums albümüne bir albüm listesi eklendi. Daha fazla bilgi için bkz. Albümleri listeleme. Yanıt da bir nextPageToken içeriyor. Daha fazla bilgi için Sayfaları numaralandırma bölümüne bakın.

Uygulamanızın oluşturup paylaştığı albümler ek bir shareInfo Daha fazla bilgi için Paylaşma bölümüne bakın medya.

Uygulama tarafından oluşturulan albümleri listeleme

Uygulamanız tarafından oluşturulan albümleri excludeNonAppCreatedData, şu görüşmelerde true olarak ayarlandı:

• albums.list
• sharedAlbums.list

REST

Kullanıcının albümündeki tüm albümlerin listelenmesi için bir GET isteği Yalnızca uygulamanız tarafından oluşturulan Google Fotoğraflar kitaplığı:

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

Kullanıcının albümündeki tüm paylaşılan albümleri listelemek için bir GET isteği Yalnızca uygulamanız tarafından oluşturulan Google Fotoğraflar kitaplığı:

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 (ör. listesi yöntemleri) yanıtı sayfalara ayırabilir. Her bir sorgu için maksimum sonuç sayısı sayfası, pageSize parametresiyle verilir.

mediaItems:search ve mediaItems:list çağrıları için varsayılan sayfa boyutu 25 öğe. Bu sayfa boyutunu öneririz çünkü sayfa boyutu ile yanıt boyutu ve doluluk oranıdır. Medya öğesi için maksimum sayfa boyutu arama ve liste istekleri 100 öğedir.

Albümlerin listelenmesi için varsayılan ve önerilen sayfa boyutu 20 albümdür ve en fazla 50 albüm.

Kullanılabilir sonuçların sayısı sayfa boyutundan fazla olduğunda, yanıt uygulamanıza bunu belirten bir nextPageToken içerir daha fazla sonuç getirilir.

Not: pageSize parametresi maksimum bir değerdir; daha az sonuç olabilir yalnızca talep edilenlerden daha fazla sonuç gösteriliyor.

Örnek

nextPageToken öğesini, parametrede sonraki isteklere eklemeniz gerekir pageToken olarak ayarlanmıştır. pageToken öğesini birlikte belirtin isteğe bağlı olarak veya bir sorgu parametresi olarak ekleyebilirsiniz.

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 daha önce kullanılmış bir nextPageToken, aynı isteğinde bulunabilirsiniz.

Not: Bir şeyin nextPageToken olup olmadığına dair tek gösterge, sunucudan getirilecek başka sonuçlar da var. Her şeyin sayısını sonuçları görmek için nextPageToken cihazınızı kullanmanız gerekip gerekmediğini belirler. Bir talep sayfa boyutunda istenenden daha az sonuç döndürdüğünden emin olabilirsiniz. nextPageToken Mevcutsa, ilk isteğinizden sonra daha fazla sonuç için istek gönderebilirsiniz.