Mengakses item media

Setelah melakukan panggilan untuk mencantumkan konten galeri foto atau album, bukan menyimpan item media yang ditampilkan, aplikasi Anda harus menyimpan ID item media. Hal ini karena konten item media dapat berubah dan setelah waktu tertentu, URL yang disertakan dalam respons akan berakhir masa berlakunya. ID item media mengidentifikasi item media secara unik, seperti foto atau video di dalam library pengguna.

Perhatikan bahwa aplikasi Anda tidak boleh menyimpan foto atau video pengguna dalam cache selama berlangsungnya waktu yang lama, tetapi bergantung pada kasus penggunaan, Anda dapat menyimpan atau menyimpan dalam cache ID item media selama sepanjang diperlukan. Anda juga harus memperhatikan bahwa akses ke data pengguna diatur oleh kewajiban privasi.

Cakupan otorisasi yang diperlukan

Untuk mengakses item media, aplikasi Anda harus meminta setidaknya salah satu cakupan otorisasi berikut. Akses ke item media yang ditampilkan dalam respons bergantung pada cakupan yang telah Anda minta.

  • photoslibrary.readonly memungkinkan akses ke semua item media di library pengguna
  • photoslibrary.readonly.appcreateddata hanya mengizinkan akses ke item media yang dibuat oleh aplikasi

Item media

mediaItem adalah representasi media seperti foto atau video yang telah diupload ke koleksi Google Foto. Ini adalah objek tingkat teratas dan propertinya dapat berbeda berdasarkan jenis media yang mendasarinya.

Tabel berikut mencantumkan properti mediaItem:

Properti
id ID permanen dan stabil yang digunakan untuk mengidentifikasi objek.
description Deskripsi item media seperti yang terlihat di dalam Google Foto.
baseUrl Digunakan untuk mengakses byte mentah. Untuk mengetahui informasi selengkapnya, lihat URL Dasar.
productUrl

Link ke gambar di dalam Google Foto. Link ini tidak dapat dibuka oleh developer, hanya oleh pengguna. URL mengarah ke item media di library. Jika URL diambil dari penelusuran album, URL tersebut akan mengarah ke item dalam album.

mimeType Jenis item media untuk membantu mengidentifikasi jenis media dengan mudah (misalnya: image/jpg).
filename Nama file item media yang ditampilkan kepada pengguna di aplikasi Google Foto (dalam bagian info item).
mediaMetadata Bervariasi bergantung pada jenis media yang mendasarinya, seperti, photo atau video. Untuk mengurangi payload, field mask dapat digunakan.
contributorInfo

Kolom ini hanya diisi jika item media berada dalam album bersama yang dibuat oleh aplikasi ini dan pengguna telah memberikan cakupan photoslibrary.sharing.

Berisi informasi tentang kontributor yang menambahkan item media ini. Untuk mengetahui detail selengkapnya, lihat Membagikan media.

Mendapatkan item media

Untuk mengambil item media, panggil mediaItems.get menggunakan mediaItemId. Permintaan menampilkan satu item media.

mediaItem berisi properti, seperti ID, deskripsi, dan URL. Informasi tambahan dalam photo atau video didasarkan pada metadata dalam file. Mungkin tidak semua properti ada. ContributorInfo berisi metadata untuk item yang merupakan bagian dari album bersama. Kolom ini hanya disertakan saat mencantumkan konten album bersama tempat pengguna telah memberikan cakupan otorisasi photoslibrary.sharing.

Jika item media adalah video, file video harus diproses terlebih dahulu. mediaItem berisi kolom status di dalam mediaMetadata yang menjelaskan status pemrosesan file video. File yang baru diupload akan menampilkan videoProcessingStatus dengan nilai PROCESSING terlebih dahulu, sebelum menjadi READY untuk digunakan. baseUrl item media video tidak tersedia hingga video diproses.

REST

Berikut adalah permintaan GET:

GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

Respons untuk item media foto akan terlihat seperti ini. Properti foto berisi metadata untuk item foto.

{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "photo": {
       "cameraMake": "make-of-the-camera",
       "cameraModel": "model-of-the-camera",
       "focalLength": "focal-length-of-the-camera-lens",
       "apertureFNumber": "aperture-f-number-of-the-camera-lens",
       "isoEquivalent": "iso-of-the-camera",
       "exposureTime": "exposure-time-of-the-camera-aperture"
    }
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}

Respons untuk item media video terlihat seperti ini. Properti video berisi metadata untuk item video.

{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "video": {
     "cameraMake": "make-of-the-camera",
     "cameraModel": "model-of-the-camera",
     "fps": "frame-rate-of-the-video",
     "status": "READY"
    },
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}

Java

Properti foto berisi metadata untuk item foto.

