Mencantumkan dan mengambil item media

Setelah pengguna mengonfigurasi perangkat ambient dan memilih sumber media di Google Foto, aplikasi Anda dapat mencantumkan dan mengambil item media tersebut untuk ditampilkan.

Sebelum memulai

  • Periksa penyiapan perangkat: Pastikan Anda telah berhasil membuat dan mengonfigurasi perangkat untuk pengguna.
  • Memahami alur Ambient API: Tinjau Alur Ambient API untuk memahami keseluruhan proses, terutama langkah yang melibatkan polling untuk mediaSourcesSet.

Polling untuk mediaSourcesSet

Sebelum Anda dapat mencantumkan item media untuk perangkat, pengguna harus memilih foto yang ingin dibagikan dengan aplikasi Anda dalam aplikasi Google Foto. Aplikasi Anda harus melakukan polling pada perangkat untuk menentukan kapan pilihan ini telah dibuat.

Panggil metode devices.get secara berkala untuk deviceId tertentu. Pantau kolom mediaSourcesSet dalam respons AmbientDevice. Awalnya, nilainya adalah false. Setelah pengguna berhasil memilih sumber media, kolom ini akan berubah menjadi true.

Respons AmbientDevice mencakup pollingConfig dengan pollInterval yang harus Anda gunakan sebagai panduan untuk frekuensi polling.

Mencantumkan Item Media

Setelah mediaSourcesSet menjadi true untuk perangkat, Anda dapat mulai mengambil item media yang dipilih oleh pengguna.

  1. Gunakan endpoint mediaItems.list: Buat permintaan GET ke https://photosambient.googleapis.com/v1/mediaItems, dengan memberikan deviceId di jalur.

  2. Menangani penomoran halaman (jika perlu): Respons dapat diberi nomor halaman. Gunakan parameter pageSize untuk menentukan jumlah maksimum item yang akan ditampilkan, dan pageToken dari respons sebelumnya untuk mengambil halaman hasil berikutnya.

  3. Memproses item media: Respons akan berisi array objek AmbientMediaItem, yang masing-masing mewakili item media yang dipilih. Objek ini mencakup detail penting seperti:

    • id: ID unik untuk item media.
    • creationTime: Stempel waktu saat item media dibuat.
    • mediaFile: Objek yang berisi detail untuk mengakses konten sebenarnya.

Kolom mediaFile mencakup baseUrl. baseUrl ini adalah yang akan Anda gunakan untuk membuat URL guna mengakses konten item media dalam berbagai resolusi atau format.

URL Dasar

URL dasar di Google Photos API memberikan akses ke byte mentah item media, sehingga aplikasi Anda dapat mendownload atau menampilkannya. URL ini disertakan dalam respons saat mencantumkan album (Library API) atau mengakses item media (baik Library API maupun Picker API). Ingat, URL dasar memerlukan parameter tambahan agar berfungsi dengan benar.

Untuk Picker API:

Semua objek PickedMediaItem.mediaFile mencakup baseUrl.

URL dasar tetap aktif selama 60 menit, tetapi dapat berakhir lebih cepat jika pengguna mencabut izin aplikasi Anda melalui setelan Akun Google mereka.

Untuk Library API:

URL dasar tetap aktif selama 60 menit.

Berbagai URL dasar adalah:

  • baseUrl: Mengakses foto secara langsung, thumbnail untuk video, atau mendownload byte video.
  • coverPhotoBaseUrl: Mengakses foto sampul album secara langsung.
  • profilePictureBaseUrl: Mengakses foto profil pemilik mediaItem secara langsung.

URL dasar gambar

Berikut adalah daftar opsi yang dapat Anda gunakan dengan URL dasar gambar:

Parameter
w, h

Deskripsi

Parameter lebar, w, dan tinggi, h.

Untuk mengakses item media gambar, seperti foto atau thumbnail untuk video, Anda harus menentukan dimensi yang akan ditampilkan di aplikasi (sehingga gambar dapat diskalakan ke dimensi ini sambil mempertahankan rasio aspek). Untuk melakukannya, gabungkan URL dasar dengan dimensi yang Anda inginkan seperti yang ditunjukkan dalam contoh.

Contoh:

base-url=wmax-width-hmax-height

Berikut adalah contoh untuk menampilkan item media yang tidak lebih lebar dari 2048 piksel dan tidak lebih tinggi dari 1024 piksel:

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

Deskripsi

Pemangkasan, parameter c.

Jika Anda ingin memangkas gambar ke dimensi lebar dan tinggi yang tepat yang telah Anda tentukan, gabungkan URL dasar dengan parameter -c opsional beserta parameter w dan h wajib.

