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