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:
- Tạo album thay mặt cho 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. 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:
- 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ẻ.
- Tạo album,
và ghi lại
albumId
. Nếu đã tạo album, bạn có thể truy xuấtalbumId
bằng cách liệt kê album của người dùng. - Gọi
albums.share
bằngalbumId
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. - 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. - 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
|
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.
|
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. |
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ứcalbumId
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ụngexcludeNonAppCreatedData
. - 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 albumshareInfo
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 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
trongshareInfo
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
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 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" } }