Learn about the new Picker API and important Library API changes. Details here.

本頁面由 Cloud Translation API 翻譯而成。

存取媒體項目

撥打給列出相片庫或相簿的內容，應用程式應儲存媒體項目的 ID。這是因為媒體項目的內容時間過後，回應中所含網址就會失效。媒體項目 ID 可用於識別相片或影片等媒體項目在使用者介面中

請注意，您的應用程式不應快取使用者相片或影片的時間過長根據您的用途，您可以儲存或快取做為媒體項目編號長。您也應該注意，user 資料受隱私權規範義務。

必要的授權範圍

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

photoslibrary.readonly 會允許存取使用者程式庫
photoslibrary.readonly.appcreateddata 僅允許存取符合以下條件的媒體項目：是由應用程式建立

媒體項目

A 罩杯 mediaItem敬上代表的媒體，例如上傳到 YouTube 的相片或影片顯示在 Google 相簿相片庫中這是一個頂層物件，其屬性可以會因基礎媒體類型而異

下表列出 mediaItem 屬性：

屬性
`id`	用來識別物件的永久固定 ID。
`description`	顯示於媒體項目的說明 Google 相簿
`baseUrl`	用於存取原始位元組。詳情請參閱「基準網址」。
`productUrl`	Google 相簿內部圖片的連結。這個連結不可僅由使用者開啟。網址指向以下中的媒體項目：程式庫。如果是從相簿搜尋擷取的網址，指向相簿中的項目。
`mimeType`	可輕鬆識別媒體類型的媒體項目類型 (例如：`image/jpg`)。
`filename`	在 Google 相簿向使用者顯示的媒體項目檔案名稱。
`mediaMetadata`	因媒體的基礎類型而異，例如 `photo` 或 `video`。如要減少酬載，可以使用欄位遮罩。
`contributorInfo`	這個欄位只有在媒體項目位於共享相簿中時才會填入資料，且使用者已授予 `photoslibrary.sharing` 範圍。包含加入這個媒體的著作人相關資訊項目。詳情請參閱「分享媒體」。

取得媒體項目

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

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

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

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

這個要求會傳回 MediaItemResults敬上按照請求中提供的媒體項目 ID 順序排列。每筆結果包含 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 Photos Library API 中的基本網址可讓你存取媒體位元組項目。應用程式可以使用各種基準網址，下載媒體項目或在應用程式內顯示媒體項目。「基礎網址」是附加在回應中。這些效期為 60 分鐘，且需要額外的參數，因為無法將不過，無論內部 IP 位址為何 DNS 名稱始終會指向特定的執行個體

常見的網址如下：

baseUrl：直接存取相片、影片縮圖或下載影片位元組。
coverPhotoBaseUrl：直接存取相簿的封面相片。
profilePictureBaseUrl：直接存取 mediaItem。

，瞭解如何調查及移除這項存取權。

映像檔基本網址

以下是可與映像檔基本網址搭配使用的選項清單：

參數

參數
`w`、`h`	說明寬度、`w` 和高度 `h` 參數。如要存取圖片媒體項目，例如則您必須指定要在影片廣告中顯示的尺寸以便可以將圖片縮放為這些元件同時保留長寬比)。方法如下將基準網址連結至所需尺寸，如下所示：範例。例如： `base-url`=w`max-width`-h`max-height` 以下範例說明如何顯示寬度為 2048 像素且不大於 1024 像素： https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
`c`	說明裁剪，`c` 參數。如果您希望將圖片裁剪為確切的寬度和高度將基準網址和自選 `-c` 參數和必要的 `w` 和 `h` 參數。大小 (以像素為單位) 應在 [1, 16383] 範圍內。如果有圖片的寬度或高度，超過要求的大小，縮小並裁剪圖片 (維持長寬比)。例如： `base-url`=w`max-width`-h`max-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

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 相容參數。影片下載的基本網址可能需要幾秒鐘才能完成傳回位元組。下載影片時，預設使用 H.264 編碼。如果 H.264 編碼失敗，系統會使用 VP9。使用這個參數前，請檢查媒體項目的 `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`=w`max-width`-h`max-height`-no 以下範例顯示的影片縮圖，寬度正好為 1280 px x 720 px，且不含播放按鈕重疊： https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

dv

說明

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

dv 參數請求的是高品質。原始影片的轉碼版本。參數不是與 w 和 h 相容參數。

影片下載的基本網址可能需要幾秒鐘才能完成傳回位元組。下載影片時，預設使用 H.264 編碼。如果 H.264 編碼失敗，系統會使用 VP9。

使用這個參數前，請檢查媒體項目的 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 px x 720 px，且不含播放按鈕重疊：

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

動態相片基本網址

動態相片同時包含相片和影片元素。您可以使用映像檔基本網址或動態相片 baseUrl 要求的影片基本網址。

參數

參數
`dv`	說明如要擷取動態相片媒體項目的影片元素，請使用 `dv` 參數，與從影片基本網址下載相同。
`w`、`h`、`c`和 `d`	說明如要擷取動態相片媒體項目的相片元素，請使用圖片基本網址的格式。

dv

說明

如要擷取動態相片媒體項目的影片元素，請使用 dv 參數，與從影片基本網址下載相同。

w、h、c和 d

說明

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