Chia sẻ nội dung nghe nhìn

Album do ứng dụng của bạn tạo có thể được chia sẻ giữa những người dùng, với các tùy chọn cho phép những người dùng đó để nhận xét hoặc đóng góp mục nội dung đa phương tiện của riêng họ vào album.

Để chia sẻ album thông qua API Thư viện Google Photos, ứng dụng của bạn cần thực hiện những việc sau:

1. Tạo album thay mặt cho người dùng.
2. Đặt album đó thành được chia sẻ.

Lưu ý: Trước khi chia sẻ album, hãy có được sự đồng ý rõ ràng của người dùng và đặt hãy nhớ làm theo Nguyên tắc về trải nghiệm người dùng.

Phạm vi xác thực bắt buộc

Để chia sẻ nội dung, ứng dụng của bạn phải yêu cầu photoslibrary.sharing phạm vi uỷ quyền.

Chia sẻ album

Trước khi chia sẻ album, hãy cân nhắc những điều sau:

• Ứng dụng của bạn chỉ có thể chia sẻ những album mà ứng dụng đó đã tạo. Album do các ứng dụng khác tạo, kể cả Google Photos, mà ứng dụng của bạn không chia sẻ được.
• Khi ứng dụng của bạn chia sẻ một album qua API Thư viện, URL có thể chia sẻ được tạo mà bất kỳ ai cũng có thể sử dụng để truy cập vào album.
• Đối với các anbom được chia sẻ qua API, chủ sở hữu của anbom có thể tắt tính năng chia sẻ đường liên kết hoặc thôi chia sẻ album trong ứng dụng Google Photos, việc này có thể ngăn ứng dụng của bạn kết hợp người dùng mới với ứng dụng đó.

Để chia sẻ album:

1. Làm theo Nguyên tắc về trải nghiệm người dùng và có được sự đồng ý rõ ràng của người dùng để tạo album chia sẻ.
2. Tạo album, và ghi lại albumId. Nếu đã tạo album, bạn có thể truy xuất albumId bằng cách liệt kê album của người dùng.
3. Gọi albums.share bằng albumId có liên quan, cùng với các lựa chọn chia sẻ mà bạn muốn thiết lập.
4. Ghi lại shareToken trong phản hồi. Mã thông báo chia sẻ là giá trị nhận dạng của album chia sẻ có thể được sử dụng trên các tài khoản người dùng khác nhau.
5. Người dùng khác hiện có thể xác thực bằng ứng dụng của bạn, sau đó tham gia, rời khỏi hoặc truy xuất thông tin chi tiết của album được chia sẻ bằng cách sử dụng shareToken của album.

Tuỳ chọn chia sẻ

Bạn có thể đặt các tuỳ chọn sau đây khi chia sẻ anbom bằng sharedAlbumOptions . Nếu bạn không đặt các tuỳ chọn rõ ràng, thì giá trị mặc định sẽ được sử dụng.

Thuộc tính	Giá trị mặc định	Mô tả
isCollaborative	false	Đặt xem người dùng Google Photos khác có thể thêm nội dung vào album chia sẻ.
isCommentable	false	Đặt xem người dùng Google Photos khác có thể nhận xét trên album chia sẻ.

Yêu cầu mẫu

Yêu cầu sau đây chia sẻ một album bằng cách gọi albums.share kèm theo các tuỳ chọn. Đáp Thuộc tính shareInfo được trả về trong phản hồi mô tả thuộc tính chia sẻ.

Kiến trúc chuyển trạng thái đại diện (REST)

Dưới đây là tiêu đề của yêu cầu POST để chia sẻ album:

POST https://photoslibrary.googleapis.com/v1/albums/album-id:share
Content-type: application/json
Authorization: Bearer oauth2-token

Trong nội dung yêu cầu, hãy chỉ định các tuỳ chọn chia sẻ.

{
  "sharedAlbumOptions": {
    "isCollaborative": "true",
    "isCommentable": "true"
  }
}

Yêu cầu này trả về phản hồi sau:

{
  "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
}

Thuộc tính album chia sẻ

Đối với các album mà ứng dụng của bạn tạo và chia sẻ, tất cả phản hồi trả về một album bao gồm một thuộc tính bổ sung, shareInfo. Chiến dịch này được trả về khi chia sẻ, trang thông tin hoặc truy xuất album.

