Mengakses item media

Setelah melakukan panggilan ke mencantumkan konten galeri foto atau album, sebagai ganti menyimpan item media yang dikembalikan, aplikasi Anda harus menyimpan ID item media. Hal ini karena konten item media mungkin berubah dan setelah waktu tertentu, URL yang disertakan dalam respons akan kedaluwarsa. Tujuan ID item media secara unik mengidentifikasi item media, seperti foto atau video di dalam library pengguna.

Perlu diperhatikan bahwa aplikasi Anda tidak boleh meng-cache foto atau video pengguna untuk waktu yang lama jangka waktu tertentu, namun bergantung pada kasus penggunaan, Anda dapat menyimpan atau cache ID item media sebagai panjang selanjutnya yang diperlukan. Anda juga harus memperhatikan bahwa akses ke akses data diatur oleh privasi kewajiban tersebut.

Cakupan otorisasi yang diperlukan

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

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

Item media

J mediaItem adalah representasi media seperti foto atau video yang telah diupload ke galeri Google Foto. Objek tersebut adalah objek tingkat atas dan propertinya bisa 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 informasi selengkapnya, lihat URL Dasar.
productUrl

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

mimeType Jenis item media untuk membantu mengidentifikasi jenis media dengan mudah (contoh: image/jpg).
filename Nama file item media yang ditampilkan kepada pengguna di Google Foto (di 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 photoslibrary.sharing cakupan.

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

Dapatkan item media

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

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

Jika item media adalah video, file video harus diproses terlebih dahulu. Tujuan 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 nilai tersebut adalah 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. 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. 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 tersebut akan 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 diminta 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 tidak berhasil dari item media. Tentukan setiap ID item media sebagai ID baru Parameter kueri mediaItemIds 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 media item. 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. Mereka adalah berlaku selama 60 menit dan memerlukan parameter tambahan karena tidak dapat digunakan sebagai alamat IP internalnya.

Berbagai URL dasar adalah:

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

URL image base

Berikut daftar opsi yang dapat Anda gunakan dengan URL dasar gambar:

Parameter
w, h

Deskripsi

Lebar, w dan tinggi, h parameter.

Untuk mengakses item media gambar, seperti foto atau thumbnail untuk sebuah video, Anda harus menentukan dimensi yang akan ditampilkan aplikasi Anda (sehingga gambar dapat diskalakan ke dalam dimensi tanpa mengubah rasio aspek). Untuk melakukannya: gabungkan URL dasar dengan dimensi yang diperlukan seperti yang ditunjukkan pada contoh.

Contoh:

base-url=wmax-width-hmax-height

Berikut contoh untuk menampilkan item media dengan lebar tidak lebih dari 2048 px dan tidak lebih tinggi dari 1024 px:

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

Deskripsi

Crop, parameter c.

Jika Anda ingin memangkas gambar agar sesuai dengan lebar dan tinggi yang tepat dimensi yang Anda tentukan, gabungkan URL dasar dengan parameter -c opsional beserta elemen Parameter w dan h.

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

Contoh:

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

Dalam contoh ini, aplikasi menampilkan item media yang lebar persis 256 px dan tinggi 256 px, seperti {i>thumbnail<i}:

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

Deskripsi

Parameter download, d.

Jika Anda ingin mendownload gambar yang menyimpan semua metadata Exif kecuali metadata lokasi, sambungkan URL dasar dengan Parameter d.

Contoh:

base-url=d

Dalam contoh ini, aplikasi mengunduh 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, sambungkan baseUrl dengan video download, dv .

Parameter dv meminta respons berkualitas tinggi, yang di-transcoding dari video asli. Parameter ini bukan kompatibel dengan w dan h parameter.

URL dasar untuk download video dapat memerlukan waktu hingga beberapa detik untuk menampilkan byte. Hasil download video ditetapkan secara default ke encoding H.264. Jika encoding H.264 gagal, maka VP9 akan digunakan.

Sebelum menggunakan parameter ini, periksa apakah metode Kolom mediaMetadata.status adalah READY. Atau, jika item media Anda belum proses selesai, Anda mungkin menerima {i>error<i}.

Contoh:

base-url=dv

Contoh berikut menunjukkan cara mengunduh byte dari 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 pemutaran tombol. Lihat parameter -no untuk menghapus overlay ini.

Contoh:

Lihat tabel URL dasar gambar untuk contoh.
no

Deskripsi

Hapus overlay thumbnail, parameter no.

Jika Anda ingin mengambil thumbnail video tanpa overlay tombol pemutaran, gabungkan URL dasar dengan no .

Parameter no harus digunakan dengan setidaknya salah satu dari tindakan parameter URL dasar gambar.

Contoh:

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

Contoh berikut menampilkan thumbnail video yang lebarnya tepat 1.280 px dan tinggi 720 px dan tidak menyertakan overlay tombol pemutaran:

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

URL dasar foto gerakan

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 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 motion, gunakan format untuk URL dasar gambar.