列出媒體庫內容、相簿和媒體項目

必要的授權範圍

Google Photos Library API 包含多個範圍，可用於存取媒體項目和相簿。 根據不同的範圍，各種呼叫傳回的媒體項目會有所不同 未獲得開發人員的要求

photoslibrary.readonly 範圍允許存取 使用者的程式庫。photoslibrary.readonly.appcreateddata 範圍允許存取 只會用於由應用程式建立的媒體項目若需更多資訊，請參閲 授權範圍。

總覽

這個 API 的重要用途是列出使用者備份的媒體項目 。特定相簿或使用者整個相簿的項目 相片庫 (Google 相簿應用程式的預設檢視畫面) 會隨即顯示。

你可以使用濾鏡選取相片 依據您指定的日期、內容類別或媒體類型列出項目 來自使用者的程式庫當你在清單中列出項目時，將不支援這項功能 相簿。

列出媒體庫和相簿內容會傳回媒體項目清單。 相簿中的充實內容 的相關設定媒體項目描述的是相片、影片或其他媒體。A 罩杯 mediaItem 包含該項目的直接連結，以及該項目在 Google 相簿和其他相關中繼資料若需更多資訊，請參閲 存取媒體項目和 mediaItems。

注意： 請勿快取使用者的相片和影片。請改為儲存媒體項目 id，並在需要時再次要求詳細資料。圖片可能隨時變動，且 透過 baseUrl 的直接存取會在 60 分鐘後失效。如要 資訊，請參閱 存取媒體項目。

列出相簿

您可以使用 albums.list.

REST

以下是要求範例：

GET https://photoslibrary.googleapis.com/v1/albums

這個要求會傳回下列結果：

