Membuat daftar item media dan album yang dibuat aplikasi

Cakupan otorisasi yang diperlukan

Mencantumkan konten yang dibuat aplikasi memerlukan cakupan photoslibrary.readonly.appcreateddata. Untuk informasi selengkapnya tentang cakupan, lihat Cakupan otorisasi.

Ringkasan

Library API memungkinkan Anda menampilkan daftar dan mengakses item media yang telah dibuat aplikasi.

Beberapa fitur utama listingan item media meliputi:

• Mencantumkan item media dari album tertentu yang dibuat oleh aplikasi atau seluruh library yang dibuat aplikasi

• Terapkan filter (tanggal, kategori konten, jenis media) saat membuat daftar untuk mempersempit hasil

  Catatan: Filter tidak didukung saat Anda mencantumkan item dari album.

• Ambil objek mediaItem dengan detail penting seperti link langsung dan metadata.

Mencantumkan konten koleksi dan 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 relevan lainnya. Untuk informasi selengkapnya, lihat Mengakses item media dan mediaItems.

Perhatian: Jangan menyimpan foto dan video pengguna dalam cache. Sebagai gantinya, simpan item media id dan minta detailnya lagi saat Anda membutuhkannya. Gambar dapat berubah, dan akses langsung melalui baseUrl akan berakhir setelah 60 menit. Untuk mengetahui informasi selengkapnya, lihat Mengakses item media.

Mencantumkan album yang dibuat aplikasi

Anda dapat mencantumkan album yang telah dibuat oleh aplikasi 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 ditampilkan memiliki ID yang dapat digunakan untuk mengambil konten album seperti yang ditunjukkan dalam Daftar isi album. Informasi 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.

Responsnya juga berisi nextPageToken. Untuk mengetahui informasi selengkapnya, lihat Penautan.

Respons untuk album kosong bervariasi, 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 yang dibuat aplikasi

Anda dapat mencantumkan semua item media dari galeri Google Foto pengguna yang dibuat oleh aplikasi Anda. Hal ini tidak termasuk item yang diarsipkan dan dihapus. Anda dapat mencantumkan item media berdasarkan konten, tanggal, dan properti lainnya dengan menerapkan filter.

Untuk mencantumkan 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. Header ini juga berisi nextPageToken, yang dijelaskan secara lebih mendetail di Penautan.

Mencantumkan konten album

Untuk mencantumkan semua item media dalam album, tambahkan kolom albumId ke permintaan penelusuran Anda. Untuk mengetahui informasi selengkapnya tentang albumId, lihat Mencantumkan album. 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"
}

Respons berisi nextPageToken dan daftar item media. Tidak seperti saat mencantumkan konten library, item media ditampilkan sesuai urutan di album. Untuk mengetahui detail selengkapnya, lihat mediaItems dan Penautan. Pengguna dapat mengedit pesanan di antarmuka Google Foto.

Jika albumId ditetapkan, Anda tidak dapat menerapkan filter saat mencantumkan konten album. Tindakan ini akan menghasilkan error Bad Request.

Penomoran halaman untuk REST

Untuk meningkatkan performa, metode yang menampilkan hasil dalam jumlah besar (seperti metode daftar) dapat memberi nomor halaman pada respons. Jumlah maksimum hasil di setiap halaman diberikan oleh parameter pageSize.

Untuk panggilan ke mediaItems.search dan mediaItems.list, ukuran halaman default adalah 25 item. Kami merekomendasikan ukuran halaman ini karena memberikan keseimbangan antara ukuran respons dan rasio pengisian. Ukuran halaman maksimum untuk permintaan penelusuran dan daftar 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.

Catatan: Parameter pageSize adalah maksimum — hasil yang ditampilkan mungkin lebih sedikit daripada yang diminta.

Contoh

Anda harus menambahkan nextPageToken ke permintaan berikutnya dalam parameter pageToken, seperti yang ditunjukkan dalam contoh berikut. Tentukan pageToken bersama parameter lain yang diperlukan untuk operasi, baik dalam isi permintaan, maupun sebagai parameter kueri.

Permintaan #1

{
  "pageSize": "5",
  "filters": { … }
}

Respons #1

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

Permintaan #2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

Respons #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.

Catatan: Keberadaan nextPageToken adalah satu-satunya indikator yang menunjukkan apakah ada lebih banyak hasil yang akan diambil dari server atau tidak. Jangan hitung jumlah hasil untuk menentukan apakah Anda harus menggunakan nextPageToken. Permintaan dapat menampilkan lebih sedikit hasil daripada yang diminta dalam ukuran halaman. Jika nextPageToken ada, Anda dapat mengirim permintaan untuk hasil lainnya setelah permintaan awal.