存取媒體項目

呼叫列出相片庫或相簿的內容後，應用程式應儲存媒體項目的 ID，而不是儲存傳回的媒體項目。這是因為媒體項目的內容可能會變更，且在一段時間後，回應中包含的網址會過期。媒體項目 ID 可明確識別媒體項目，例如使用者媒體庫中的相片或影片。

請注意，應用程式不應長時間快取使用者的相片或影片，但視用途而定，您可以儲存或快取媒體項目 ID，時間長度視需要而定。您也應注意，使用者資料的存取權受隱私權義務規範。

必要的授權範圍

如要存取媒體項目，應用程式必須至少要求以下其中一個授權範圍。您可以存取回應中傳回的媒體項目，取決於您要求的範圍。

  • photoslibrary.readonly 可存取使用者媒體庫中的所有媒體項目
  • photoslibrary.readonly.appcreateddata 只允許存取由應用程式建立的媒體項目

媒體項目

mediaItem 是媒體的表示法，例如已上傳至 Google 相簿相片庫的相片或影片。這是頂層物件，其屬性可能會因基礎媒體類型而異。

下表列出 mediaItem 屬性：

屬性
id 用於識別物件的永久固定 ID。
description Google 相簿中媒體項目的說明。
baseUrl 用於存取原始位元組。詳情請參閱「Base URLs」。
productUrl

Google 相簿內部圖片的連結。開發人員無法開啟這個連結，只有使用者可以開啟。網址會指向媒體庫中的媒體項目。如果網址是從相簿搜尋中擷取，則會指向相簿中的項目。
mimeType 可輕鬆識別媒體類型的媒體項目類型，例如 image/jpg。
filename 媒體項目的檔案名稱，會在 Google 相簿應用程式中向使用者顯示 (在項目的資訊部分)。
mediaMetadata 這會因媒體的基礎類型而異，例如 photo 或 video。如要減少酬載，可以使用欄位遮罩。
contributorInfo

只有在媒體項目位於由此應用程式建立的共用相簿中，且使用者已授予 photoslibrary.sharing 範圍時，這個欄位才會填入資料。

包含新增此媒體項目的貢獻者相關資訊。詳情請參閱「分享媒體」。

取得媒體項目

如要擷取媒體項目，請使用 mediaItemId 呼叫 mediaItems.get。要求會傳回單一媒體項目。

mediaItem 包含 ID、說明和網址等屬性。photo 或 video 中的其他資訊，取決於檔案中的中繼資料。部分屬性可能不會顯示。ContributorInfo 包含共享相簿中項目的中繼資料。只有在列出共用相簿的內容時，才會納入這個欄位，且使用者必須已授予 photoslibrary.sharing 授權範圍。

如果媒體項目是影片，則必須先處理影片檔案。mediaItem 在 mediaMetadata 中包含 status 欄位，用來說明影片檔案的處理狀態。新上傳的檔案會先傳回 videoProcessingStatus，值為 PROCESSING，然後再 READY 供使用。影片必須先經過處理，才能使用影片媒體項目的 baseUrl。

REST

以下是 GET 要求：

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

相片媒體項目的回應如下所示。photo 屬性包含相片項目的中繼資料。

{
  "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"
  }
}

影片媒體項目的回應如下所示。影片屬性包含影片項目的中繼資料。

{
  "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

相片屬性包含相片項目的中繼資料。

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
}

影片屬性包含影片項目的中繼資料。

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

相片屬性包含相片項目的中繼資料。

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
}

影片屬性包含影片項目的中繼資料。

  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
}

取得多個媒體項目

如要依 ID 擷取多個媒體項目，請使用 mediaItemId 呼叫 mediaItems.batchGet。

要求會依照要求中提供的媒體項目 ID 順序，傳回 MediaItemResults 清單。每個結果都包含 MediaItem 或 Status (如果發生錯誤)。

一次呼叫中可要求的媒體項目數量上限為 50 個。媒體項目清單不得包含重複的 ID，也不能留空。

REST

