您的应用创建的影集可以在用户之间共享,并为用户提供一些选项,使这些用户能够对影集发表评论或向影集贡献自己的媒体内容。
要通过 Google Photos Library API 分享影集,您的应用需要执行以下操作:
必需的身份验证范围
为了分享内容,您的应用必须请求 photoslibrary.sharing
授权范围。
分享影集
在分享影集前,请考虑以下注意事项:
- 您的应用只能分享其创建的影集。您的应用无法分享其他应用(包括 Google 相册)创建的影集。
- 当您的应用通过 Library API 分享影集时,系统会生成一个可分享的网址,任何人都可以通过该网址访问该影集。
- 对于通过 API 分享的影集,影集的所有者可以在 Google 相册应用中关闭链接共享或取消分享影集,这可能会阻止应用将新用户加入到该影集中。
要分享影集,请执行以下操作:
- 按照用户体验指南操作,并征得用户的明确同意才能创建共享影集。
- 创建影集,并录制其
albumId
。如果您已经创建了影集,可以通过列出用户的影集来检索其albumId
。 - 使用相关的
albumId
以及您想设置的分享选项调用albums.share
。 - 记录响应中的
shareToken
值。共享令牌是共享影集的标识符,可用于不同的用户帐号。 - 现在,另一个用户可以向您的应用进行身份验证,然后使用其
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 。对于影集的所有者而言,这种情况始终为 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" } }