Ukuran (dalam piksel) harus berada dalam rentang [1, 16383]. Jika lebar atau tinggi gambar melebihi ukuran yang diminta, gambar akan diperkecil dan dipangkas (dengan mempertahankan rasio aspek).

Contoh:

base-url=wmax-width-hmax-height-c

Dalam contoh ini, aplikasi menampilkan item media yang berukuran tepat 256 px lebar x 256 px tinggi, seperti thumbnail:

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

Deskripsi

Download, parameter d.

Jika Anda ingin mendownload gambar dengan mempertahankan semua metadata Exif kecuali metadata lokasi, gabungkan URL dasar dengan parameter d.

Contoh:

base-url=d

Dalam contoh ini, aplikasi mendownload gambar dengan semua metadata kecuali metadata lokasi:

https://lh3.googleusercontent.com/p/Az....XabC=d

URL dasar video

Berikut adalah daftar opsi yang dapat Anda gunakan dengan URL dasar video:

Parameter
dv

Deskripsi

Untuk mengakses byte video mediaItem, gabungkan baseUrl dengan video yang didownload, dv parameter.

Parameter dv meminta versi video asli yang ditranskode dan berkualitas tinggi. Parameter tidak kompatibel dengan parameter w dan h.

URL dasar untuk download video dapat memerlukan waktu hingga beberapa detik untuk menampilkan byte.

Sebelum menggunakan parameter ini, periksa apakah kolom mediaMetadata.status item media adalah READY. Jika tidak, jika item media Anda belum selesai diproses, Anda mungkin menerima error.

Contoh:

base-url=dv

Contoh berikut menunjukkan cara mendownload byte video:

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h, c, dan d

Deskripsi

Untuk mengakses thumbnail video, gunakan salah satu parameter URL dasar gambar.

Secara default, semua thumbnail video menyertakan overlay tombol putar. Lihat parameter -no untuk menghapus overlay ini.

Contoh:

Lihat tabel URL dasar gambar untuk mengetahui contohnya.
no

Deskripsi

Overlay hapus thumbnail, parameter no.

Jika Anda ingin mengambil thumbnail video tanpa overlay tombol pemutaran, gabungkan URL dasar dengan parameter no.

Parameter no harus digunakan dengan setidaknya salah satu parameter URL dasar gambar.

Contoh:

base-url=wmax-width-hmax-height-no

Contoh berikut menampilkan thumbnail video yang lebarnya persis 1280 px dan tingginya 720 px, serta tidak menyertakan overlay tombol pemutaran:

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

URL dasar foto motion

Foto motion berisi elemen foto dan video. Anda dapat menggunakan parameter dari URL dasar gambar atau URL dasar video untuk permintaan foto bergerak baseUrl.

Parameter
dv

Deskripsi

Untuk mengambil elemen video item media foto bergerak, gunakan parameter dv seperti yang Anda lakukan untuk mendownload dari URL dasar video.
w, h, c, dan d

Deskripsi

Untuk mengambil elemen foto dari item media foto bergerak, gunakan format untuk URL dasar gambar.

Kebijakan dan Pemfilteran Konten

Google Foto menerapkan pemfilteran konten standar secara default untuk gambar dan video yang ditampilkan di perangkat bersama seperti TV atau layar digital. Filter ini dirancang untuk mengoptimalkan pengalaman menonton dengan mengecualikan konten seperti:

  • Gambar fungsional (misalnya, screenshot, dokumen, tanda terima).
  • Gambar yang mungkin dirender dengan buruk di layar besar (misalnya, resolusi sangat rendah, buram, terlalu banyak butiran).
  • Konten yang diidentifikasi sebagai sangat pribadi atau sensitif, yang mungkin tidak dimaksudkan untuk ditampilkan secara umum di lingkungan bersama.

Semua pemfilteran konten dilakukan secara otomatis. Untuk memberi pengguna lebih banyak kontrol atas konten yang ditampilkan, Anda dapat mengizinkan mereka memilih dan memperbarui sumber media yang digunakan untuk tampilan ambient secara manual.

Langkah Berikutnya

  • Aplikasi Contoh: Aplikasi contoh kami mencakup contoh pencantuman dan pengambilan item media. Lihat fungsi checkMediaSourcesSet dan fetch_media_item_list untuk mengetahui info selengkapnya.
  • Dokumentasi Referensi: Tinjau dokumen referensi item media yang komprehensif untuk mengetahui informasi mendetail tentang semua metode yang tersedia, parameter permintaan dan respons, serta kode error.