Cakupan otorisasi yang diperlukan
Untuk membuat listingan konten yang dibuat aplikasi, Anda memerlukan photoslibrary.readonly.appcreateddata
ruang lingkup proyek. Untuk informasi selengkapnya tentang cakupan, lihat Otorisasi
cakupan kami.
Ringkasan
Library API memungkinkan Anda membuat daftar dan mengakses item media yang dibuat.
Beberapa fitur utama listingan item media meliputi:
- Mencantumkan item media dari album tertentu yang dibuat oleh aplikasi atau seluruh aplikasi yang dibuat perpustakaan
Menerapkan filter (tanggal, kategori konten, media ) saat menampilkan listingan untuk mempersempit hasil
Mengambil objek
mediaItem
dengan detail penting seperti tautan langsung dan {i>metadata<i}.
Mencantumkan konten galeri dan album akan menampilkan daftar item media.
Pengayaan yang merupakan bagian dari album
tidak disertakan. Item media mendeskripsikan foto, video, atau media lainnya. J
mediaItem
menyertakan link langsung ke item, sebuah link ke item dalam
Google Foto, dan metadata relevan lainnya. Untuk informasi selengkapnya, lihat
Mengakses item media dan
mediaItems
Mencantumkan album yang dibuat aplikasi
Anda dapat mencantumkan album yang telah dibuat oleh aplikasi Anda 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" }
Setiap album yang dikembalikan memiliki ID yang bisa digunakan untuk mengambil konten seperti yang ditampilkan dalam Daftar isi album. Anda juga meliputi judul dan jumlah item media yang ada di dalamnya.
productUrl
mengarah ke album di Google Foto yang dapat berupa
dibuka oleh pengguna.
coverPhotoMediaItemId
berisi item media
ID yang mewakili sampul
foto album ini. Untuk mengakses gambar sampul ini, gunakan coverPhotoBaseUrl
.
Anda tidak boleh menggunakan coverPhotoBaseUrl
secara langsung tanpa menentukan
parameter tambahan.
Respons juga berisi nextPageToken
. Untuk informasi selengkapnya, lihat
Penomoran halaman.
Respons untuk album kosong bervariasi, mediaItemsCount
dan
coverPhotoMediaItemId
ditetapkan ke 0 secara default dan dihilangkan dari REST
yang dihasilkan. Perhatikan juga bahwa coverPhotoBaseUrl
mengarah ke gambar placeholder
default.
Mencantumkan konten library yang dibuat aplikasi
Anda dapat mencantumkan semua item media dari galeri Google Foto pengguna yang dibuat oleh aplikasi Anda.. Tidak termasuk item yang diarsipkan dan dihapus. Anda dapat menampilkan daftar item media berdasarkan konten, tanggal, dan propertinya dengan menerapkan filter.
Untuk menampilkan daftar 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" }
Respons berisi daftar item media, yang diurutkan dari yang paling baru hingga yang paling lama.
Untuk mengetahui informasi selengkapnya, lihat
mediaItems
. Anda juga
berisi nextPageToken
, yang dijelaskan lebih detail di
Penomoran halaman.
Daftar isi album
Untuk mencantumkan semua item media dalam album, tambahkan kolom albumId
ke
permintaan penelusuran. Untuk informasi selengkapnya tentang albumId
, lihat Listingan
album. Jika albumId
tidak valid, error Bad Request
dikembalikan. Jika ID valid, tetapi album tidak ada untuk pengguna yang diautentikasi, error Not Found
akan ditampilkan. Untuk detail selengkapnya terkait error
penanganan,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" }
Respons akan berisi nextPageToken
dan daftar item media. Tidak seperti saat
menampilkan daftar konten pustaka, item media dikembalikan sesuai urutannya
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
.
Penomoran halaman untuk REST
Untuk meningkatkan performa, metode yang menampilkan hasil dalam jumlah besar (seperti
daftar) dapat memberi nomor 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 akan mencapai keseimbangan antara
ukuran respons dan rasio pengisian. Ukuran halaman maksimum untuk item media
permintaan penelusuran dan daftar 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
menyertakan nextPageToken
, yang menunjukkan pada aplikasi Anda bahwa ada
lebih banyak hasil yang bisa
diambil dari server.
Contoh
Anda harus menambahkan nextPageToken
ke permintaan berikutnya dalam parameter
pageToken
, seperti yang ditunjukkan dalam contoh berikut. Tentukan pageToken
bersama-sama
dengan parameter lain yang diperlukan untuk operasi, baik dalam isi
permintaan, atau sebagai parameter kueri.
Permintaan #1
{ "pageSize": "5", "filters": { … } }
Respons #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 parameter apa pun
berubah, nextPageToken
yang digunakan sebelumnya tidak boleh digunakan dalam permintaan
yang sama.