يمكن للمستخدمين مشاركة الألبومات التي أنشأها تطبيقك، مع توفّر خيارات للسماح بذلك. هؤلاء المستخدمين للتعليق على عناصر الوسائط الخاصة بهم أو المساهمة بها في الألبوم.
لمشاركة ألبوم من خلال واجهة برمجة التطبيقات Google Photos Library API، يجب إجراء ما يلي في تطبيقك:
- إنشاء ألبوم نيابةً عن مستخدم
- ضبط هذا الألبوم على "مشترَك"
نطاق المصادقة المطلوب
لمشاركة المحتوى، يجب أن يطلب تطبيقك photoslibrary.sharing
.
نطاق التفويض.
مشاركة ألبوم
قبل مشاركة ألبوم، يجب مراعاة الاعتبارات التالية:
- يمكن لتطبيقك مشاركة الألبومات التي أنشأها فقط. الألبومات التي أنشأتها تطبيقات أخرى بما في ذلك "صور Google"، وذلك ضمن التطبيقات التي لا يمكن مشاركتها.
- عندما يشارك تطبيقك ألبومًا عبر واجهة برمجة تطبيقات المكتبة، عنوان URL قابل للمشاركة يمكن لأي شخص استخدامه للوصول إلى الألبوم.
- بالنسبة إلى الألبومات التي تمت مشاركتها عبر واجهة برمجة التطبيقات، يمكن لمالك الألبوم إيقاف المشاركة باستخدام رابط أو إلغاء مشاركته في تطبيق "صور Google"، ما قد يحول دون مشاركة تطبيقك من انضمام مستخدمين جدد إليه.
لمشاركة ألبوم:
- اتّبِع إرشادات تجربة المستخدم الحصول على موافقة صريحة من المستخدم لإنشاء ألبوم مشترك.
- أنشئ الألبوم،
وتسجيل
albumId
. إذا كنت قد أنشأت الألبوم من قبل، يمكنك استردادalbumId
من خلال إدراج ألبومات المستخدم. - الاتصال بـ
albums.share
باستخدامalbumId
ذات الصلة، إلى جانب خيارات المشاركة التي تريد مشاركتها تعيين. - تسجيل
shareToken
قيمة في الرد. الرمز المميز للمشاركة هو معرّف لألبوم مشترك والتي يمكن استخدامها عبر حسابات مستخدمين مختلفة. - يمكن لمستخدم آخر الآن المصادقة باستخدام تطبيقك، ثم
الانضمام،
مغادرة أو
استرداد التفاصيل
من الألبوم المشترك باستخدام
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" المشترَك يمكن لأي شخص لديه الرابط على محتوى الألبوم، لذا يجب التعامل معه بعناية. لا يتم عرض الحقل يتم إبطال صلاحية |
shareToken |
يشير هذا المصطلح إلى رمز مميّز يُستخدم الانضمام، مغادرة، أو استرداد تفاصيل ألبوم مشترك نيابةً عن مستخدم ليس المالك. يتم إبطال صلاحية |
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" } }