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