列出應用程式建立的媒體項目和專輯

必要的授權範圍

商店資訊應用程式建立的內容需要 photoslibrary.readonly.appcreateddata 範圍。如要進一步瞭解範圍，請參閱「授權範圍」。

總覽

Library API 可讓您列出及存取應用程式的媒體項目

列出媒體項目的幾項重要功能包括：

  • 從特定應用程式建立的相簿或整個應用程式建立的相簿列出媒體項目 程式庫

  • 套用篩選器 (日期、內容類別、媒體) type) 個結果

  • 擷取 mediaItem 物件 當中包含直接連結和中繼資料等重要詳細資料

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

列出應用程式建立的相簿

您可以使用以下應用程式列出應用程式建立的相簿： 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"
}

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

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

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

回應也會包含 nextPageToken。若需更多資訊，請參閲 分頁。

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

列出應用程式建立的媒體庫內容

你可以列出使用者 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"
}

回應包含媒體項目清單，依時間由新到舊排序。 若需更多資訊，請參閲 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"
}

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

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

REST 的分頁

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

如果是呼叫 mediaItems.search 和 mediaItems.list，預設頁面大小為 25 個項目。我們建議使用這個頁面大小，因為它可在回應大小和填入率之間取得平衡。媒體項目的頁面大小上限 「搜尋」和「清單要求」可容納 100 個項目。

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

如果可用結果的數量超過頁面大小，回應就會包含 nextPageToken，這會向應用程式指出還有更多結果可從伺服器擷取。

範例

您必須將 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 請求。