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.
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:
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.
Ö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.