ניתן לשתף בין משתמשים אלבומים שנוצרו על ידי האפליקציה, כאשר ניתן לאפשר להם להגיב או להוסיף פריטי מדיה משלהם לאלבום.
כדי לשתף אלבום באמצעות Google Photos Library API, האפליקציה צריכה:
- יצירת אלבום בשם המשתמש.
- להגדיר את האלבום כאלבום משותף.
היקף האימות הנדרש
כדי לשתף תוכן, האפליקציה צריכה לבקש את היקף ההרשאה photoslibrary.sharing
.
שיתוף אלבום
לפני שמשתפים אלבום, חשוב לקחת בחשבון את השיקולים הבאים:
- האפליקציה שלך יכולה לשתף רק אלבומים שהיא יצרה. לא ניתן לשתף על ידי האפליקציה שלך אלבומים שנוצרו על ידי אפליקציות אחרות, כולל Google Photos.
- כשהאפליקציה משתפת אלבום באמצעות Library API, נוצרת כתובת URL לשיתוף שכל אחד יכול להשתמש בה כדי לגשת לאלבום.
- עבור אלבומים ששותפו דרך ה-API, הבעלים של האלבום יכול להשבית את השיתוף באמצעות קישור או לבטל את השיתוף של האלבום באפליקציית Google Photos, מה שעלול למנוע מהאפליקציה לצרף משתמשים חדשים.
כדי לשתף אלבום:
- צריך לפעול לפי ההנחיות בנושא חוויית המשתמש ולקבל מהמשתמש הסכמה מפורשת ליצירת אלבום משותף.
- צור את האלבום, והקליט את
albumId
שלו. אם כבר יצרתם את האלבום, תוכלו לאחזר את הalbumId
שלו על ידי פירוט האלבומים של המשתמש. - מפעילים את
albums.share
באמצעותalbumId
הרלוונטי, יחד עם אפשרויות השיתוף שרוצים להגדיר. - מתעדים את הערך של
shareToken
בתשובה. אסימון השיתוף הוא מזהה של אלבום משותף, שאפשר להשתמש בו בחשבונות משתמשים שונים. - משתמש אחר יכול עכשיו לבצע אימות באמצעות האפליקציה, ואז join, לעזוב או לאחזר את הפרטים של האלבום המשותף באמצעות
shareToken
שלו.
אפשרויות השיתוף
אפשר להגדיר את האפשרויות הבאות כשמשתפים אלבום באמצעות הפרמטר sharedAlbumOptions
. אם האפשרויות לא מוגדרות באופן מפורש, המערכת משתמשת בערכי ברירת המחדל.
מאפיין (property) | ערך ברירת המחדל | תיאור |
---|---|---|
isCollaborative |
false |
ההגדרה הזו קובעת אם משתמשים אחרים ב-Google Photos יכולים להוסיף תוכן לאלבום המשותף. |
isCommentable |
false |
ההגדרה הזו קובעת אם משתמשים אחרים ב-Google Photos יוכלו להגיב על האלבום המשותף. |
בקשה לדוגמה
בבקשה הבאה משתפים אלבום באמצעות התקשרות אל albums.share
עם אפשרויות. המאפיין shareInfo
מוחזר בתגובה שמתאר את מאפייני השיתוף של האלבום.
REST
הנה כותרת בקשת 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 Photos. כל מי שיש לו את הקישור יכול לצפות בתוכן של האלבום, לכן צריך להתייחס אליו בזהירות. השדה אם הבעלים של |
shareToken |
אסימון שמשמש join, לעזיבה או לאחזור הפרטים של אלבום משותף מטעם משתמש שאינו הבעלים. אם הבעלים של |
isJoinable |
True אם המשתמשים יכולים להצטרף לאלבום. |
isJoined |
True אם המשתמש יצורף לאלבום. הדבר נכון תמיד
לבעלים של האלבום. |
isOwned |
True אם האלבום הוא הבעלים של האלבום. |
ביטול השיתוף של אלבום
כדי לבטל את השיתוף של אלבום שהאפליקציה שיתפה בעבר, אפשר להתקשר למספר albums.unshare
באמצעות albumId
של האלבום.
בנוסף לכך שהאלבום לא משותף יותר, יקרו הדברים הבאים:
- כל מי שאינם הבעלים יאבדו את הגישה לאלבום. נכללים בכך אנשים שהאלבום שותף איתם באופן ספציפי באמצעות אפליקציית Google Photos.
- כל התוכן שנוסף על ידי משתמשים שאינם בעלים יוסר מהאלבום.
- אם משתמש הוסיף בעבר את תוכן האלבום לספרייה שלו, התוכן יישמר בספרייה שלו.
- אסימון השיתוף וכתובת ה-URL שניתנת לשיתוף של האלבום יבוטלו.
בקשה לדוגמה
REST
הנה כותרת בקשת 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
באמצעות אסימון שיתוף תקין.
בקשה לדוגמה
REST
הנה בקשה לקבלת אלבום של 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
של האלבום הוא TRUE.
REST
זוהי הכותרת של בקשת 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
של האלבום הוא TRUE. - המשתמש שמחובר לאפליקציה הוא לא הבעלים של האלבום. כלומר, השדה
isOwned
ב-shareInfo
של האלבום הוא FALSE.
REST
הנה הכותרת של בקשת 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" } }