{
  "albums": [
    {
      "id": "album-id",
      "title": "album-title",
      "productUrl": "album-product-url",
      "coverPhotoBaseUrl": "album-cover-base-url_do-not-use-directly",
      "coverPhotoMediaItemId": "album-cover-media-item-id",
      "isWriteable": "whether-you-can-write-to-this-album",
      "mediaItemsCount": "number-of-media-items-in-album"
    },
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all albums in the user's library
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums();

  for (Album album : response.iterateAll()) {
    // Get some properties of an album
    String id = album.getId();
    String title = album.getTitle();
    String productUrl = album.getProductUrl();
    String coverPhotoBaseUrl = album.getCoverPhotoBaseUrl();
    // The cover photo media item id field may be empty
    String coverPhotoMediaItemId = album.getCoverPhotoMediaItemId();
    boolean isWritable = album.getIsWriteable();
    long mediaItemsCount = album.getMediaItemsCount();
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums in the user's library
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // Get some properties of an album
        $albumId = $album->getId();
        $title = $album->getTitle();
        $productUrl = $album->getProductUrl();
        $coverPhotoBaseUrl = $album->getCoverPhotoBaseUrl();
        // The cover photo media item id field may be empty
        $coverPhotoMediaItemId = $album->getCoverPhotoMediaItemId();
        $isWriteable = $album->getIsWriteable();
        $totalMediaItems = $album->getTotalMediaItems();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

每個傳回的相簿都有 ID，可用於擷取 如同列出相簿內容一節中所示。此外， 包含標題及其中的媒體項目數量。

productUrl 指向 Google 相簿中的相簿，可以是 使用者開啟的新檔案

coverPhotoMediaItemId 包含媒體項目 ID： 代表這本相簿的封面相片。如要存取這張封面圖片，請使用 coverPhotoBaseUrl。請勿在沒有說明的情況下直接使用 coverPhotoBaseUrl 指定其他 參數

在使用者帳戶中建立或新增到使用者的相簿 帳戶，且應用程式共用了額外的 shareInfo 資源。 詳情請參閱「分享媒體」。

相簿也可能顯示 isWriteable 標記，用於表示您是否可以建立媒體 相簿中的項目。如未傳回，這個旗標會預設為 false。是 取決於授予應用程式的存取權，包括：

• 建立相簿的使用者。
• 是否與他人共用。
• 使用者的範圍 已核准。

如果這些條件有變動，這個標記可能會改變。詳情請參閱 建立相簿。 回應也包含 nextPageToken。若需更多資訊，請參閲 分頁。

空白相簿的回應會有所不同，mediaItemsCount 和 coverPhotoMediaItemId 預設為 0，而 REST 會省略 回應。另請注意，coverPhotoBaseUrl 會指向預設預留位置 圖片。

列出程式庫內容

您可以列出使用者 Google 相簿相片庫中的所有媒體項目。 但不包含已封存和已刪除的項目。您可以根據 內容、日期及其他屬性 篩選器。如果使用者尚未將 對方可在自己的 Google 相簿「共享」分頁中存取以下對象： 程式庫中，該項目就不會包含在此清單中。

如要擷取媒體項目，請呼叫 mediaItems.list.

REST

以下是要求範例：

GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
}

GET 要求會傳回下列回應：

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all media items in the user's library
  // Iterate over all the retrieved media items
  // Pagination is handled automatically
  ListMediaItemsPagedResponse response = photosLibraryClient.listMediaItems();
  for (MediaItem item : response.iterateAll()) {
    // Get some properties of a media item
    String id = item.getId();
    String description = item.getDescription();
    String mimeType = item.getMimeType();
    String productUrl = item.getProductUrl();
    String filename = item.getFilename();
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all media items in the user's library
    // Iterate over all the retrieved media items
    // Pagination is handled automatically
    $response = $photosLibraryClient->listMediaItems();
    foreach ($response->iterateAllElements() as $item) {
        // Get some properties of a media item
        /* @var $item \Google\Photos\Library\V1\MediaItem */
        $id = $item->getId();
        $description = $item->getDescription();
        $mimeType = $item->getMimeType();
        $productUrl = $item->getProductUrl();
        $filename = $item->getFilename();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

回應包含媒體項目清單，依時間由新到舊排序。 若需更多資訊，請參閲 mediaItems。此外， 包含 nextPageToken，詳情請參閱 分頁。

列出相簿內容

如要列出相簿中的所有媒體項目，請將 albumId 欄位新增至 搜尋要求。如要進一步瞭解 albumId，請參閱「列出商家資訊」 相簿和列出共享相簿。如果 albumId 無效，系統會傳回 Bad Request 錯誤。如果 ID 有效 但已驗證使用者沒有相簿，但 Not Found 錯誤為 。如要進一步瞭解錯誤處理，請參閱效能 提示和最佳 做法。

REST

以下是要求範例：

POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
  "albumId": "album-id"
}

POST 要求會傳回下列回應：

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all media items in an album
  // Provide the ID of the album as a parameter in the searchMediaItems call
  // Iterate over all the retrieved media items
  SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(albumId);

  for (MediaItem item : response.iterateAll()) {
    // ...
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all media items in an album
    // Provide the ID of the album as a parameter in the searchMediaItems call
    // Iterate over all the retrieved media items
    $response = $photosLibraryClient->searchMediaItems(['albumId' => $albumId]);
    foreach ($response->iterateAllElements() as $item) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

回應包含 nextPageToken 和媒體項目清單。不喜歡 則會按照其順序傳回媒體項目 專輯詳情請參閱 mediaItems敬上 和分頁。使用者可以編輯訂單 Google 相簿介面。

如果設定 albumId，就無法在列出相簿內容時套用篩選器。 這樣做會導致 Bad Request 錯誤。

列出共享相簿

您可以擷取使用者已分享或已分享的所有相簿清單 並與使用者共用這很像 Google 相簿應用程式。

使用者新增至 Google 相簿相片庫的共享相簿 清單相簿呼叫中也會傳回這些屬性。做出 呼叫下列呼叫，透過 Library API 列出共享相簿：

REST

以下是要求範例：

GET https://photoslibrary.googleapis.com/v1/sharedAlbums

這個要求會傳回下列結果：

{
  "sharedAlbums": [...]
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all albums that have been shared by the user
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums();

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums that have been shared by the user
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listSharedAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

「sharedAlbums」中有相簿清單。若需更多資訊，請參閲 列出相簿。回應也會包含 nextPageToken。 詳情請參閱分頁。

應用程式建立並分享的相簿包含額外的 shareInfo 資源。詳情請參閱「分享 媒體。

列出應用程式建立的專輯

您可以將應用程式建立的相簿列出為 已將下列呼叫中的 excludeNonAppCreatedData 設為 true：

• albums.list
• sharedAlbums.list

REST

這個 GET 要求會列出使用者的 僅由應用程式建立的 Google 相簿相片庫：

GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

這個 GET 要求可列出使用者 僅由應用程式建立的 Google 相簿相片庫：

GET https://photoslibrary.googleapis.com/v1/sharedAlbums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

Java

try {
  // Make a request to list all albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

try {
  // Make a request to list all shared albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response =
      photosLibraryClient.listSharedAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums that have been created by your app
    $response = $photosLibraryClient->listAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

try {
    // Make a request to list all shared albums that have been created by your app
    $response = $photosLibraryClient->listSharedAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

REST 的分頁

為了提升效能，建議方法會傳回大量結果 (例如 list 方法)，可能會使回應分頁。每個路徑中的結果數量上限 網頁是由 pageSize 參數決定

如果是呼叫 mediaItems:search 和 mediaItems:list，預設頁面大小為 25 個項目。建議您用這個網頁大小，這在 回應大小和供應率媒體項目的頁面大小上限 「搜尋」和「清單要求」可容納 100 個項目。

列出 20 本相簿， 最多 50 個相簿。

如果可用的結果數量超過頁面大小，系統就會回應 包含 nextPageToken，用於向應用程式表示 要從伺服器擷取更多結果。

注意： pageSize 參數為最大值，可能的結果較少 而非可能的要求。

範例

您必須將 nextPageToken 附加至參數中的後續要求 pageToken，如以下範例所示。一併指定 pageToken 以及作業所需的其他參數 (位於 查詢，或是做為查詢參數

要求 #1

{
  "pageSize": "5",
  "filters": { … }
}

回應 #1

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

要求 #2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

回應 #2

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

請繼續使用這個模式，直到沒有其他 nextPageToken 物件為止。

nextPageToken 只適用於相同要求。如果有任何參數 已變更，請勿在同一處使用先前使用的 nextPageToken 請求。

注意： nextPageToken 的存在是唯一表示是否存在的指標 系統要從伺服器擷取更多結果。不要計算 的結果，判斷是否應使用 nextPageToken。例如要求 傳回的結果少於網頁大小所要求的結果。如果 nextPageToken 是 您可以在首次提出要求後，再傳送要求以取得更多結果。