您正在查看 Google Photos Library API 的旧版文档。

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

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

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

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

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

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

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

برای لغو اشتراک‌گذاری آلبومی که برنامه شما قبلاً به اشتراک گذاشته است، با استفاده از 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 آلبوم درست است.

استراحت

در اینجا یک هدر درخواست 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"
}

جاوا

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"
  }
}

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

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

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

گزینه های اشتراک گذاری

درخواست نمونه

استراحت

جاوا

PHP

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

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

درخواست نمونه

استراحت

جاوا

PHP

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

درخواست نمونه

استراحت

جاوا

PHP

پیوستن به یک آلبوم مشترک

استراحت

جاوا

PHP

ترک یک آلبوم مشترک

استراحت

جاوا

PHP

ویژگی های مورد رسانه مشترک