Album yang dibuat oleh aplikasi Anda dapat dibagikan antar-pengguna, dengan opsi yang memungkinkan pengguna tersebut mengomentari, atau mengontribusikan item media mereka sendiri ke album.
Untuk membagikan album melalui Google Photos Library API, aplikasi Anda perlu melakukan hal berikut:
- Membuat album atas nama pengguna.
- Setel album tersebut untuk dibagikan.
Cakupan autentikasi yang diperlukan
Untuk membagikan konten, aplikasi Anda harus meminta
cakupan otorisasi photoslibrary.sharing
.
Membagikan album
Sebelum membagikan album, pertimbangkan pertimbangan berikut:
- Aplikasi hanya dapat membagikan album yang telah dibuatnya. Album yang dibuat oleh aplikasi lain, termasuk Google Foto, tidak dapat dibagikan oleh aplikasi Anda.
- Saat aplikasi Anda membagikan album melalui Library API, URL yang dapat dibagikan akan dibuat dan dapat digunakan siapa saja untuk mengakses album tersebut.
- Untuk album yang dibagikan melalui API, pemilik album dapat menonaktifkan berbagi link atau membatalkan berbagi album di aplikasi Google Foto sehingga berpotensi mencegah aplikasi Anda bergabung dengan pengguna baru ke album tersebut.
Untuk membagikan album:
- Ikuti pedoman UX dan dapatkan izin eksplisit dari pengguna untuk membuat album bersama.
- Buat album,
dan rekam
albumId
-nya. Jika sudah membuat album, Anda dapat mengambilalbumId
-nya dengan mencantumkan album pengguna. - Panggil
albums.share
menggunakanalbumId
yang relevan, bersama dengan opsi berbagi yang ingin Anda tetapkan. - Catat nilai
shareToken
dalam respons. Token berbagi adalah ID untuk album bersama yang dapat digunakan di berbagai akun pengguna. - Pengguna lain kini dapat melakukan autentikasi dengan aplikasi Anda, lalu
join,
keluar, atau
mengambil detail
album bersama menggunakan
shareToken
-nya.
Opsi berbagi
Opsi berikut dapat disetel saat berbagi album menggunakan
parameter
sharedAlbumOptions
. Jika opsi tidak ditetapkan secara eksplisit, nilai default akan digunakan.
Properti | Nilai default | Deskripsi |
---|---|---|
isCollaborative |
false |
Menetapkan apakah pengguna Google Foto lain dapat menambahkan konten ke album bersama. |
isCommentable |
false |
Menetapkan apakah pengguna Google Foto lain dapat mengomentari album bersama. |
Contoh permintaan
Permintaan berikut membagikan album dengan memanggil albums.share
yang disertai opsi. Properti
shareInfo
ditampilkan dalam respons yang mendeskripsikan
properti berbagi album.
REST
Berikut adalah header permintaan POST untuk membagikan album:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:share Content-type: application/json Authorization: Bearer oauth2-token
Dalam isi permintaan, tentukan opsi berbagi.
{ "sharedAlbumOptions": { "isCollaborative": "true", "isCommentable": "true" } }
Permintaan ini menampilkan respons berikut:
{ "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 }
Properti album bersama
Untuk album yang telah dibuat dan dibagikan oleh aplikasi Anda, semua respons yang
menampilkan album
menyertakan properti tambahan,
shareInfo
. Properti
ini ditampilkan saat membagikan,
mencantumkan, atau
retrieving album.
Tabel berikut mencantumkan properti shareInfo
:
Properti | |
---|---|
sharedAlbumOptions |
Opsi yang menjelaskan apakah seseorang dapat menambahkan item media ke atau mengomentari album bersama. |
shareableUrl |
Link ke album Google Foto bersama. Siapa pun yang memiliki link dapat melihat konten album sehingga harus diperlakukan dengan hati-hati. Kolom
|
shareToken |
Token yang digunakan untuk join, keluar, atau mengambil detail album bersama atas nama pengguna yang bukan pemiliknya.
|
isJoinable |
True jika album dapat digabungkan oleh pengguna. |
isJoined |
True jika pengguna bergabung ke album. Hal ini selalu berlaku untuk pemilik album. |
isOwned |
True jika pengguna adalah pemilik album. |
Membatalkan berbagi album
Untuk membatalkan berbagi album yang sebelumnya telah dibagikan aplikasi Anda, panggil
albums.unshare
menggunakan
albumId
album.
Selain album yang tidak lagi dibagikan, hal-hal berikut akan terjadi:
- Semua orang yang bukan pemilik akan kehilangan akses ke album tersebut. Ini mencakup orang-orang yang telah secara khusus membagikan album kepada mereka melalui aplikasi Google Foto.
- Semua konten yang ditambahkan oleh bukan pemilik akan dihapus dari album.
- Jika pengguna sebelumnya telah menambahkan konten album ke koleksinya, konten tersebut akan dipertahankan di koleksi pengguna.
- Token berbagi album dan URL yang dapat dibagikan menjadi tidak valid.
Contoh permintaan
REST
Berikut adalah header permintaan POST untuk membatalkan berbagi album:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:unshare Content-type: application/json Authorization: Bearer oauth2-token
Isi permintaan harus kosong.
Jika berhasil, permintaan akan menampilkan respons kosong dengan kode status sukses HTTP. Jika permintaan tidak berhasil, kode status error HTTP akan ditampilkan dengan pesan error.
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 }
Mengambil album bersama dan token berbagi
Detail album bersama, termasuk token berbaginya, ditampilkan saat aplikasi Anda membagikan album. Anda juga dapat mengambil detail tersebut setelahnya dengan cara berikut.
Jika pengguna yang saat ini terhubung ke aplikasi Anda adalah pemilik, atau bergabung dengan album:
- Dengan
albums.get
menggunakanalbumId
yang relevan. - Dengan
albums.list
, jika ada item media dalam album. - Dengan
sharedAlbums.list
, yang menampilkan semua album bersama yang bergabung atau dimiliki pengguna. Untuk mengambil hanya album yang telah dibuat aplikasi Anda, gunakan parameterexcludeNonAppCreatedData
. - Dengan
sharedAlbums.get
menggunakan token berbagi.
Jika pengguna yang saat ini terhubung ke aplikasi Anda tidak digabungkan ke album, Anda dapat
mengambil detail album bersama dengan
sharedAlbums.get
menggunakan
token berbagi yang valid.
Contoh permintaan
REST
Berikut adalah permintaan untuk mendapatkan album dari shareToken
:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token
Jika permintaan berhasil, detail
album
yang dibagikan akan ditampilkan.
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 }
Bergabung dengan album bersama
Aplikasi Anda dapat bergabung dengan album bersama atas nama pengguna dengan token berbagi album. Untuk melakukannya, kondisi berikut harus terpenuhi:
- Aplikasi Anda telah membuat dan membagikan album.
- Pengguna yang ingin Anda gabungkan ke album bukan pemiliknya. Artinya, kolom
isOwned
dishareInfo
album adalah salah. - Token berbagi valid.
- Kolom
isJoinable
dishareInfo
album adalah benar (true).
REST
Berikut adalah header permintaan POST untuk bergabung dengan album bersama:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:join Content-type: application/json Authorization: Bearer oauth2-token
Dalam isi permintaan, tentukan shareToken
.
{ "shareToken": "share-token" }
Permintaan POST menampilkan album
bersama yang digabungkan dengan aplikasi Anda atas nama pengguna.
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 }
Keluar dari album bersama
Aplikasi Anda dapat keluar dari album bersama atas nama pengguna, menggunakan token berbagi album. Untuk melakukannya, kondisi berikut harus terpenuhi:
- Aplikasi Anda telah membuat dan membagikan album.
- Saat ini pengguna bergabung dengan album. Artinya, kolom
isJoined
dishareInfo
album adalah benar (true). - Pengguna yang terhubung ke aplikasi Anda bukanlah pemilik album. Artinya, kolom
isOwned
dishareInfo
album adalah salah (false).
REST
Berikut adalah header permintaan POST untuk keluar dari album bersama:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:leave Content-type: application/json Authorization: Bearer oauth2-token
Dalam isi permintaan, tentukan shareToken
.
{ "shareToken": "share-token" }
Jika berhasil, permintaan akan menampilkan respons kosong dengan kode status sukses HTTP. Jika permintaan tidak berhasil, kode status error HTTP akan ditampilkan dengan pesan error.
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 }
Properti item media bersama
Item media yang termasuk dalam
album yang dibagikan oleh aplikasi Anda berisi properti tambahan,
yaitu contributorInfo
.
Properti ini hanya disertakan saat mencantumkan
konten album bersama.
Properti contributorInfo
mencakup nama pengguna yang menambahkan item
media ke album, dan
URL dasar ke foto
profilnya.
Berikut contohnya:
{ "id: "media-item-id", ..., "mediaMetadata": { ... } "contributorInfo": { "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters", "displayName": "name-of-user" } }