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