هم‌رسانی کردن رسانه

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

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

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

محدوده اصالت‌سنجی الزامی

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

هم‌رسانی آلبوم

پیش‌از هم‌رسانی آلبوم، موارد زیر را درنظر بگیرید:

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

برای هم‌رسانی آلبوم:

  1. رهنمودهای تجربه کاربری را دنبال کنید و برای ایجاد آلبوم مشترک، موافقت صریح کاربر را دریافت کنید.
  2. آلبوم را ایجاد کنید، و albumId آن را ضبط کنید. اگر قبلاً آلبوم را ایجاد کرده‌اید، می‌توانید albumId آن را با فهرست کردن آلبوم‌های کاربر بازیابی کنید.
  3. albums.share را بااستفاده از albumId مربوطه، همراه با گزینه‌های هم‌رسانی که می‌خواهید تنظیم کنید، فراخوانی کنید.
  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 اگر کاربر مالک آلبوم باشد.

لغو هم‌رسانی آلبوم

برای لغو هم‌رسانی آلبومی که برنامه‌تان قبلاً هم‌رسانی کرده است، 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"
  }
}