try {
  // Get a media item using its ID
  String mediaItemId = "...";
  MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
  // Get some properties from the retrieved media item
  String id = item.getId();
  String description = item.getDescription();
  String baseUrl = item.getBaseUrl();
  String productUrl = item.getProductUrl();
  // ...
  if (item.hasMediaMetadata()) {
    // The media item contains additional metadata, such as the height and width
    MediaMetadata metadata = item.getMediaMetadata();
    long height = metadata.getHeight();
    long width = metadata.getWidth();
    Timestamp creationTime = metadata.getCreationTime();
    // ...
    if (metadata.hasPhoto()) {
      // This media item is a photo and has additional photo metadata
      Photo photoMetadata = metadata.getPhoto();
      String cameraMake = photoMetadata.getCameraMake();
      String cameraModel = photoMetadata.getCameraModel();
      float aperture = photoMetadata.getApertureFNumber();
      int isoEquivalent = photoMetadata.getIsoEquivalent();
      // ...
    }
  }
  if (item.hasContributorInfo()) {
    // A user has contributed this media item  to a shared album
    ContributorInfo contributorInfo = item.getContributorInfo();
    String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
    String displayName = contributorInfo.getDisplayName();
  }
} catch (ApiException e) {
  // Handle error
}

Properti video berisi metadata untuk item video.

try {
  // Get a media item using its ID
  String mediaItemId = "...";
  MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
  // Get some properties from the retrieved media item
  String id = item.getId();
  String description = item.getDescription();
  String baseUrl = item.getBaseUrl();
  String productUrl = item.getProductUrl();
  // ...
  if (item.hasMediaMetadata()) {
    // The media item contains additional metadata, such as the height and width
    MediaMetadata metadata = item.getMediaMetadata();
    long height = metadata.getHeight();
    long width = metadata.getWidth();
    Timestamp creationTime = metadata.getCreationTime();
    // ...

    if (metadata.hasVideo()) {
      // This media item is a video and has additional video metadata
      Video videoMetadata = metadata.getVideo();
      VideoProcessingStatus status = videoMetadata.getStatus();
      if (status.equals(VideoProcessingStatus.READY)) {
        // This video media item has been processed
        String cameraMake = videoMetadata.getCameraMake();
        String cameraModel = videoMetadata.getCameraModel();
        double fps = videoMetadata.getFps();
        // ...
      }
    }
  }

  if (item.hasContributorInfo()) {
    // A user has contributed this media item  to a shared album
    ContributorInfo contributorInfo = item.getContributorInfo();
    String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
    String displayName = contributorInfo.getDisplayName();
  }
} catch (ApiException e) {
  // Handle error
}

PHP

Properti foto berisi metadata untuk item foto.

