שיתוף המדיה

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

כדי לשתף אלבום באמצעות 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 הפרמטר. אם האפשרויות לא מוגדרות באופן מפורש, המערכת תשתמש בערכי ברירת המחדל.

נכס	ערך ברירת מחדל	תיאור
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 הזה מוחזר נכס בעת שיתוף, כרטיסי מוצר או מאחזר אלבומים.

הטבלה הבאה מפרטת את shareInfo נכסים:

מאפיינים
sharedAlbumOptions	אפשרויות שמתארות אם אדם יכול הוספת מדיה באלבום משותף או מגיבים עליו.
shareableUrl	קישור לאלבום המשותף ב-Google Photos. כל מי שיש לו את הקישור יכול להציג את תוכן האלבום, אז צריך להתייחס אליו בזהירות. השדה shareableUrl יוחזר רק אם האלבום כולל שיתוף באמצעות קישור מופעלת. אם משתמש מצורף כבר לאלבום אינו משותף באמצעות קישור, הוא יכול להשתמש ב-productUrl של האלבום כדי במקום זאת, shareableUrl לא תקף אם הבעלים ישבית את הקישור לשתף אותו באפליקציית Google Photos, או אם השיתוף של האלבום בוטל.
shareToken	אסימון שמשמש ל- join, leave, או לאחזר הפרטים של האלבום המשותף בשם משתמש אחר הבעלים. shareToken לא תקף אם הבעלים ישבית את הקישור לשתף אותו באפליקציית Google Photos, או אם השיתוף של האלבום בוטל.
isJoinable	True אם משתמשים יכולים להצטרף לאלבום הזה.
isJoined	True אם המשתמש מצורף לאלבום. זה תמיד נכון לבעלי האלבום.
isOwned	True אם האלבום הוא בבעלות המשתמש.

זהירות: כל מי שיש לו את shareableUrl של האלבום יכול לראות את התוכן שלו.

ביטול שיתוף של אלבום

כדי לבטל את השיתוף של אלבום שהאפליקציה שיתפה בעבר, צריך להתקשר 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
}

איך מצטרפים לאלבום משותף

האפליקציה שלך יכולה להצטרף לאלבום משותף בשם משתמש אחר כשמשתפים את האלבום ב-Assistant. כדי לעשות זאת, התנאים הבאים צריכים להתקיים:

• לאפליקציה שלך יש יצר ושיתף את אלבום.
• המשתמש שרוצים להצטרף לאלבום הוא לא הבעלים שלו. כלומר, השדה isOwned באלבום shareInfo שגוי.
• אסימון השיתוף חוקי.
• השדה isJoinable ב-shareInfo של האלבום הוא True.

זהירות: אחרי שהאפליקציה משתפת אלבום, הבעלים שלו יכולים להשבית את השיתוף באמצעות קישור או לבטל את השיתוף של האלבום באפליקציית Google Photos. במקרה כזה, תוקף אסימון השיתוף יבוטל, השדה isJoinable שלו יהיה שגוי האפליקציה לא תוכל לצרף משתמשים אליה.

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
}

איך עוזבים אלבומים משותפים

האפליקציה שלך יכולה לעזוב אלבום משותף בשם משתמש, באמצעות אחוז השיתוף של האלבום ב-Assistant. כדי לעשות זאת, התנאים הבאים צריכים להתקיים:

• האפליקציה שלך יצרה את האלבום ושיתפה אותו.
• המשתמש מצורף כרגע לאלבום. כלומר, השדה isJoined shareInfo של האלבום הוא True.
• המשתמש שמחובר לאפליקציה שלכם הוא לא הבעלים של האלבום. כלומר, השדה isOwned בשדה shareInfo של האלבום שגוי.

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 כולל את שם המשתמש שהוסיף את המדיה פריט לאלבום, base URL לפרופיל שלו תמונה.

לדוגמה:

{
  "id: "media-item-id",
  ...,
  "mediaMetadata": {
    ...
  }
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters",
    "displayName": "name-of-user"
  }
}

הערה: הנכס contributorInfo מוחזר רק אם המשתמש העניק גישה להיקף photoslibrary.sharing.