分享媒体内容

您的应用创建的影集可以在用户之间共享,您可以选择允许这些用户对影集发表评论或向影集贡献自己的媒体内容。

如需通过 Google Photos Library API 分享影集,您的应用需要执行以下操作:

  1. 代表用户创建影集
  2. 将该影集设为已分享

必需的身份验证范围

为了分享内容,您的应用必须请求 photoslibrary.sharing 授权范围

分享影集

在分享影集之前,请考虑以下事项:

  • 您的应用只能分享自己创建的影集。您的应用不能分享由其他应用(包括 Google 相册)创建的影集。
  • 当您的应用通过 Library API 分享影集时,系统会生成一个可分享的网址,任何人都可以使用此网址访问该影集。
  • 对于通过 API 分享的影集,影集的所有者可以在 Google 相册应用中关闭链接共享或停止分享该影集,这可能会导致您的应用无法加入新用户。

要分享影集,请执行以下操作:

  1. 遵循用户体验指南,并明确同意创建共享影集。
  2. 创建影集,并记录其 albumId。如果您已创建影集,则可以通过列出用户的影集检索其 albumId
  3. 使用相关的 albumId 以及您想设置的共享选项调用 albums.share
  4. 记录响应中的 shareToken 值。分享令牌是共享影集的标识符,可用于不同的用户帐号。
  5. 现在,另一用户可以向您的应用进行身份验证,然后使用共享影集的 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 相册中共享影集的链接。知道链接的任何人都可以查看影集的内容,因此请务必谨慎对待。

仅当影集已开启链接共享时,系统才会返回 shareableUrl 字段。如果用户已加入并非通过链接分享的影集,则可以改用该影集的 productUrl 来访问该影集。

如果所有者在 Google 相册应用中关闭了链接共享功能,或影集已取消分享,则 shareableUrl 会失效。

shareToken

用于代表非所有者用户join退出检索共享影集详情的令牌。

如果所有者在 Google 相册应用中关闭了链接共享功能,或影集已取消分享,则 shareToken 会失效。

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
}

检索共享影集和分享令牌

当应用分享影集时,系统会返回共享影集的详细信息(包括其分享令牌)。之后,您还可以通过以下方式检索这些详细信息。

如果当前连接到您应用的用户是所有者或已加入影集:

如果当前连接到您的应用的用户未加入影集,您可以使用有效的共享令牌通过 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"
  }
}