رسانه را به اشتراک بگذارید

آلبوم‌های ایجاد شده توسط برنامه شما را می‌توان بین کاربران به اشتراک گذاشت، با گزینه‌هایی که به آن کاربران اجازه می‌دهد درباره آنها نظر بدهند یا موارد رسانه‌ای خود را در آلبوم مشارکت دهند.

برای اشتراک‌گذاری یک آلبوم از طریق Google Photos Library API، برنامه شما باید کارهای زیر را انجام دهد:

1. یک آلبوم از طرف یک کاربر ایجاد کنید .
2. آن آلبوم را به اشتراک گذاشته شده تنظیم کنید .

توجه: قبل از اشتراک‌گذاری آلبوم، رضایت صریح کاربر را دریافت کنید و حتماً دستورالعمل‌های UX را دنبال کنید.

محدوده احراز هویت مورد نیاز

برای اشتراک‌گذاری محتوا، برنامه شما باید محدوده مجوز photoslibrary.sharing را درخواست کند.

به اشتراک گذاری یک آلبوم

قبل از اشتراک‌گذاری آلبوم، نکات زیر را در نظر بگیرید:

• برنامه شما فقط می‌تواند آلبوم‌هایی را که ایجاد کرده به اشتراک بگذارد. آلبوم‌های ایجاد شده توسط سایر برنامه‌ها، از جمله Google Photos، توسط برنامه شما قابل اشتراک‌گذاری نیست.
• هنگامی که برنامه شما یک آلبوم را از طریق کتابخانه API به اشتراک می گذارد، یک URL قابل اشتراک ایجاد می شود که همه می توانند از آن برای دسترسی به آلبوم استفاده کنند.
• برای آلبوم‌هایی که از طریق API به اشتراک گذاشته می‌شوند، مالک آلبوم می‌تواند اشتراک‌گذاری پیوند را غیرفعال کند یا آلبوم را در برنامه Google Photos لغو اشتراک‌گذاری کند، و به طور بالقوه مانع از پیوستن کاربران جدید برنامه شما به آن می‌شود.

برای به اشتراک گذاشتن یک آلبوم:

1. دستورالعمل های UX را دنبال کنید و رضایت صریح کاربر را برای ایجاد یک آلبوم مشترک دریافت کنید.
2. آلبوم را ایجاد کنید و albumId آن را ضبط کنید. اگر قبلاً آلبوم را ایجاد کرده‌اید، می‌توانید با فهرست کردن آلبوم‌های کاربر albumId آن را بازیابی کنید.
3. با استفاده از albumId مربوطه به همراه گزینه‌های اشتراک‌گذاری که می‌خواهید تنظیم کنید، با albums.share تماس بگیرید.
4. مقدار shareToken را در پاسخ ثبت کنید. نشانه اشتراک‌گذاری یک شناسه برای یک آلبوم مشترک است که می‌تواند در حساب‌های کاربری مختلف استفاده شود.
5. کاربر دیگری اکنون می‌تواند با برنامه شما احراز هویت کند، سپس با استفاده از 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. هر کسی که پیوند را داشته باشد می تواند محتویات آلبوم را مشاهده کند، بنابراین باید با احتیاط رفتار شود. قسمت shareableUrl تنها در صورتی برگردانده می‌شود که اشتراک‌گذاری پیوند در آلبوم روشن باشد. اگر کاربر قبلاً به آلبومی ملحق شده است که پیوند به اشتراک گذاشته نشده است، می‌تواند از productUrl آلبوم برای دسترسی به آن استفاده کند. اگر مالک اشتراک‌گذاری پیوند را در برنامه Google Photos غیرفعال کند، یا اگر آلبوم به اشتراک گذاشته نشود shareableUrl باطل می‌شود.
shareToken	رمزی که برای پیوستن ، خروج ، یا بازیابی جزئیات یک آلبوم مشترک از طرف کاربری که مالک نیست استفاده می‌شود. اگر مالک اشتراک‌گذاری پیوند را در برنامه Google Photos غیرفعال کند، یا اگر آلبوم به اشتراک گذاشته نشود، shareToken باطل می‌شود.
isJoinable	True اگر کاربران بتوانند به آلبوم ملحق شوند.
isJoined	True اگر کاربر به آلبوم ملحق شده باشد. این همیشه برای صاحب آلبوم صادق است.
isOwned	True اگر کاربر مالک آلبوم باشد.

احتیاط: هرکسی که دارای shareableUrl آلبوم باشد می‌تواند محتویات آلبوم را مشاهده کند.

لغو اشتراک‌گذاری آلبوم

برای لغو اشتراک‌گذاری آلبومی که برنامه شما قبلاً به اشتراک گذاشته است، با استفاده از albumId آلبوم آلبوم با albums.unshare تماس بگیرید.

علاوه بر این که آلبوم دیگر به اشتراک گذاشته نمی شود، موارد زیر رخ خواهد داد:

• همه افراد غیر مالک دسترسی به آلبوم را از دست خواهند داد. این شامل افرادی می شود که آلبوم را به طور خاص از طریق برنامه 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 آلبوم درست است.

احتیاط: پس از اینکه برنامه شما آلبومی را به اشتراک گذاشت، مالک آن می‌تواند اشتراک‌گذاری پیوند را غیرفعال کند یا آلبوم را در برنامه Google Photos لغو اشتراک‌گذاری کند. اگر این اتفاق بیفتد، توکن اشتراک آلبوم باطل می‌شود، قسمت isJoinable آن نادرست است و برنامه شما نمی‌تواند کاربران را به آن ملحق کند.

باقی مانده

در اینجا یک هدر درخواست 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 شامل نام کاربری است که آیتم رسانه ای را به آلبوم اضافه کرده است و یک URL پایه به تصویر نمایه خود.

در اینجا یک مثال است:

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

توجه: ویژگی contributorInfo تنها در صورتی برگردانده می‌شود که کاربر اجازه دسترسی به محدوده photoslibrary.sharing را داده باشد.