Bảng sau đây liệt kê shareInfo thuộc tính:

Thuộc tính
sharedAlbumOptions	Các tuỳ chọn mô tả việc một người có thể thêm nội dung nghe nhìn các mục hoặc nhận xét về một album chia sẻ.
shareableUrl	Đường liên kết đến album chia sẻ trên Google Photos. Bất kỳ ai có đường liên kết đều có thể xem nội dung của anbom, do đó phải được xử lý cẩn thận. Trường shareableUrl chỉ được trả về nếu album có chia sẻ đường liên kết đã bật. Nếu người dùng đã tham gia vào album không được chia sẻ liên kết, họ có thể sử dụng productUrl của album để hãy truy cập vào ứng dụng đó. shareableUrl sẽ không hợp lệ nếu chủ sở hữu tắt đường liên kết chia sẻ trong ứng dụng Google Photos hoặc nếu album không được chia sẻ.
shareToken	Mã thông báo được dùng để tham gia, rời khỏi, hoặc truy xuất thông tin chi tiết của một album chia sẻ thay mặt cho một người dùng không phải là của bạn. shareToken sẽ không hợp lệ nếu chủ sở hữu tắt đường liên kết chia sẻ trong ứng dụng Google Photos hoặc nếu album không được chia sẻ.
isJoinable	True nếu người dùng có thể tham gia album.
isJoined	True nếu người dùng đã tham gia vào album. Thông báo này luôn luôn đúng với chủ sở hữu của anbom.
isOwned	True nếu người dùng sở hữu album.

Thận trọng: Bất cứ ai có shareableUrl của album đều có thể xem nội dung của album.

Ngắt chia sẻ album

Để huỷ chia sẻ album mà ứng dụng của bạn đã chia sẻ trước đó, hãy gọi albums.unshare bằng cách sử dụng albumId của anbom.

Ngoài album không còn được chia sẻ, những mục sau đây sẽ xảy ra:

• Tất cả những người không phải là chủ sở hữu sẽ mất quyền truy cập vào album. Số liệu này bao gồm cả những người có album được chia sẻ cụ thể thông qua ứng dụng Google Photos.
• Tất cả nội dung do những người không phải chủ sở hữu thêm vào sẽ bị xóa khỏi album.
• Nếu trước đây người dùng đã thêm nội dung của album vào thư viện của họ, nội dung sẽ được giữ lại trong thư viện của họ.
• Mã thông báo chia sẻ của album và URL có thể chia sẻ sẽ không hợp lệ.

Yêu cầu mẫu

Kiến trúc chuyển trạng thái đại diện (REST)

Dưới đây là tiêu đề của yêu cầu POST để thôi chia sẻ album:

POST https://photoslibrary.googleapis.com/v1/albums/album-id:unshare
Content-type: application/json
Authorization: Bearer oauth2-token

Nội dung yêu cầu phải trống.

Nếu thành công thì yêu cầu sẽ trả về một phản hồi trống kèm theo một HTTP mã trạng thái thành công. Nếu yêu cầu không thành công, hệ thống sẽ trả về một HTTP mã trạng thái lỗi kèm theo thông báo lỗi.

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
}

Truy xuất album chia sẻ và chia sẻ mã thông báo

Thông tin chi tiết về album chia sẻ, bao gồm cả mã thông báo chia sẻ, sẽ được trả về khi ứng dụng của bạn chia sẻ album. Bạn có thể cũng truy xuất các chi tiết đó sau đó theo các cách sau.

Nếu người dùng hiện đang kết nối với ứng dụng của bạn là chủ sở hữu hoặc đã tham gia với anbom:

• Với albums.get, sử dụng phương thức albumId có liên quan.
• Với albums.list, nếu có là các mục nội dung nghe nhìn trong album.
• Bằng sharedAlbums.list! Hàm này trả về tất cả các album chia sẻ mà người dùng đã tham gia hoặc sở hữu. Để truy xuất chỉ những album mà ứng dụng của bạn đã tạo, hãy sử dụng excludeNonAppCreatedData .
• Với sharedAlbums.get bằng mã thông báo chia sẻ.

