שיתוף המדיה

ניתן לשתף בין משתמשים אלבומים שנוצרו על ידי האפליקציה, כאשר ניתן לאפשר להם להגיב או להוסיף פריטי מדיה משלהם לאלבום.

כדי לשתף אלבום באמצעות Google Photos Library API, האפליקציה צריכה:

  1. יצירת אלבום בשם המשתמש.
  2. להגדיר את האלבום כאלבום משותף.

היקף האימות הנדרש

כדי לשתף תוכן, האפליקציה צריכה לבקש את היקף ההרשאה photoslibrary.sharing.

שיתוף אלבום

לפני שמשתפים אלבום, חשוב לקחת בחשבון את השיקולים הבאים:

  • האפליקציה שלך יכולה לשתף רק אלבומים שהיא יצרה. לא ניתן לשתף על ידי האפליקציה שלך אלבומים שנוצרו על ידי אפליקציות אחרות, כולל Google Photos.
  • כשהאפליקציה משתפת אלבום באמצעות Library API, נוצרת כתובת URL לשיתוף שכל אחד יכול להשתמש בה כדי לגשת לאלבום.
  • עבור אלבומים ששותפו דרך ה-API, הבעלים של האלבום יכול להשבית את השיתוף באמצעות קישור או לבטל את השיתוף של האלבום באפליקציית Google Photos, מה שעלול למנוע מהאפליקציה לצרף משתמשים חדשים.

כדי לשתף אלבום:

  1. צריך לפעול לפי ההנחיות בנושא חוויית המשתמש ולקבל מהמשתמש הסכמה מפורשת ליצירת אלבום משותף.
  2. צור את האלבום, והקליט את albumId שלו. אם כבר יצרתם את האלבום, תוכלו לאחזר את הalbumId שלו על ידי פירוט האלבומים של המשתמש.
  3. מפעילים את albums.share באמצעות albumId הרלוונטי, יחד עם אפשרויות השיתוף שרוצים להגדיר.
  4. מתעדים את הערך של shareToken בתשובה. אסימון השיתוף הוא מזהה של אלבום משותף, שאפשר להשתמש בו בחשבונות משתמשים שונים.
  5. משתמש אחר יכול עכשיו לבצע אימות באמצעות האפליקציה, ואז 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. כל מי שיש לו את הקישור יכול לצפות בתוכן של האלבום, לכן צריך להתייחס אליו בזהירות.

השדה shareableUrl מוחזר רק אם הופעל שיתוף באמצעות קישור באלבום. אם משתמש מסוים כבר צורף לאלבום שלא משותף באמצעות קישור, הוא יכול להשתמש ב-productUrl של האלבום כדי לגשת אליו.

אם הבעלים של shareableUrl השביתו את השיתוף באמצעות קישור באפליקציית תמונות Google או אם השיתוף של האלבום בוטל.
shareToken

אסימון שמשמש join, לעזיבה או לאחזור הפרטים של אלבום משותף מטעם משתמש שאינו הבעלים.

אם הבעלים של shareToken השביתו את השיתוף באמצעות קישור באפליקציית תמונות Google או אם השיתוף של האלבום בוטל.
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"
  }
}