Mencantumkan konten galeri, album, dan item media

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 akan berbeda berdasarkan cakupan diminta oleh pengembang.

Cakupan photoslibrary.readonly memungkinkan akses ke semua item media di library pengguna. Cakupan photoslibrary.readonly.appcreateddata memungkinkan akses hanya untuk item media yang dibuat oleh aplikasi. Untuk informasi selengkapnya, lihat Cakupan otorisasi.

Ringkasan

Penggunaan API yang penting adalah untuk membuat daftar item media yang telah dicadangkan pengguna ke Google Foto. Item dalam album tertentu atau dari seluruh pengguna galeri foto (tampilan default di aplikasi Google Foto) dapat dicantumkan.

Anda dapat menggunakan filter untuk memilih foto yang cocok dengan tanggal, kategori konten, atau jenis media tertentu saat Anda mencantumkan item dari library pengguna. Fitur ini tidak didukung jika Anda mencantumkan item dari album.

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

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

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 dikembalikan memiliki ID yang bisa digunakan untuk mengambil konten seperti yang ditampilkan dalam Mencantumkan konten album. Ini 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 menampilkan foto sampul album ini. Untuk mengakses gambar sampul ini, gunakan coverPhotoBaseUrl. Anda tidak boleh menggunakan coverPhotoBaseUrl secara langsung tanpa yang menentukan tambahan parameter.

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 Membagikan media.

Album juga dapat memiliki tanda isWriteable untuk menunjukkan apakah Anda dapat membuat media item dalam album. Tanda ini ditetapkan secara default ke false jika tidak ditampilkan. Penting bergantung pada akses yang diberikan ke aplikasi Anda, termasuk hal berikut:

• Siapa yang membuat album.
• Apakah dibagikan atau tidak.
• Apa yang mencakup pengguna telah disetujui.

Tanda ini dapat berubah jika salah satu kriteria ini berubah. Untuk detail selengkapnya, lihat Buat album. Tujuan 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 placeholder default gambar.

Konten koleksi listingan

Anda dapat mencantumkan semua item media dari galeri Google Foto pengguna. Pengecualian tersebut tidak mencakup item yang diarsipkan dan dihapus. Anda dapat membuat daftar item media berdasarkan konten, tanggal, dan properti lainnya dengan mengajukan permohonan filter. Jika pengguna belum menambahkan item tersedia di tab Berbagi di Google Foto mereka ke library, item tersebut tidak 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 akan berisi daftar item media, yang diurutkan dari yang paling baru ke yang paling lama. Untuk mengetahui informasi selengkapnya, lihat mediaItems. Ini juga berisi nextPageToken, yang dijelaskan lebih detail di Penomoran halaman.

Mencantumkan konten album

Untuk mencantumkan semua item media dalam album, tambahkan kolom albumId ke permintaan penelusuran. Untuk informasi selengkapnya tentang albumId, lihat Listingan album dan Mencantumkan album bersama. Jika albumId tidak valid, error Bad Request akan ditampilkan. Jika tanda pengenal valid, tetapi album tersebut tidak ada untuk pengguna yang diautentikasi, maka error Not Found dikembalikan. Untuk detail selengkapnya terkait penanganan error,lihat Performa tips dan Terbaik praktik yang baik.

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

Mencantumkan album bersama

Anda dapat mengambil daftar semua album yang telah dibagikan pengguna atau yang telah dibagikan kepada pengguna. Ini mirip dengan tab {i>Share<i} di Aplikasi Google Foto.

Album bersama yang telah ditambahkan pengguna ke galeri Google Foto mereka juga ditampilkan dalam panggilan album listingan. Jadikan 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 di 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 shareInfo tambahan saat ini. Untuk detail selengkapnya, lihat Bagikan media.

Mencantumkan album yang dibuat aplikasi

Anda dapat mencantumkan album yang telah dibuat oleh aplikasi Anda menggunakan excludeNonAppCreatedData ditetapkan ke true dalam panggilan berikut:

• albums.list
• sharedAlbums.list

REST

Berikut adalah permintaan GET untuk mencantumkan semua album dari Galeri Google Foto 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 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 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.

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

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 ada parameter yang diubah, nextPageToken yang sebelumnya digunakan tidak boleh permintaan.

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