Uygulama tarafından oluşturulan medya öğelerini ve albümleri listeleme

Gerekli yetkilendirme kapsamları

Uygulama tarafından oluşturulan içeriğin listelenmesinde photoslibrary.readonly.appcreateddata kapsamı gerekir. Kapsamlar hakkında daha fazla bilgi için Yetkilendirme kapsamları başlıklı makaleyi inceleyin.

Genel Bakış

Kitaplık API'si, uygulamanızın oluşturduğu medya öğelerini listelemenizi ve bunlara erişmenizi sağlar.

Medya öğelerini listelemenin bazı temel özellikleri şunlardır:

  • Uygulama tarafından oluşturulan belirli albümlerdeki veya uygulama tarafından oluşturulan kitaplığın tamamındaki medya öğelerini listeleme

  • Sonuçlarınızı daraltmak için listeleme yaparken filtreler (tarih, içerik kategorisi, medya türü) uygulayın.

  • Doğrudan bağlantılar ve meta veriler gibi önemli ayrıntılarla mediaItem nesnelerini alın.

Kitaplığın ve albüm içeriğinin listelenmesi, bir medya öğeleri listesi döndürür. Albümlerin parçası olan zenginleştirmeler dahil değildir. 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 öğenin bağlantısını ve diğer alakalı meta verileri içerir. Daha fazla bilgi için Medya öğelerine erişme ve mediaItems başlıklı makaleleri inceleyin.

Uygulama tarafından oluşturulan albümleri listeleme

albums.list kullanarak uygulamanız tarafından oluşturulan albümleri listeleyebilirsiniz.

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

Döndürülen her albümün, Albüm içeriğini listeleme 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'da kullanıcı tarafından açılabilen albümü gösterir.

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 simgesini kullanın. Ek parametreler belirtmeden coverPhotoBaseUrl parametresini doğrudan kullanmamalısınız.

Yanıt da bir nextPageToken içeriyor. Daha fazla bilgi için Sayfalandırma bölümüne bakın.

Boş albümler için yanıt, mediaItemsCount ve coverPhotoMediaItemId varsayılan olarak 0 olarak ayarlandığı ve REST yanıtından çıkarıldığı için değişiklik gösterir. Ayrıca coverPhotoBaseUrl'ün varsayılan bir yer tutucu resmi gösterdiğini unutmayın.

Uygulama tarafından oluşturulan kitaplık içeriklerini listeleme

Kullanıcının Google Fotoğraflar kitaplığındaki uygulamanız tarafından oluşturulan tüm medya öğelerini listeleyebilirsiniz. Buna arşivlenmiş ve silinen öğeler dahil değildir. Filtreler kullanarak medya öğelerini içerik, tarih ve diğer özelliklerine göre listeleyebilirsiniz.

Medya öğelerini listelemek için mediaItems.list simgesine dokunun.

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

Yanıtta, en çok görüntülenenden en az görüntülenene göre sıralanmış medya öğelerinin listesi yer alır. Daha fazla bilgi için mediaItems başlıklı makaleyi inceleyin. Ayrıca Sayfalandırma bölümünde daha ayrıntılı olarak açıklanan bir nextPageToken içerir.

Albüm içeriklerini 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 başlıklı makaleyi inceleyin. 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 bir Not Found hatası döndürülür. Hatalarla ilgili daha fazla bilgi için Performans ipuçları ve En iyi uygulamalar başlıklı makaleleri inceleyin.

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

Yanıt, bir nextPageToken ve medya öğelerinin listesini içerir. Kitaplık içeriklerinin listelenmesinden farklı olarak, medya öğeleri albümdeki sıralarına göre döndürülür. Daha fazla bilgi için mediaItems ve Sayfalandırma bölümlerine bakın. Kullanıcı, siparişi Google Fotoğraflar arayüzünde düzenleyebilir.

albumId ayarlanmışsa albüm içeriklerini listelerken filtre uygulayamazsınız. Aksi takdirde Bad Request hatası oluşur.

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. Bu sayfa boyutu, yanıtın boyutu ile doluluk oranı arasında bir denge sağladığı için önerilir. Medya öğesi arama ve liste istekleri için maksimum sayfa boyutu 100 öğedir.

Albüm listelemede varsayılan ve önerilen sayfa boyutu 20 albümdür. En fazla 50 albüm listelenir.

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

Örnek

Aşağıdaki örnekte gösterildiği gibi, nextPageToken parametresini pageToken parametresindeki sonraki isteklere eklemeniz gerekir. pageToken öğesini, işlem için gerekli diğer parametrelerle birlikte isteğin gövdesinde veya sorgu parametresi olarak belirtin.

İstek #1

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

Yanıt #1

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

İstek #2

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

Yanıt #2

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

nextPageToken nesnesi kalmayana kadar bu kalıbı sürdürün.

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.