مشاركة الوسائط

يمكن للمستخدمين مشاركة الألبومات التي أنشأها تطبيقك، مع توفّر خيارات للسماح بذلك. هؤلاء المستخدمين للتعليق على عناصر الوسائط الخاصة بهم أو المساهمة بها في الألبوم.

لمشاركة ألبوم من خلال واجهة برمجة التطبيقات Google Photos Library API، يجب إجراء ما يلي في تطبيقك:

  1. إنشاء ألبوم نيابةً عن مستخدم
  2. ضبط هذا الألبوم على "مشترَك"

نطاق المصادقة المطلوب

لمشاركة المحتوى، يجب أن يطلب تطبيقك photoslibrary.sharing. نطاق التفويض.

مشاركة ألبوم

قبل مشاركة ألبوم، يجب مراعاة الاعتبارات التالية:

  • يمكن لتطبيقك مشاركة الألبومات التي أنشأها فقط. الألبومات التي أنشأتها تطبيقات أخرى بما في ذلك "صور Google"، وذلك ضمن التطبيقات التي لا يمكن مشاركتها.
  • عندما يشارك تطبيقك ألبومًا عبر واجهة برمجة تطبيقات المكتبة، عنوان URL قابل للمشاركة يمكن لأي شخص استخدامه للوصول إلى الألبوم.
  • بالنسبة إلى الألبومات التي تمت مشاركتها عبر واجهة برمجة التطبيقات، يمكن لمالك الألبوم إيقاف المشاركة باستخدام رابط أو إلغاء مشاركته في تطبيق "صور Google"، ما قد يحول دون مشاركة تطبيقك من انضمام مستخدمين جدد إليه.

لمشاركة ألبوم:

  1. اتّبِع إرشادات تجربة المستخدم الحصول على موافقة صريحة من المستخدم لإنشاء ألبوم مشترك.
  2. أنشئ الألبوم، وتسجيل albumId. إذا كنت قد أنشأت الألبوم من قبل، يمكنك استرداد albumId من خلال إدراج ألبومات المستخدم.
  3. الاتصال بـ albums.share باستخدام albumId ذات الصلة، إلى جانب خيارات المشاركة التي تريد مشاركتها تعيين.
  4. تسجيل shareToken قيمة في الرد. الرمز المميز للمشاركة هو معرّف لألبوم مشترك والتي يمكن استخدامها عبر حسابات مستخدمين مختلفة.
  5. يمكن لمستخدم آخر الآن المصادقة باستخدام تطبيقك، ثم الانضمام، مغادرة أو استرداد التفاصيل من الألبوم المشترك باستخدام shareToken.

خيارات المشاركة

يمكن تعيين الخيارات التالية عند مشاركة ألبوم باستخدام sharedAlbumOptions . إذا لم يتم ضبط الخيارات بشكل صريح، سيتم استخدام القيم التلقائية.

الموقع القيمة التلقائية الوصف
isCollaborative false لضبط ما إذا كان يمكن لمستخدمي "صور Google" الآخرين إضافة محتوى إلى ألبوم مشترك.
isCommentable false لتعيين ما إذا كان يمكن لمستخدمي صور Google الآخرين التعليق على ألبوم مشترك.

مثال على الطلب

يشارك الطلب التالي ألبومًا من خلال الاتصال بـ 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"
  }
}

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
}

خصائص الألبومات المشتركة

بالنسبة إلى الألبومات التي أنشأها التطبيق وشاركها، ستكون كل الردود التي إرجاع album تضمين خاصية إضافية، shareInfo هذا النمط عند المشاركة، بطاقة بيانات أو جارٍ استرداد الألبومات.

يسرد الجدول التالي shareInfo المواقع:

أماكن إقامة
sharedAlbumOptions الخيارات التي تصف ما إذا كان يمكن لشخص ما إضافة وسائط العناصر في ألبوم مشترَك أو التعليق عليه.
shareableUrl

رابط إلى ألبوم "صور Google" المشترَك يمكن لأي شخص لديه الرابط على محتوى الألبوم، لذا يجب التعامل معه بعناية.

لا يتم عرض الحقل shareableUrl إلا إذا كان الألبوم يمتلك المشاركة باستخدام رابط مفعَّلة. إذا سبق أن انضم مستخدم إلى ألبوم لا تتم مشاركته باستخدام رابط، فيمكنهم استخدام productUrl للألبوم من أجل الوصول إليه بدلاً من ذلك.

يتم إبطال صلاحية shareableUrl في حال إيقاف المالك الرابط. مشاركته في تطبيق "صور Google" أو في حال إلغاء مشاركة الألبوم.

shareToken

يشير هذا المصطلح إلى رمز مميّز يُستخدم الانضمام، مغادرة، أو استرداد تفاصيل ألبوم مشترك نيابةً عن مستخدم ليس المالك.

يتم إبطال صلاحية shareToken في حال إيقاف المالك الرابط. مشاركته في تطبيق "صور Google" أو في حال إلغاء مشاركة الألبوم.

