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 habis masa berlakunya. ID item media secara unik mengidentifikasi item media, seperti foto atau video dalam galeri pengguna.

Perlu diperhatikan bahwa aplikasi Anda tidak boleh meng-cache foto atau video pengguna dalam jangka waktu yang lama, tetapi bergantung pada kasus penggunaan, Anda dapat menyimpan atau menyimpan dalam cache ID item media selama 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 mengizinkan 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 library 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 dalam Google Foto.
baseUrl Digunakan untuk mengakses byte mentah. Untuk 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 ini akan mengarah ke item dalam album.

mimeType Jenis item media untuk memudahkan identifikasi jenis media (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, mask kolom 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 Berbagi 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. Tidak semua properti dapat ditampilkan. 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 READY untuk digunakan. baseUrl item media video tidak tersedia hingga video selesai 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 akan 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
}

Dapatkan beberapa item media

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

Permintaan tersebut menampilkan daftar MediaItemResults sesuai urutan ID item media yang diberikan dalam permintaan. Setiap hasil berisi MediaItem atau Status jika ada 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 menampilkan akses item media yang berhasil dan tidak berhasil. 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. URL dasar adalah string yang disertakan dalam respons saat Anda mencantumkan album atau mengakses item media. Class ini berlaku selama 60 menit dan memerlukan parameter tambahan karena tidak dapat digunakan apa adanya.

Berbagai URL dasar adalah:

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

URL dasar image

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

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 dalam aplikasi (sehingga gambar dapat diskalakan ke dimensi tersebut dengan tetap 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 ini 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

Parameter crop, c.

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

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

Contoh:

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

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

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

Deskripsi

Download, parameter 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 akan mendownload gambar beserta 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 dari mediaItem video, sambungkan baseUrl dengan parameter dv video download.

Parameter dv meminta versi video asli yang di-transcoding dan berkualitas tinggi. Parameter ini tidak kompatibel dengan parameter w dan h.

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

Sebelum menggunakan parameter ini, pastikan kolom mediaMetadata.status item media adalah READY. Jika tidak, apabila item media Anda belum selesai diproses, Anda mungkin akan 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 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 memiliki lebar persis 1280 px dan 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 motion.

Parameter
dv

Deskripsi

Untuk mengambil elemen video item media foto motion, gunakan parameter dv seperti yang Anda download dari URL dasar video.

w, h, c, dan d

Deskripsi

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