存取媒體項目

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

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

必要的授權範圍

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

  • 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 擷取多個媒體項目，請呼叫 mediaItems.batchGet敬上 使用 mediaItemId。

要求會依照要求中提供的媒體項目 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 分鐘，且需要額外的參數，因為無法將 不過，無論內部 IP 位址為何 DNS 名稱始終會指向特定的執行個體

各種基礎網址如下：

  • 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 像素、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

說明

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