使用者可共用應用程式建立的相簿,且可選擇允許使用者在相簿中留言或提供自己的媒體項目。
如要透過 Google Photos Library API 共享相簿,應用程式必須執行下列步驟:
必要的驗證範圍
您的應用程式必須要求 photoslibrary.sharing
授權範圍,才能分享內容。
分享相簿
共享相簿前,請考量下列事項:
- 應用程式只能分享自己建立的相簿。應用程式無法分享由其他應用程式 (包括 Google 相簿) 建立的相簿。
- 應用程式透過 Library API 分享專輯時,會產生可分享網址,以供任何人存取該專輯。
- 如果是透過 API 共享的相簿,相簿擁有者可以關閉連結共享設定,或是取消 Google 相簿應用程式中的相簿分享功能,這可能會導致應用程式無法加入新使用者。
如何分享相簿:
- 請遵循使用者體驗指南,取得使用者明確同意來建立共享相簿。
- 建立相簿,並錄製其
albumId
。如果您已建立相簿,可以列出使用者的相簿,以擷取其albumId
。 - 使用相關的
albumId
呼叫albums.share
,以及您要設定的共用選項。 - 記錄回應中的
shareToken
值。共用權杖是共用相簿的 ID,可在不同的使用者帳戶中使用。 - 現在其他使用者可以透過您的應用程式進行驗證,然後使用其
shareToken
join、離開或擷取共享相簿的詳細資料。
分享選項
使用 sharedAlbumOptions
參數共享相簿時,您可以設定下列選項。如果選項未明確設定,系統會使用預設值。
屬性 | 預設值 | 說明 |
---|---|---|
isCollaborative |
false |
設定是否允許其他 Google 相簿使用者可以在共享相簿中新增內容。 |
isCommentable |
false |
設定是否允許其他 Google 相簿使用者在共享相簿中發表留言。 |
要求範例
以下要求透過呼叫 albums.share
的方式分享相簿,並提供選項。回應中會傳回 shareInfo
屬性,說明相簿的分享屬性。
REST
以下是分享相簿的 POST 要求標頭:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:share Content-type: application/json Authorization: Bearer oauth2-token
在要求主體中指定分享選項。
{ "sharedAlbumOptions": { "isCollaborative": "true", "isCommentable": "true" } }
這個要求會傳回下列回應:
{ "shareInfo": { "sharedAlbumOptions": { "isCollaborative": "true", "isCommentable": "true" }, "shareableUrl": "shareable-url", "shareToken": "share-token", "isJoinable": "true-if-users-can-join-album", "isJoined": "true-if-user-is-joined-to-album", "isOwned": "true-if-user-owns-album" } }
Java
try { SharedAlbumOptions options = // Set the options for the album you want to share SharedAlbumOptions.newBuilder() .setIsCollaborative(true) .setIsCommentable(true) .build(); ShareAlbumResponse response = photosLibraryClient.shareAlbum(albumId, options); // The response contains the shareInfo object, a url, and a token for sharing ShareInfo info = response.getShareInfo(); // Link to the shared album String url = info.getShareableUrl(); String shareToken = info // The share token which other users of your app can use to join the album you shared .getShareToken(); SharedAlbumOptions sharedOptions = info // The options set when sharing this album .getSharedAlbumOptions(); } catch (ApiException e) { // Handle error }
PHP
// Set the options for the album you want to share $options = new SharedAlbumOptions(); $options->setIsCollaborative(true); $options->setIsCommentable(true); try { $response = $photosLibraryClient->shareAlbum($albumId, ['sharedAlbumOptions' => $options]); // The response contains the shareInfo object, a url, and a token for sharing $shareInfo = $response->getShareInfo(); // Link to the shared album $url = $shareInfo->getShareableUrl(); // The share token which other users of your app can use to join the album you shared $shareToken = $shareInfo->getShareToken(); // The options set when sharing this album $sharedOptions = $shareInfo->getSharedAlbumOptions(); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
共享相簿屬性
對於已經建立並分享的相簿,所有傳回 album
的回應都會包含額外屬性 shareInfo
。分享、列出或retrieving相簿時,系統會傳回這個屬性。
下表列出 shareInfo
屬性:
屬性 | |
---|---|
sharedAlbumOptions |
說明使用者是否可以在共享相簿中新增媒體項目或發表留言。 |
shareableUrl |
共享 Google 相簿的連結。知道連結的人都能查看相簿內容,因此請謹慎處理。 只有在相簿已開啟連結共享功能時,系統才會傳回 如果擁有者關閉 Google 相簿應用程式中的連結共享設定,或是相簿已取消分享, |
shareToken |
這類權杖可用來代表非擁有者使用者join、離開或擷取共享相簿的詳細資料。 如果擁有者關閉 Google 相簿應用程式中的連結共享設定,或是相簿已取消分享, |
isJoinable |
True (表示使用者可加入相簿)。 |
isJoined |
True (如果使用者已加入相簿)。該日期對相簿擁有者來說皆是如此。 |
isOwned |
True (如果是使用者擁有的相簿)。 |
取消共享相簿
如要取消分享應用程式先前分享的相簿,請使用相簿的 albumId
呼叫 albums.unshare
。
除了停止共享相簿外,還會發生下列情況:
- 所有非擁有者的使用者都將無法再存取相簿。這包括透過 Google 相簿應用程式特定共享相簿的使用者。
- 所有由非擁有者新增的內容都會從相簿中移除。
- 如果使用者先前已將專輯內容新增至媒體庫,這些內容會保留在他們的媒體庫中。
- 相簿的分享權杖和可分享的網址將會失效。
要求範例
REST
以下是取消分享相簿的 POST 要求標頭:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:unshare Content-type: application/json Authorization: Bearer oauth2-token
要求主體必須為空白。
如果要求成功,系統會傳回包含 HTTP 成功狀態碼的空白回應。如果要求失敗,則會傳回含有錯誤訊息的 HTTP 錯誤狀態碼。
Java
try { // If this call is not successful, an exception is raised photosLibraryClient.unshareAlbum(albumId); } catch (ApiException e) { // Handle error }
PHP
try { // Mark the album as private and no longer shared // If this call is not successful, an exception is raised $photosLibraryClient->unshareAlbum($albumId); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
擷取共用相簿及分享權杖
應用程式分享相簿時,系統會傳回共享相簿的詳細資料 (包括共用權杖)。之後,您也可以透過下列方式擷取這些詳細資料。
如果目前連線至應用程式的使用者為擁有者或已加入相簿:
- 使用
albums.get
時,使用相關的albumId
。 - 使用
albums.list
時,如果相簿中有媒體項目, - 使用
sharedAlbums.list
可傳回使用者加入或擁有的所有共享相簿。如果只要擷取應用程式已建立的相簿,請使用excludeNonAppCreatedData
參數。 - 使用共用權杖的
sharedAlbums.get
。
如果目前連線至應用程式的使用者尚未加入相簿,您可以使用有效的共用權杖,透過 sharedAlbums.get
擷取共享相簿的詳細資料。
要求範例
REST
以下要求在 shareToken
前取得專輯:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token
如果要求成功,系統會傳回共用的
album
詳細資料。
Java
try { // Get a shared album from its share token Album sharedAlbum = photosLibraryClient.getSharedAlbum(shareToken); String id = sharedAlbum.getId(); String title = sharedAlbum.getTitle(); // ... } catch (ApiException e) { // Handle error }
PHP
try { // Get the album from a share token $album = $photosLibraryClient->getSharedAlbum($shareToken); // Get some properties of an album $productUrl = $album->getProductUrl(); $title = $album->getTitle(); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
正在加入共享相簿
應用程式可使用相簿的分享權杖,代表使用者加入共享相簿。前提是必須符合下列條件:
- 應用程式建立並分享該相簿。
- 你要加入相簿的使用者不是擁有者。也就是說,相簿的
shareInfo
中的isOwned
欄位為 false。 - 共用權杖有效。
- 專輯
shareInfo
中的isJoinable
欄位為 true。
REST
以下是加入共享相簿的 POST 要求標頭:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:join Content-type: application/json Authorization: Bearer oauth2-token
在要求主體中,指定 shareToken
。
{ "shareToken": "share-token" }
POST 要求會傳回共用的 album
,您的應用程式會代表使用者加入。
Java
try { // Join the shared album using the share token obtained when sharing the album // If this call is not successful, an exception is raised JoinSharedAlbumResponse response = photosLibraryClient.joinSharedAlbum(shareToken); Album joinedAlbum = response.getAlbum(); } catch (ApiException e) { // Handle error }
PHP
try { $response = $photosLibraryClient->joinSharedAlbum($shareToken); // Join the shared album using the share token obtained when sharing the album // If this call is not successful, an exception is raised $joinedAlbum = $response->getAlbum(); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
正在離開共享相簿
應用程式可使用相簿的分享權杖,代表使用者離開共享相簿。前提是必須符合下列條件:
- 應用程式已建立並分享了這本相簿。
- 使用者目前已加入相簿。也就是說,相簿的
shareInfo
中的isJoined
欄位為 true。 - 連結至應用程式的使用者不是相簿擁有者。也就是說,相簿
shareInfo
中的isOwned
欄位為 false。
REST
以下是離開共享相簿的 POST 要求標頭:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:leave Content-type: application/json Authorization: Bearer oauth2-token
在要求主體中,指定 shareToken
。
{ "shareToken": "share-token" }
如果要求成功,系統會傳回包含 HTTP 成功狀態碼的空白回應。如果要求失敗,則會傳回含有錯誤訊息的 HTTP 錯誤狀態碼。
Java
try { // Leave a shared album using its share token // If this call is not successful, an exception is raised photosLibraryClient.leaveSharedAlbum(shareToken); } catch (ApiException e) { // Handle error }
PHP
try { // Leave the shared album using the share token obtained when sharing the album // If this call is not successful, an exception is raised $photosLibraryClient->leaveSharedAlbum($shareToken); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
共用媒體項目屬性
應用程式所分享相簿的媒體項目包含額外屬性 contributorInfo
。只有在列出共享相簿內容時,才會納入這個屬性。
contributorInfo
屬性包含將媒體項目新增至相簿的使用者名稱,以及新增至個人資料圖片的基本網址。
範例如下:
{ "id: "media-item-id", ..., "mediaMetadata": { ... } "contributorInfo": { "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters", "displayName": "name-of-user" } }