Cakupan otorisasi yang diperlukan
Google Photos Library API berisi beberapa cakupan yang digunakan untuk mengakses item dan album media. Item media yang ditampilkan dari berbagai panggilan berbeda berdasarkan cakupan yang telah diminta oleh developer.
Cakupan photoslibrary.readonly
memungkinkan akses ke semua item media di
library pengguna. Cakupan photoslibrary.readonly.appcreateddata
hanya memungkinkan akses
ke item media yang dibuat oleh aplikasi. Untuk informasi selengkapnya, lihat
Cakupan otorisasi.
Ringkasan
Penggunaan API yang penting adalah mencantumkan item media yang telah dicadangkan pengguna ke Google Foto. Item di album tertentu atau dari seluruh library pengguna (tampilan default di aplikasi Google Foto) dapat dicantumkan.
Anda dapat menggunakan filter untuk memilih foto yang cocok dengan tanggal, kategori konten, atau jenis media yang ditentukan saat mencantumkan item dari galeri pengguna. Fitur ini tidak didukung saat Anda mencantumkan item dari album.
Mencantumkan koleksi dan konten album akan menampilkan daftar item media.
Pengayaan yang merupakan bagian dari album
tidak disertakan. Item media menjelaskan foto, video, atau media lainnya. mediaItem
menyertakan link langsung ke item, link ke item di
Google Foto, dan metadata lain yang relevan. Untuk mengetahui informasi selengkapnya, lihat
Mengakses item media dan
mediaItems
.
Mencantumkan album
Anda dapat mengambil daftar album pengguna menggunakan albums.list.
REST
Berikut adalah contoh permintaan:
GET https://photoslibrary.googleapis.com/v1/albums
Permintaan tersebut menampilkan hasil berikut:
{ "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 }
Setiap album yang ditampilkan memiliki ID yang dapat digunakan untuk mengambil isi album seperti yang ditunjukkan dalam Mencantumkan konten album. Format ini juga mencakup judul dan jumlah item media yang ada di dalamnya.
productUrl
mengarah ke album di Google Foto yang dapat
dibuka oleh pengguna.
coverPhotoMediaItemId
berisi ID item
media yang
mewakili foto sampul album ini. Untuk mengakses gambar sampul ini, gunakan
coverPhotoBaseUrl
. Anda tidak boleh menggunakan coverPhotoBaseUrl
secara langsung tanpa menentukan parameter tambahan.
Album yang telah dibuat di akun pengguna atau ditambahkan ke akun
pengguna dan yang telah dibagikan aplikasi Anda menyertakan properti shareInfo
tambahan.
Untuk mengetahui detail selengkapnya, lihat Berbagi media.
Album mungkin juga memiliki tanda isWriteable
untuk menunjukkan apakah Anda dapat membuat item
media dalam album. Jika tidak ditampilkan, flag ini secara default disetel ke false
. Hal ini
bergantung pada akses yang diberikan ke aplikasi Anda, termasuk hal berikut:
- Siapa yang membuat album.
- Apakah dibagikan atau tidak.
- Cakupan yang telah disetujui pengguna.
Tanda ini dapat berubah jika salah satu kriteria ini berubah. Untuk mengetahui detail selengkapnya, lihat
Membuat album. Respons
juga berisi nextPageToken
. Untuk informasi selengkapnya, lihat
Penomoran halaman.
Respons untuk album kosong bervariasi dalam hal ini, mediaItemsCount
dan
coverPhotoMediaItemId
ditetapkan ke 0 secara default dan dihilangkan dari respons
REST. Perhatikan juga bahwa coverPhotoBaseUrl
mengarah ke gambar placeholder
default.
Mencantumkan konten library
Anda dapat mencantumkan semua item media dari galeri Google Foto pengguna tersebut. Tidak termasuk item yang diarsipkan dan dihapus. Anda bisa mencantumkan item media berdasarkan konten, tanggal, dan properti lainnya dengan menerapkan filter. Jika pengguna belum menambahkan item yang tersedia di tab Berbagi pada Google Foto ke galeri fotonya, item tersebut tidak akan disertakan dalam daftar ini.
Untuk mengambil item media, panggil mediaItems.list.
REST
Berikut adalah contoh permintaan:
GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
}
Permintaan GET menghasilkan respons berikut:
{ "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 }
Respons berisi daftar item media, yang diurutkan dari yang paling baru ke yang paling lama.
Untuk mengetahui informasi selengkapnya, lihat
mediaItems
. Class ini juga
berisi nextPageToken
, yang dijelaskan secara lebih mendetail dalam
Penomoran halaman.
Mencantumkan konten album
Untuk mencantumkan semua item media dalam album, tambahkan kolom albumId
ke
permintaan penelusuran Anda. Untuk informasi selengkapnya tentang albumId
, lihat Mencantumkan
album dan Mencantumkan album bersama. Jika albumId
tidak valid, error Bad Request
akan ditampilkan. Jika ID valid,
tetapi album tidak ada untuk pengguna yang diautentikasi, error Not Found
akan ditampilkan. Untuk mengetahui detail selengkapnya tentang penanganan error,lihat Tips
performa dan Praktik
terbaik.
REST
Berikut adalah contoh permintaan:
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
"albumId": "album-id"
}
Permintaan POST menampilkan respons berikut:
{ "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 }
Respons berisi nextPageToken
dan daftar item media. Tidak seperti saat
mencantumkan konten koleksi, item media ditampilkan berdasarkan urutannya dalam
album. Untuk detail selengkapnya, lihat
mediaItems
dan Penomoran halaman. Pengguna dapat mengedit pesanan di
antarmuka Google Foto.
Jika albumId
disetel, Anda tidak dapat menerapkan filter saat mencantumkan konten album.
Tindakan tersebut akan menghasilkan error Bad Request
.
Mencantumkan album bersama
Anda dapat mengambil daftar semua album yang telah dibagikan pengguna atau yang telah dibagikan dengan pengguna. Fitur ini mirip dengan tab Berbagi di aplikasi Google Foto.
Album bersama yang telah ditambahkan pengguna ke galeri Google Foto mereka juga ditampilkan di panggilan album listingan. Lakukan panggilan berikut untuk mencantumkan album bersama melalui Library API:
REST
Berikut adalah contoh permintaan:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums
Permintaan tersebut menampilkan hasil berikut:
{ "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 }
Daftar album disertakan dalam sharedAlbums
. Untuk informasi selengkapnya, lihat
Mencantumkan album. Respons juga berisi nextPageToken
.
Untuk informasi selengkapnya, lihat Penomoran halaman.
Album yang telah dibuat dan dibagikan oleh aplikasi Anda menyertakan properti shareInfo
tambahan. Untuk detail selengkapnya, lihat Berbagi
media.
Album yang dibuat oleh aplikasi listingan
Anda dapat mencantumkan album yang telah dibuat oleh aplikasi Anda dengan
excludeNonAppCreatedData
yang ditetapkan ke true
dalam panggilan berikut:
REST
Berikut adalah permintaan GET untuk mencantumkan semua album dari galeri Google Foto pengguna yang hanya dibuat oleh aplikasi Anda:
GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
Berikut adalah permintaan GET untuk mencantumkan semua album bersama dari galeri Google Foto pengguna yang dibuat hanya oleh aplikasi Anda:
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 }
Penomoran halaman untuk REST
Untuk meningkatkan performa, metode yang menampilkan sejumlah besar hasil (seperti
metode daftar) dapat memberi nomor halaman pada respons. Jumlah hasil maksimum di setiap
halaman diberikan oleh parameter pageSize
.
Untuk panggilan ke mediaItems:search
dan mediaItems:list
, ukuran halaman default adalah
25 item. Sebaiknya gunakan ukuran halaman ini karena mencapai keseimbangan antara
ukuran respons dan rasio pengisian. Ukuran halaman maksimum untuk permintaan daftar
dan penelusuran item media adalah 100 item.
Ukuran halaman default dan yang direkomendasikan saat mencantumkan album adalah 20 album, dengan maksimum 50 album.
Jika jumlah hasil yang tersedia lebih besar dari ukuran halaman, respons
akan menyertakan nextPageToken
, yang menunjukkan kepada aplikasi Anda bahwa ada
lebih banyak hasil yang akan diambil dari server.
Contoh
Anda harus menambahkan nextPageToken
ke permintaan berikutnya dalam parameter
pageToken
, seperti yang ditunjukkan dalam contoh berikut. Tentukan pageToken
bersama dengan parameter lain yang diperlukan untuk operasi, baik dalam isi permintaan, maupun sebagai parameter kueri.
Permintaan #1
{ "pageSize": "5", "filters": { … } }
Tanggapan #1
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
Permintaan #2
{ "pageSize": "5", "filters": { … }, "pageToken": "page-token" }
Tanggapan #2
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
Lanjutkan pola ini sampai tidak ada lagi objek nextPageToken
.
nextPageToken
hanya valid untuk permintaan yang sama. Jika ada parameter yang diubah, nextPageToken
yang telah digunakan sebelumnya tidak boleh digunakan dalam permintaan yang sama.