必要的授權範圍
Google Photos Library API 提供多個範圍,可用於存取媒體項目和相簿。各種呼叫傳回的媒體項目會因開發人員要求的範圍而異。
photoslibrary.readonly
範圍允許存取使用者資料庫中的所有媒體項目。photoslibrary.readonly.appcreateddata
範圍僅允許存取應用程式建立的媒體項目。詳情請參閱「授權範圍」。
總覽
這個 API 的重要用途是列出使用者已備份到 Google 相簿的媒體項目。可列出特定相簿或使用者整個相片庫的項目 (Google 相簿應用程式的預設檢視畫面)。
列出使用者相片庫中的項目時,您可以使用篩選器選取符合指定日期、內容類別或媒體類型的相片。當您列出專輯中的項目時,此功能不支援這項功能。
列出程式庫和相簿內容會傳回媒體項目清單。
但不含專輯中的豐富內容。媒體項目可用來描述相片、影片或其他媒體。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" }
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
:
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
,向應用程式指出要從伺服器擷取的更多結果。
範例
您必須將 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
。