Bạn có thể chia sẻ các album do ứng dụng của bạn tạo ra giữa những người dùng, với các tuỳ chọn cho phép những người dùng đó nhận xét hoặc đóng góp các mục nội dung nghe nhìn của riêng họ vào album.
Để chia sẻ album 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:
- Tạo album thay mặt người dùng.
- Đặt album đó thành được chia sẻ.
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. Ứng dụng của bạn không thể chia sẻ album do các ứng dụng khác tạo, bao gồm cả Google Photos.
- Khi ứng dụng của bạn chia sẻ một album qua API Thư viện, một URL có thể chia sẻ sẽ được tạo và bất cứ ai cũng có thể dùng để truy cập vào album đó.
- Đối với các album được chia sẻ qua API, 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, điều này có thể ngăn ứng dụng của bạn tham gia cùng người dùng mới.
Cách chia sẻ album:
- Tuân thủ nguyên tắc về trải nghiệm người dùng và lấy sự đồng ý rõ ràng của người dùng để tạo album chia sẻ.
- Tạo album và ghi lại
albumId
của album. Nếu đã tạo đĩa nhạc, bạn có thể truy xuấtalbumId
của đĩa nhạc đó bằng cách liệt kê các đĩa nhạc của người dùng. - Gọi
albums.share
bằng cách sử dụngalbumId
có liên quan cùng với tuỳ chọn chia sẻ mà bạn muốn đặt. - Ghi lại giá trị
shareToken
trong phản hồi. Mã thông báo chia sẻ là giá trị nhận dạng của một album chia sẻ. Bạn có thể sử dụng mã này trên nhiều tài khoản người dùng. - Một người dùng khác hiện có thể xác thực bằng ứng dụng của bạn, sau đó join, rời khỏi hoặc truy xuất thông tin chi tiết về album chia sẻ bằng
shareToken
.
Tuỳ chọn chia sẻ
Bạn có thể đặt các tuỳ chọn sau đây khi chia sẻ một album bằng tham số sharedAlbumOptions
. Nếu bạn không đặt rõ ràng các tuỳ chọn, thì giá trị mặc định sẽ được sử dụng.
Tài sản | Giá trị mặc định | Nội dung mô tả |
---|---|---|
isCollaborative |
false |
Đặt liệu những người dùng Google Photos khác có thể thêm nội dung vào album chia sẻ hay không. |
isCommentable |
false |
Đặt liệu người dùng Google Photos khác có thể nhận xét về album chia sẻ hay không. |
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
với các tuỳ chọn. Thuộc tính shareInfo
được trả về trong phản hồi mô tả thuộc tính chia sẻ của album.
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 lựa 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 }
1.199
// 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 do ứng dụng của bạn tạo và chia sẻ, tất cả phản hồi trả về album
đều bao gồm một thuộc tính bổ sung là shareInfo
. Thuộc tính này được trả về khi chia sẻ, danh sách hoặc retrieving album.
Bảng sau đây liệt kê các thuộc tính shareInfo
:
Thuộc tính | |
---|---|
sharedAlbumOptions |
Các tuỳ chọn mô tả việc một người có thể thêm các mục nội dung nghe nhìn vào hoặc nhận xét về một album chia sẻ hay không. |
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 album. Vì vậy, bạn cần cẩn thận khi xem album. Trường
|
shareToken |
Mã thông báo dùng để join, rời khỏi hoặc truy xuất thông tin của một album chia sẻ thay mặt cho người dùng không phải là chủ sở hữu.
|
isJoinable |
True nếu người dùng có thể tham gia album. |
isJoined |
True nếu người dùng đã tham gia album. Điều này luôn đúng với chủ sở hữu album. |
isOwned |
True nếu người dùng sở hữu album. |
Ngừng chia sẻ album
Để huỷ chia sẻ một album mà ứng dụng của bạn đã chia sẻ trước đó, hãy gọi
albums.unshare
bằng
albumId
của album đó.
Ngoài việc album không còn được chia sẻ nữa, những điều sau sẽ xảy ra:
- Tất cả những người không phải là chủ sở hữu đều sẽ mất quyền truy cập vào album này. Số liệu này bao gồm cả những người có album được chia sẻ cụ thể với họ 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 sẽ bị xoá khỏi album.
- Nếu trước đây người dùng đã thêm nội dung của đĩa nhạc vào thư viện, thì nội dung đó sẽ vẫn được giữ lại trong thư viện.
- Mã chia sẻ và URL có thể chia sẻ của album 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 yêu cầu thành công, hệ thống sẽ trả về một phản hồi trống kèm theo mã trạng thái thành công HTTP. Nếu yêu cầu không thành công, yêu cầu sẽ trả về mã trạng thái lỗi HTTP kèm 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 }
1.199
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ẻ của album) sẽ được trả về khi ứng dụng của bạn chia sẻ album. Sau đó, bạn cũng có thể truy xuất các thông tin chi tiết đó theo các cách sau.
Nếu người dùng hiện đã kết nối với ứng dụng của bạn là chủ sở hữu hoặc được tham gia vào album:
- Với
albums.get
sử dụngalbumId
có liên quan. - Với
albums.list
, nếu có các mục nội dung nghe nhìn trong album. - Với
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. Để chỉ truy xuất các album mà ứng dụng của bạn đã tạo, hãy sử dụng tham sốexcludeNonAppCreatedData
. - Với
sharedAlbums.get
, hãy dùng mã chia sẻ.
Nếu người dùng đang kết nối với ứng dụng của bạn chưa tham gia album, bạn có thể truy xuất thông tin của album chia sẻ bằng sharedAlbums.get
bằng cách 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 nhận album theo shareToken
:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token
Nếu yêu cầu thành công, yêu cầu sẽ trả về thông tin chi tiết đượ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 }
1.199
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 album chia sẻ bằng mã thông báo chia sẻ của album đó. Để làm được như vậ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 mà bạn muốn tham gia vào album không phải là chủ sở hữu của album. Tức là trường
isOwned
trongshareInfo
của album là false. - Mã thông báo chia sẻ là hợp lệ.
- Trường
isJoinable
trongshareInfo
của album là true.
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 nội dung yêu cầu, hãy chỉ định shareToken
.
{ "shareToken": "share-token" }
Yêu cầu POST sẽ trả về album
chung mà ứng dụng của bạn đã tham gia thay mặt 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 }
1.199
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 album chia sẻ thay mặt cho người dùng bằng mã thông báo chia sẻ của album. Để làm được như vậ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. Điều này nghĩa là trường
isJoined
trongshareInfo
của album là true. - Người dùng được kết nối với ứng dụng của bạn không phải là chủ sở hữu album. Điều đó có nghĩa là trường
isOwned
trongshareInfo
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 nội dung yêu cầu, hãy chỉ định shareToken
.
{ "shareToken": "share-token" }
Nếu yêu cầu thành công, hệ thống sẽ trả về một phản hồi trống kèm theo mã trạng thái thành công HTTP. Nếu yêu cầu không thành công, yêu cầu sẽ trả về mã trạng thái lỗi HTTP kèm 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 }
1.199
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 dùng chung
Mục nội dung nghe nhìn thuộc về
album mà ứng dụng của bạn chia sẻ chứa một thuộc tính bổ sung là
contributorInfo
.
Thuộc tính này chỉ được đưa vào khi liệt kê 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 mục nội dung đa phương tiện vào album và một URL cơ sở vào ảnh hồ sơ của họ.
Ví dụ:
{ "id: "media-item-id", ..., "mediaMetadata": { ... } "contributorInfo": { "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters", "displayName": "name-of-user" } }