try {
    // Get a media item using its ID
    $mediaItemId = "...";
    $item = $photosLibraryClient->getMediaItem($mediaItemId);
    // Get some properties from the retrieved media item
    $id = $item->getId();
    $description = $item->getDescription();
    $baseUrl = $item->getBaseUrl();
    $productUrl = $item->getProductUrl();
    // ...
    $metadata = $item->getMediaMetadata();
    if (!is_null($metadata)) {
        // The media item contains additional metadata, such as the height and width
        $height = $metadata->getHeight();
        $width = $metadata->getWidth();
        $creationTime = $metadata->getCreationTime();
        // ...
        $photoMetadata = $metadata->getPhoto();
        if (!is_null($photoMetadata)) {
            // This media item is a photo and has additional photo metadata
            $cameraMake = $photoMetadata->getCameraMake();
            $cameraModel = $photoMetadata->getCameraModel();
            $aperture = $photoMetadata->getApertureFNumber();
            $isoEquivalent = $photoMetadata->getIsoEquivalent();
            // ...
        }
    }
    $contributorInfo = $item->getContributorInfo();
    if (!is_null($contributorInfo)) {
        // A user has contributed this media item to a shared album
        $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
        $displayName = $contributorInfo->getDisplayName();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Properti video berisi metadata untuk item video.

  try {
    // Get a media item using its ID
    $mediaItemId = "...";
    $item = $photosLibraryClient->getMediaItem($mediaItemId);
    // Get some properties from the retrieved media item
    $id = $item->getId();
    $description = $item->getDescription();
    $baseUrl = $item->getBaseUrl();
    $productUrl = $item->getProductUrl();
    // ...
    $metadata = $item->getMediaMetadata();
    if (!is_null($metadata)) {
        // The media item contains additional metadata, such as the height and width
        $height = $metadata->getHeight();
        $width = $metadata->getWidth();
        $creationTime = $metadata->getCreationTime();
        // ...
        $videoMetadata = $metadata->getVideo();
        if (!is_null($videoMetadata)) {
            // This media item is a video and has additional video metadata
            if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) {
            // This video media item has been processed
                $cameraMake = $videoMetadata->getCameraMake();
                $cameraModel = $videoMetadata->getCameraModel();
                $fps = $videoMetadata->getFps();
                // ...
            }
        }
    }
    $contributorInfo = $item->getContributorInfo();
    if (!is_null($contributorInfo)) {
        // A user has contributed this media item to a shared album
        $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
        $displayName = $contributorInfo->getDisplayName();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Mendapatkan beberapa item media

Untuk mengambil beberapa item media berdasarkan ID-nya, panggil mediaItems.batchGet menggunakan mediaItemId.

Permintaan menampilkan daftar MediaItemResults sesuai urutan ID item media yang diberikan dalam permintaan. Setiap hasil berisi MediaItem atau Status jika terjadi error.

Jumlah maksimum item media yang dapat Anda minta dalam satu panggilan adalah 50. Daftar item media tidak boleh berisi ID duplikat dan tidak boleh kosong.

REST

Berikut adalah permintaan GET yang menunjukkan akses yang berhasil dan gagal terhadap item media. Tentukan setiap ID item media sebagai parameter kueri mediaItemIds baru sebagai bagian dari permintaan:

GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

Permintaan GET menampilkan respons berikut:

{
  "mediaItemResults": [
    {
      "mediaItem": {
        "id": "media-item-id",
        ...
      }
    },
    {
      "mediaItem": {
        "id": "another-media-item-id",
        ...
      }
    },
    {
      "status": {
        "code": 3,
        "message": "Invalid media item ID."
      }
    }
  ]
}

Java

try {
  // List of media item IDs to retrieve
  List<String> mediaItemIds = Arrays
      .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID");

  // Get a list of media items using their IDs
  BatchGetMediaItemsResponse response = photosLibraryClient
      .batchGetMediaItems(mediaItemIds);

  // Loop over each result
  for (MediaItemResult result : response.getMediaItemResultsList()) {

    // Each MediaItemresult contains a status and a media item
    if (result.hasMediaItem()) {
      // The media item was successfully retrieved, get some properties
      MediaItem item = result.getMediaItem();
      String id = item.getId();
      // ...
    } else {
      // If the media item is not set, an error occurred and the item could not be loaded
      // Check the status and handle the error
      Status status = result.getStatus();
      // ...
    }

  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {

    // List of media item IDs to retrieve
    $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"];

    // Get a list of media items using their IDs
    $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds);

    // Loop over each result
    foreach ($response->getMediaItemResults() as $itemResult) {

        // Each MediaItemresult contains a status and a media item
        $mediaItem = $itemResult->getMediaItem();

        if(!is_null($mediaItem)){
            // The media item was successfully retrieved, get some properties
            $id = $mediaItem->getId();
            // ...
        } else {
            // If the media item is null, an error occurred and the item could not be loaded
        }
    }

} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

URL Dasar

URL dasar dalam Google Photos Library API memungkinkan Anda mengakses byte item media. Dengan menggunakan berbagai URL dasar, aplikasi Anda dapat mendownload item media atau menampilkan item media dalam aplikasi Anda. URL dasar adalah string yang disertakan dalam respons saat Anda mencantumkan album atau mengakses item media. Token ini berlaku selama 60 menit dan memerlukan parameter tambahan karena tidak dapat digunakan begitu saja.

Berbagai URL dasarnya adalah:

  • baseUrl: Mengakses foto, thumbnail untuk video, atau mendownload byte video secara langsung.
  • coverPhotoBaseUrl: Mengakses langsung foto sampul untuk album.
  • 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 ingin ditampilkan di aplikasi (sehingga gambar dapat diskalakan ke dimensi ini sekaligus mempertahankan rasio aspek). Untuk melakukannya, gabungkan URL dasar dengan dimensi yang diperlukan 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 diskalakan ke bawah dan dipangkas (mempertahankan rasio aspek).

Contoh:

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

Dalam contoh ini, aplikasi menampilkan item media dengan lebar 256 px dan tinggi 256 px, seperti thumbnail:

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

Deskripsi

Parameter download, d.

Jika Anda ingin mendownload gambar yang 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 daftar opsi yang dapat Anda gunakan dengan URL basis video:

Parameter
dv

Deskripsi

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

Parameter dv meminta versi video asli yang ditranskode dan berkualitas tinggi. Parameter ini 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, pastikan 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 pemutaran. Lihat parameter -no untuk menghapus overlay ini.

Contoh:

Lihat tabel URL dasar gambar untuk mengetahui contohnya.
no

Deskripsi

Hapus overlay 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 dengan lebar 1.280 px kali tinggi 720 px dan 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 baseUrl foto gerakan.

Parameter
dv

Deskripsi

Untuk mengambil elemen video dari item media foto motion, gunakan parameter dv seperti yang akan Anda download dari URL dasar video.
w, h, c, dan d

Deskripsi

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