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

必要的授權範圍

如要列出應用程式建立的內容，您必須使用 photoslibrary.readonly.appcreateddata 範圍。如要進一步瞭解範圍，請參閱「授權範圍」。

總覽

Library API 可讓您列出應用程式建立的媒體項目，並存取這些項目。

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

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

  • 列出篩選器 (日期、內容類別、媒體類型)，以縮小結果範圍

  • 擷取含有直接連結和中繼資料等重要詳細資料的 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 的分頁

為提升效能，傳回大量結果的方法 (例如清單方法) 可能會將回應分頁。pageSize 參數提供的是每頁結果數量上限。

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

列出相簿時，預設和建議的頁面大小為 20 張相簿，上限為 50 張相簿。

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

範例

您必須在參數 pageToken 中將 nextPageToken 附加至後續要求，如以下範例所示。請在要求主體中，或以查詢參數的形式，指定 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。