آلبومهای ایجادشده توسط برنامهتان را میتوان بین کاربران همرسانی کرد، با گزینههایی برای اجازه دادن به آن کاربران برای نظر دادن یا افزودن فایلهای رسانهای خود به آلبوم.
برای همرسانی آلبوم ازطریق Google Photos Library API، برنامهتان باید کارهای زیر را انجام دهد:
- ایجاد آلبوم ازطرف کاربر.
- آن آلبوم را روی همرسانیشده تنظیم کنید.
محدوده اصالتسنجی الزامی
برای همرسانی محتوا، برنامهتان باید دامنه مجوز photoslibrary.sharing را درخواست کند.
همرسانی آلبوم
پیشاز همرسانی آلبوم، موارد زیر را درنظر بگیرید:
- برنامهتان فقط میتواند آلبومهایی را که خودش ایجاد کرده است همرسانی کند. آلبومهای ایجادشده توسط برنامههای دیگر، ازجمله Google Photos، نمیتوانند توسط برنامه شما همرسانی شوند.
- وقتی برنامهتان آلبومی را ازطریق Library API همرسانی میکند، نشانی وب قابل همرسانی تولید میشود که هرکسی میتواند از آن برای دسترسی به آلبوم استفاده کند.
- برای آلبومهای همرسانیشده ازطریق API، مالک آلبوم میتواند همرسانی پیوند را خاموش کند یا همرسانی آلبوم را در برنامه Google Photos لغو کند، که این کار ممکن است مانع از پیوستن کاربران جدید به آلبوم ازطریق برنامه شما شود.
برای همرسانی آلبوم:
- رهنمودهای تجربه کاربری را دنبال کنید و برای ایجاد آلبوم مشترک، موافقت صریح کاربر را دریافت کنید.
- آلبوم را ایجاد کنید،
و
albumIdآن را ضبط کنید. اگر قبلاً آلبوم را ایجاد کردهاید، میتوانیدalbumIdآن را با فهرست کردن آلبومهای کاربر بازیابی کنید. albums.shareرا بااستفاده ازalbumIdمربوطه، همراه با گزینههای همرسانی که میخواهید تنظیم کنید، فراخوانی کنید.- مقدار
shareTokenرا در پاسخ ثبت کنید. کد همرسانی شناسهای برای آلبوم مشترک است که میتوان از آن در حسابهای کاربری مختلف استفاده کرد. - اکنون کاربر دیگری میتواند با برنامه شما اصالتسنجی کند، سپس
بپیوندد،
خارج شود، یا
جزئیات
آلبوم مشترک را بااستفاده از
shareTokenآن بازیابی کند.
گزینههای همرسانی
هنگام همرسانی آلبوم بااستفاده از پارامتر
sharedAlbumOptions
میتوانید گزینههای زیر را تنظیم کنید. اگر گزینهها بهطور صریح تنظیم نشده باشند، از مقادیر پیشفرض استفاده میشود.
| دارایی | مقدار پیشفرض | شرح |
|---|---|---|
isCollaborative |
false |
تنظیم میکند که آیا سایر کاربران Google Photos میتوانند به آلبوم مشترک محتوا اضافه کنند یا نه. |
isCommentable |
false |
تنظیم میکند که آیا سایر کاربران Google Photos میتوانند در آلبوم مشترک نظر بدهند یا نه. |
درخواست نمونه
درخواست زیر آلبومی را با فراخوانی albums.share با گزینهها همرسانی میکند. یک ویژگی
shareInfo
در پاسخ برگردانده میشود که
ویژگیهای همرسانی آلبوم را توصیف میکند.
استراحت
در اینجا سرایند درخواست 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"
}
}جاوا
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 هستند. این
ویژگی هنگام همرسانی،
فهرست کردن یا
بازیابی آلبومها برگردانده میشود.
جدول زیر ویژگیهای
shareInfo
را فهرست میکند:
| مشخصات | |
|---|---|
sharedAlbumOptions |
گزینههایی که شرح میدهند آیا فردی میتواند فایلهای رسانهای را به آلبوم مشترک اضافه کند یا در آن نظر بدهد. |
shareableUrl |
پیوندی به آلبوم مشترک Google Photos. هرکسی که پیوند را داشته باشد میتواند محتوای آلبوم را ببیند، بنابراین باید بااحتیاط از آن استفاده شود. فیلد اگر مالک همرسانی پیوند را در برنامه Google Photos خاموش کند، یا اگر آلبوم لغو همرسانی شود، |
shareToken |
نشانهای که برای پیوستن، ترک کردن، یا بازیابی جزئیات آلبوم مشترک ازطرف کاربری که مالک نیست استفاده میشود. اگر مالک همرسانی پیوند را در برنامه Google Photos خاموش کند، یا اگر آلبوم لغو همرسانی شود، |
isJoinable |
True اگر کاربران بتوانند به آلبوم بپیوندند. |
isJoined |
True اگر کاربر به آلبوم پیوسته باشد. این موضوع همیشه برای مالک آلبوم صادق است. |
isOwned |
True اگر کاربر مالک آلبوم باشد. |
لغو همرسانی آلبوم
برای لغو همرسانی آلبومی که برنامهتان قبلاً همرسانی کرده است،
albums.unshare را بااستفاده از
albumId آلبوم فراخوانی کنید.
علاوهبر اینکه آلبوم دیگر همرسانی نمیشود، موارد زیر نیز اتفاق میافتد:
- همه افرادی که مالک نیستند دسترسی به آلبوم را ازدست خواهند داد. این شامل افرادی میشود که آلبوم بهطور خاص ازطریق برنامه Google Photos با آنها همرسانی شده است.
- همه محتوای اضافهشده توسط غیرمالکان از آلبوم برداشته خواهد شد.
- اگر کاربری قبلاً محتوای آلبوم را به کتابخانهاش اضافه کرده باشد، محتوا در کتابخانهاش حفظ خواهد شد.
- کد همرسانی آلبوم و نشانی وب قابل همرسانی آن نامعتبر خواهد شد.
درخواست نمونه
استراحت
در اینجا یک سرایند درخواست پست (POST) برای لغو همرسانی آلبوم آورده شده است:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:unshare Content-type: application/json Authorization: Bearer oauth2-token
بدنه درخواست باید خالی باشد.
اگر درخواست موفقیتآمیز باشد، پاسخی خالی با رمز وضعیت موفقیت HTTP برمیگرداند. اگر درخواست موفقیتآمیز نباشد، رمز وضعیت خطای HTTP را با پیام خطا برمیگرداند.
جاوا
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 }
درحال بازیابی آلبومهای مشترک و نشانهای همرسانی
جزئیات آلبوم مشترک، ازجمله کد همرسانی آن، زمانی برگردانده میشود که برنامهتان آلبومی را همرسانی کند. همچنین میتوانید بعداً این جزئیات را به روشهای زیر بازیابی کنید.
اگر کاربری که درحالحاضر به برنامه شما متصل است مالک باشد یا به آلبوم پیوسته باشد:
- با
albums.getبااستفاده ازalbumIdمربوطه. - با
albums.list، اگر فایل رسانهای در آلبوم وجود داشته باشد. - با
sharedAlbums.list، که همه آلبومهای مشترکی را که کاربر به آنها پیوسته است یا مالک آنها است برمیگرداند. برای بازیابی فقط آلبومهایی که برنامهتان ایجاد کرده است، از پارامترexcludeNonAppCreatedDataاستفاده کنید. - با
sharedAlbums.getبااستفاده از کد همرسانی.
اگر کاربری که درحالحاضر به برنامه شما متصل است به آلبوم نپیوسته باشد، میتوانید
جزئیات آلبوم مشترک را با
sharedAlbums.get بااستفاده از
یک کد همرسانی معتبر بازیابی کنید.
درخواست نمونه
استراحت
در اینجا درخواستی برای دریافت آلبوم براساس shareToken آن آورده شده است:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token
اگر درخواست موفقیتآمیز باشد، جزئیات
album
همرسانیشده را برمیگرداند.
جاوا
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 }
پیوستن به آلبوم مشترک
برنامه شما میتواند ازطرف کاربر بااستفاده از کد همرسانی آلبوم به آلبوم مشترک بپیوندد. برای انجام این کار، شرایط زیر باید برقرار باشد:
- برنامهتان آلبوم را ایجاد و همرسانی کرده است.
- کاربری که میخواهید به آلبوم بپیوندد مالک آن نیست. یعنی فیلد
isOwnedدرshareInfoآلبوم نادرست است. - کد همرسانی معتبر است.
- فیلد
isJoinableدرshareInfoآلبوم درست است.
استراحت
در اینجا سرایند درخواست POST برای پیوستن به آلبوم مشترک آمده است:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:join Content-type: application/json Authorization: Bearer oauth2-token
در متن درخواست، shareToken را مشخص کنید.
{
"shareToken": "share-token"
}درخواست POST album همرسانیشده را برمیگرداند
که برنامهتان ازطرف کاربر به آن پیوسته است.
جاوا
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 }
ترک کردن آلبوم مشترک
برنامه شما میتواند بااستفاده از کد همرسانی آلبوم، ازطرف کاربر از آلبوم مشترک خارج شود. برای انجام این کار، شرایط زیر باید برقرار باشد:
- برنامهتان آلبوم را ایجاد و همرسانی کرده است.
- کاربر درحالحاضر به آلبوم ملحق شده است. یعنی فیلد
isJoinedدرshareInfoآلبوم درست است. - کاربری که به برنامه شما متصل شده است مالک آلبوم نیست. یعنی،
فیلد
isOwnedدرshareInfoآلبوم نادرست است.
استراحت
در اینجا سرایند درخواست POST برای ترک آلبوم مشترک آمده است:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:leave Content-type: application/json Authorization: Bearer oauth2-token
در متن درخواست، shareToken را مشخص کنید.
{
"shareToken": "share-token"
}اگر درخواست موفقیتآمیز باشد، پاسخی خالی با رمز وضعیت موفقیت HTTP برمیگرداند. اگر درخواست موفقیتآمیز نباشد، رمز وضعیت خطای HTTP را با پیام خطا برمیگرداند.
جاوا
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"
}
}