isJoinable True إذا كان بإمكان المستخدمين الانضمام إلى الألبوم
isJoined True إذا كان المستخدم عضوًا في الألبوم. هذا دائمًا ما صحيح لمالك الألبوم.
isOwned True إذا كان المستخدم يملك الألبوم.

إلغاء مشاركة ألبوم

لإلغاء مشاركة ألبوم شاركه تطبيقك سابقًا، يُرجى الاتصال albums.unshare باستخدام albumId الخاص بالألبوم.

بالإضافة إلى إيقاف مشاركة الألبوم، سيتم اتخاذ الإجراءات التالية: الحدوث:

  • سيفقد جميع غير المالكين إمكانية الوصول إلى الألبوم. وهذا يشمل الأشخاص الذين لديهم تَمَّ تَشْغِيلْ أَلْبُومْ التي تمّت مشاركتها على وجه التحديد معهم من خلال تطبيق صور Google.
  • وستتم إزالة كل المحتوى الذي أضافه غير المالكين من الألبوم.
  • إذا سبق لمستخدم إضافة محتوى الألبوم إلى مكتبته، فسيتم المحتوى في مكتبتهم.
  • سيتم إلغاء صلاحية الرمز المميز لمشاركة الألبوم وعنوان URL القابل للمشاركة.

مثال على الطلب

راحة

إليك عنوان طلب POST لإلغاء مشاركة ألبوم:

POST https://photoslibrary.googleapis.com/v1/albums/album-id:unshare
Content-type: application/json
Authorization: Bearer oauth2-token

يجب أن يكون نص الطلب فارغًا.

إذا نجح الطلب، فإنه يعرض استجابة فارغة مع HTTP رمز حالة النجاح. إذا لم ينجح الطلب، فسيعرض HTTP رمز حالة خطأ مع رسالة خطأ.

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
}

استرداد الألبومات المشتركة ومشاركة الرموز المميزة

تفاصيل ألبوم مشترك، بما في ذلك الرمز المميّز للمشاركة، عندما يشارك التطبيق ألبومًا. يمكنك أيضًا استرداد هذه التفاصيل بعد ذلك بالطرق التالية.

إذا كان المستخدم المرتبط حاليًا بتطبيقك هو المالك أو منضمًا إلى التطبيق ألبوم:

  • من خلال استخدام albums.get albumId ذات الصلة.
  • مع albums.list، إذا كانت هناك هي عناصر وسائط في الألبوم.
  • مع sharedAlbums.list، الذي يعرض جميع الألبومات المشتركة التي انضم إليها المستخدم أو يملكها لاسترداد للألبومات التي أنشأها تطبيقك فقط، فاستخدم excludeNonAppCreatedData .
  • مع sharedAlbums.get باستخدام رمز المشاركة.

إذا لم يكن المستخدم المرتبط حاليًا بتطبيقك منضمًا إلى الألبوم، يمكنك: لاسترداد تفاصيل ألبوم مشترك باستخدام sharedAlbums.get باستخدام رمز مشاركة صالح.

مثال على الطلب

راحة

إليك طلب للحصول على ألبوم من shareToken:

GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token

وإذا نجح الطلب، فسيتم عرض النموذج المشترك album التفاصيل.

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
}

الانضمام إلى ألبوم مشترَك

يمكن لتطبيقك الانضمام إلى ألبوم مشترَك نيابةً عن مستخدم باستخدام مشاركة الألبوم. الرمز المميز. لإجراء ذلك، يجب استيفاء الشروط التالية:

  • يتضمن تطبيقك أنشأ وشارك الألبوم.
  • إنّ المستخدم الذي تريد الانضمام إلى الألبوم ليس مالكه. وهي أن حقل isOwned في الألبوم shareInfo هو false.
  • الرمز المميّز للمشاركة صالح.
  • الحقل 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 الذي تمت مشاركته. انضمّ تطبيقك بالنيابة عن المستخدم.

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
}

جارٍ مغادرة ألبوم مشترَك

يمكن لتطبيقك مغادرة ألبوم مشترَك نيابةً عن المستخدم، وذلك باستخدام خيار مشاركة الألبوم. الرمز المميز. لإجراء ذلك، يجب استيفاء الشروط التالية:

  • أنشأ تطبيقك الألبوم وشاركه.
  • المستخدم منضم حاليًا إلى الألبوم. وهذا يعني أنّ الحقل 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 رمز حالة خطأ مع رسالة خطأ.

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
}

خصائص عنصر الوسائط المشتركة

عناصر الوسائط التي تنتمي إلى تحتوي الألبومات التي شاركها تطبيقك على خاصية إضافية، contributorInfo ولا يتم تضمين هذه السمة إلا عند إدراج لمحتوى ألبوم مشترَك.

تتضمّن السمة contributorInfo اسم المستخدم الذي أضاف الوسائط. عنصر واحد إلى الألبوم عنوان URL الأساسي لملفه الشخصي .

وفي ما يلي مثال لذلك:

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