Nếu người dùng hiện đang kết nối với ứng dụng của bạn chưa tham gia vào album, bạn có thể truy xuất chi tiết của album được chia sẻ với sharedAlbums.get sử dụng mã thông báo chia sẻ hợp lệ.

Yêu cầu mẫu

Kiến trúc chuyển trạng thái đại diện (REST)

Dưới đây là yêu cầu tải album vào shareToken:

GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token

Nếu yêu cầu thành công, hệ thống sẽ trả về dữ liệu được chia sẻ 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
}

Tham gia album chia sẻ

Ứng dụng của bạn có thể thay mặt người dùng tham gia một album chia sẻ có phần chia sẻ của album đó mã thông báo. Để thực hiện việc này, bạn phải đáp ứng các điều kiện sau:

• Ứng dụng của bạn có tạo và chia sẻ của bạn.
• Người dùng mà bạn muốn tham gia vào album không phải là chủ sở hữu. Đó là Trường isOwned trong album shareInfo là false.
• Mã thông báo chia sẻ là hợp lệ.
• Trường isJoinable trong shareInfo của album là true.

Thận trọng: Sau khi ứng dụng của bạn chia sẻ một album, chủ sở hữu album có thể tắt tính năng chia sẻ đường liên kết hoặc thôi chia sẻ album trong ứng dụng Google Photos. Nếu điều này xảy ra, mã thông báo chia sẻ sẽ không hợp lệ, trường isJoinable của mã đó sẽ sai và ứng dụng của bạn sẽ không thể tham gia cùng người dùng với ứng dụng đó.

Kiến trúc chuyển trạng thái đại diện (REST)

Dưới đây là tiêu đề của yêu cầu POST để tham gia album chia sẻ:

POST https://photoslibrary.googleapis.com/v1/sharedAlbums:join
Content-type: application/json
Authorization: Bearer oauth2-token

Trong phần nội dung yêu cầu, hãy chỉ định shareToken.

{
  "shareToken": "share-token"
}

Yêu cầu POST trả về album được chia sẻ ứng dụng của bạn đã tham gia thay mặt cho người dùng.

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
}

Rời khỏi album chia sẻ

Ứng dụng của bạn có thể rời khỏi một album chia sẻ thay mặt cho người dùng bằng cách sử dụng tính năng chia sẻ của album mã thông báo. Để thực hiện việc này, bạn phải đáp ứng các điều kiện sau:

• Ứng dụng của bạn đã tạo và chia sẻ album.
• Người dùng hiện đã tham gia vào album. Tức là trường isJoined trong shareInfo của anbom là true.
• Người dùng kết nối với ứng dụng của bạn không phải là chủ sở hữu của album. Đó là Trường isOwned trong shareInfo của album là false.

Kiến trúc chuyển trạng thái đại diện (REST)

Dưới đây là tiêu đề của yêu cầu POST để rời khỏi album chia sẻ:

POST https://photoslibrary.googleapis.com/v1/sharedAlbums:leave
Content-type: application/json
Authorization: Bearer oauth2-token

Trong phần nội dung yêu cầu, hãy chỉ định shareToken.

{
  "shareToken": "share-token"
}

Nếu thành công thì yêu cầu sẽ trả về một phản hồi trống kèm theo một HTTP mã trạng thái thành công. Nếu yêu cầu không thành công, hệ thống sẽ trả về một HTTP mã trạng thái lỗi kèm theo thông báo lỗi.

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
}

Thuộc tính mục nội dung nghe nhìn được chia sẻ

Mục nội dung đa phương tiện thuộc về album do ứng dụng của bạn chia sẻ chứa một thuộc tính bổ sung, contributorInfo. Thuộc tính này chỉ được đưa vào khi đăng nội dung của một album chia sẻ.

Thuộc tính contributorInfo bao gồm tên của người dùng đã thêm nội dung nghe nhìn mục vào album và URL cơ sở đến hồ sơ của họ hình ảnh.

Ví dụ:

{
  "id: "media-item-id",
  ...,
  "mediaMetadata": {
    ...
  }
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters",
    "displayName": "name-of-user"
  }
}

Lưu ý: Thuộc tính contributorInfo chỉ được trả về nếu người dùng đã cấp quyền quyền truy cập vào phạm vi photoslibrary.sharing.