以下是 GET 要求，顯示媒體項目的存取成功和失敗情況。在要求中指定每個媒體項目 ID 做為新的 mediaItemIds 查詢參數：

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

GET 要求會傳回下列回應：

{
  "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
}

基礎網址

Google 相簿程式庫 API 中的基礎網址可讓您存取媒體項目的位元組。應用程式可使用各種基本網址，下載媒體項目或在應用程式中顯示媒體項目。基本網址是字串，會在您列出專輯或存取媒體項目時，納入回應中。有效時間為 60 分鐘，且需要額外參數，因為無法直接使用。

常見的網址如下：

  • baseUrl：直接存取相片、影片縮圖或下載影片位元組。
  • coverPhotoBaseUrl：直接存取相簿的封面相片。
  • profilePictureBaseUrl：直接存取 mediaItem 擁有者的個人資料相片。

圖片基準網址

以下是可搭配圖片基本網址使用的選項清單：

參數
w、h

說明

寬度 w 和高度 h 參數。

如要存取圖片媒體項目 (例如影片的相片或縮圖)，您必須指定想要在應用程式中顯示的尺寸 (這樣圖片可以縮放為這些尺寸，同時保留長寬比)。如要這麼做，請將基準網址與所需尺寸連結，如範例所示。

例如：

base-url=wmax-width-hmax-height

以下範例說明如何顯示寬度不超過 2048 像素、高度不超過 1024 像素的媒體項目：

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

說明

裁剪 c 參數。

如要將圖片裁剪為您指定的確切寬度和高度，請將基準網址與選用的 -c 參數連結，並加上必要的 w 和 h 參數。

大小 (以像素為單位) 應介於 [1, 16383] 之間。如果圖片的寬度或高度超過要求的大小，圖片就會縮小並裁剪 (維持顯示比例)。

例如：

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

在這個範例中，應用程式會顯示寬度和高度皆為 256 像素的媒體項目，例如縮圖：

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

說明

下載，d 參數。

如果您想下載圖片，並保留位置中繼資料以外的所有 Exif 中繼資料，請將基準網址與 d 參數連結。

例如：

base-url=d

在這個範例中，應用程式會下載含有所有中繼資料的圖片，但不含位置中繼資料：

https://lh3.googleusercontent.com/p/Az....XabC=d

影片基準網址

以下是可搭配影片基本網址使用的選項清單：

參數
dv

說明

如要存取影片 mediaItem 的位元組，請將 baseUrl 與下載影片 dv 參數連結。

dv 參數會要求原始影片的高畫質轉碼版本。這個參數與 w 和 h 參數不相容。

影片下載的基本網址可能需要幾秒鐘的時間才能傳回位元組。

使用這個參數前，請確認媒體項目的 mediaMetadata.status 欄位為 READY。否則，如果媒體項目尚未完成處理，您可能會收到錯誤訊息。

例如：

base-url=dv

以下範例說明如何下載影片位元組：

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w、h、c 和 d

說明

如要存取影片縮圖，請使用任何圖片基準網址參數。

根據預設，所有影片縮圖都會附上播放按鈕的疊加層。查看 -no 參數即可移除這個疊加層。

例如：

如需範例，請參閱圖片基本網址表格。
no

說明

移除縮圖覆蓋圖片，no 參數。

如果您想擷取影片縮圖，但不顯示播放按鈕的疊加層，請將基本網址與 no 參數連結在一起。

no 參數必須搭配至少一個 圖片基本網址參數使用。

例如：

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

以下範例顯示的影片縮圖寬度和高度分別為 1280 像素和 720 像素，且不含播放按鈕疊加：

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

動態相片基本網址

動態相片包含相片和影片元素。您可以使用圖片基礎網址或影片基礎網址的參數，為動態相片 baseUrl 要求提供服務。

參數
dv

說明

如要擷取動態相片媒體項目的影片元素，請使用 dv 參數，就像從影片基礎網址下載一樣。
w、h、c 和 d

說明

如要擷取動態相片媒體項目的圖片元素，請使用圖片基礎網址的格式。