存取應用程式建立的媒體項目

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

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

必要的授權範圍

如要存取應用程式建立的媒體項目，您必須具備 photoslibrary.readonly.appcreateddata 範圍。如要進一步瞭解範圍，請參閱「授權範圍」。

媒體項目

mediaItem 代表上傳到 Google 相簿相片庫的相片或影片等媒體。這是頂層物件，其屬性可能會因底層媒體類型而異。

下表列出 mediaItem 屬性：

屬性
id	用於識別物件的永久固定 ID。
description	Google 相簿中媒體項目的說明。
baseUrl	用於存取原始位元組。詳情請參閱「Base URLs」。
productUrl	連結至 Google 相簿中的圖片。只有使用者本人才能開啟這個連結，網址會指向媒體庫中的媒體項目。如果是從相簿搜尋擷取的網址，它會指向相簿中的項目。
mimeType	媒體項目的類型，可協助輕鬆識別媒體類型 (例如：image/jpg)。
filename	媒體項目的檔案名稱，會在 Google 相簿應用程式中向使用者顯示 (在項目的資訊部分)。
mediaMetadata	這會因媒體的基礎類型而異，例如 photo 或 video。如要減少酬載，可以使用欄位遮罩。

取得媒體項目

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

mediaItem 包含 ID、說明和網址等屬性。photo 或 video 中的其他資訊，取決於檔案中的中繼資料。可能不會顯示所有屬性。

如果媒體項目是影片，則必須先處理影片檔案。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"
  }
}

取得多個媒體項目

如要依據 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."
      }
    }
  ]
}

基礎網址

Google Photos API 中的基本網址可供存取媒體項目的原始位元組，讓應用程式能夠下載或顯示這些內容。列出專輯 (Library API) 或存取媒體項目 (Library 和 Picker API) 時，這些網址會包含在回應中。提醒您，基本網址需要額外的參數才能正常運作。

Picker API：

所有 PickedMediaItem.mediaFile 物件都包含 baseUrl。

基本網址會保持有效 60 分鐘，但如果使用者透過 Google 帳戶設定撤銷應用程式的權限，則可能會提早失效。

注意： 對 PickedMediaItem.mediaFile baseUrl 提出的要求必須包含 Authorization 標頭，並附上有效的 OAuth 2.0 不記名憑證。

Library 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	說明 如要擷取動態相片媒體項目的圖片元素，請使用圖片基礎網址的格式。