تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

أنشئ ألبومًا نيابةً عن أحد المستخدمين.
ضبط هذا الألبوم على "مشترك"

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

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

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

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

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

اتّبِع إرشادات تجربة المستخدم واحصل على موافقة صريحة من المستخدم لإنشاء ألبوم مشترك.
أنشئ الألبوم وسجّل albumId له. إذا كنت قد أنشأت الألبوم من قبل، يمكنك استرداد albumId الخاص به من خلال إدراج ألبومات المستخدم.
يمكنك الاتصال بـ albums.share باستخدام albumId ذي الصلة، إلى جانب خيارات المشاركة التي تريد ضبطها.
سجِّل قيمة shareToken في الرد. الرمز المميز للمشاركة هو معرف لألبوم مشترك يمكن استخدامه عبر حسابات مستخدمين مختلفة.
يمكن لمستخدم آخر الآن المصادقة باستخدام تطبيقك، ثم join أو مغادرته أو استرداد تفاصيل الألبوم المشترَك باستخدام 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. يتم إرجاع هذه الخاصية عند مشاركة الألبومات أو إدراجها أو retrieving.

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

أماكن إقامة
`sharedAlbumOptions`	خيارات تصف ما إذا كان بإمكان أحد المستخدمين إضافة عناصر وسائط إلى ألبوم مشترك أو التعليق عليه.
`shareableUrl`	رابط يؤدي إلى ألبوم "صور Google" المشترك ويمكن لأي شخص لديه الرابط الاطّلاع على محتوى الألبوم، لذا يجب التعامل معه بحرص. لا يتم عرض الحقل `shareableUrl` إلا إذا تم تفعيل ميزة "المشاركة باستخدام رابط" في الألبوم. وإذا سبق أن انضم مستخدم إلى ألبوم غير مشترَك باستخدام رابط، يمكنه استخدام `productUrl` الخاص بالألبوم للوصول إليه بدلاً من ذلك. يتم إبطال صلاحية `shareableUrl` إذا أوقف المالك ميزة "المشاركة باستخدام رابط" في تطبيق "صور Google" أو إذا تم إلغاء مشاركة الألبوم.
`shareToken`	يشير هذا المصطلح إلى رمز مميّز يُستخدم join إلى ألبوم مشترَك أو مغادرته أو استرداد تفاصيله نيابةً عن مستخدم آخر. يتم إبطال صلاحية `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 الألبوم هو خطأ.
الرمز المميز للمشاركة صالح.
الحقل 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"
}

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

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

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

مشاركة ألبوم

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

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

راحة

Java

PHP

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

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

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

راحة

Java

PHP

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

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

راحة

Java

PHP

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

راحة

Java

PHP

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

راحة

Java

PHP

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