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

必要的授權範圍

Google Photos Library API 提供多個範圍，可用於存取媒體項目和相簿。各種呼叫傳回的媒體項目會因開發人員要求的範圍而異。

photoslibrary.readonly 範圍允許存取使用者資料庫中的所有媒體項目。photoslibrary.readonly.appcreateddata 範圍僅允許存取應用程式建立的媒體項目。詳情請參閱「授權範圍」。

總覽

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

列出使用者相片庫中的項目時，您可以使用篩選器選取符合指定日期、內容類別或媒體類型的相片。當您列出專輯中的項目時，此功能不支援這項功能。

列出程式庫和相簿內容會傳回媒體項目清單。 但不含專輯中的豐富內容。媒體項目可用來描述相片、影片或其他媒體。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 專用分頁

為提升效能，傳回大量結果的方法 (例如清單方法) 可能會將回應分頁。每頁的結果數量上限則是由 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，您可以在初始要求後傳送要求以取得其他結果。