Cakupan otorisasi yang diperlukan
Google Photos Library API berisi beberapa cakupan yang digunakan untuk mengakses item media dan album. Item media yang ditampilkan dari berbagai panggilan berbeda-beda berdasarkan cakupan yang telah diminta oleh developer.
Cakupan photoslibrary.readonly
memungkinkan akses ke semua item media di
library pengguna. Cakupan photoslibrary.readonly.appcreateddata
hanya mengizinkan akses
ke item media yang dibuat oleh aplikasi. Untuk mengetahui informasi selengkapnya, lihat
Cakupan otorisasi.
Ringkasan
Penggunaan penting API ini adalah untuk mencantumkan item media yang telah dicadangkan pengguna ke Google Foto. Item dalam 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 mendeskripsikan 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 konten album seperti yang ditunjukkan dalam Menampilkan konten album. Kolom 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 akan 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 di album. Flag ini secara default disetel ke false
jika tidak ditampilkan. 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 detail selengkapnya, lihat
Membuat album. Respons
juga berisi nextPageToken
. Untuk informasi selengkapnya, lihat
Penomoran halaman.
Respons untuk album kosong bervariasi, karena mediaItemsCount
dan
coverPhotoMediaItemId
ditetapkan ke 0 secara default dan dihilangkan dari respons
REST. Perhatikan juga bahwa coverPhotoBaseUrl
mengarah ke gambar placeholder
default.
Konten library listingan
Anda dapat mencantumkan semua item media dari galeri Google Foto pengguna. Tidak termasuk item yang diarsipkan dan dihapus. Anda dapat membuat daftar item media berdasarkan konten, tanggal, dan properti lainnya dengan menerapkan filter. Jika pengguna belum menambahkan item yang tersedia di tab Berbagi di Google Foto ke library mereka, 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 menampilkan 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 hingga yang paling lama.
Untuk mengetahui informasi selengkapnya, lihat
mediaItems
. Class ini juga
berisi nextPageToken
, yang dijelaskan secara lebih mendetail di
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 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 mengembalikan 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 library, item media ditampilkan berdasarkan urutannya dalam
album. Untuk detail selengkapnya, lihat
mediaItems
dan Penomoran halaman. Pengguna dapat mengedit urutan 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. Ini serupa 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 Membagikan
media.
Membuat daftar album yang dibuat oleh aplikasi
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 dibuat hanya 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 hasil dalam jumlah besar (seperti metode daftar) dapat memberi nomor halaman 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 dapat menyeimbangkan
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 atau 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 hingga tidak ada lagi objek nextPageToken
.
nextPageToken
hanya valid untuk permintaan yang sama. Jika parameter
diubah, nextPageToken
yang digunakan sebelumnya tidak boleh digunakan dalam permintaan
yang sama.