您的应用创建的影集可以在用户之间共享,您可以选择允许这些用户对影集发表评论或向影集贡献自己的媒体内容。
如需通过 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" } }