แชร์สื่อ

ผู้ใช้สามารถแชร์อัลบั้มที่สร้างโดยแอปของคุณ พร้อมตัวเลือกในการอนุญาตให้ผู้ใช้แสดงความคิดเห็นหรือร่วมส่งรายการสื่อของตนเองลงในอัลบั้ม

หากต้องการแชร์อัลบั้มผ่าน Google Photos Library API แอปของคุณต้องดำเนินการดังนี้

1. สร้างอัลบั้มในนามของผู้ใช้
2. ตั้งค่าให้แชร์อัลบั้มนั้น

หมายเหตุ: ก่อนแชร์อัลบั้ม โปรดขอความยินยอมอย่างชัดแจ้งจากผู้ใช้ และทำตามหลักเกณฑ์ด้าน UX

ขอบเขตการตรวจสอบสิทธิ์ที่จำเป็น

หากต้องการแชร์เนื้อหา แอปของคุณต้องขอphotoslibrary.sharing ขอบเขตการให้สิทธิ์

การแชร์อัลบั้ม

ก่อนที่จะแชร์อัลบั้ม โปรดพิจารณาสิ่งต่อไปนี้

• แอปของคุณแชร์ได้เฉพาะอัลบั้มที่แอปสร้างขึ้นเท่านั้น อัลบั้มที่สร้างโดยแอปอื่นๆ รวมถึง Google รูปภาพ จะไม่สามารถแชร์โดยแอปของคุณ
• เมื่อแอปแชร์อัลบั้มผ่าน Library API ระบบจะสร้าง URL ที่แชร์ได้ซึ่งทุกคนใช้เพื่อเข้าถึงอัลบั้มได้
• สำหรับอัลบั้มที่แชร์ผ่าน API เจ้าของอัลบั้มสามารถ ปิดการแชร์ลิงก์ หรือเลิกแชร์อัลบั้มในแอป Google Photos ซึ่งอาจทำให้แอปของคุณ เข้าร่วมกับผู้ใช้ใหม่ได้

วิธีแชร์อัลบั้ม

1. ทำตามหลักเกณฑ์ UX และขอความยินยอมอย่างชัดแจ้งจากผู้ใช้เพื่อสร้างอัลบั้มที่แชร์
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 พร็อพเพอร์ตี้นี้จะส่งคืนเมื่อแชร์ รายการ หรือretrievingอัลบั้ม

ตารางต่อไปนี้แสดงพร็อพเพอร์ตี้ shareInfo

พร็อพเพอร์ตี้
sharedAlbumOptions	ตัวเลือกที่อธิบายว่าผู้ใช้จะเพิ่มรายการสื่อในหรือแสดงความคิดเห็นในอัลบั้มที่แชร์ได้หรือไม่
shareableUrl	ลิงก์ไปยังอัลบั้ม Google Photos ที่แชร์ ทุกคนที่มีลิงก์จะดูเนื้อหาของอัลบั้มได้ คุณควรดำเนินการด้วยความระมัดระวัง ระบบจะแสดงช่อง shareableUrl ก็ต่อเมื่อเปิดการแชร์ลิงก์อัลบั้มไว้เท่านั้น หากผู้ใช้เข้าร่วมอัลบั้มที่ไม่ได้แชร์ลิงก์แล้ว ผู้ใช้จะใช้ productUrl ของอัลบั้มเพื่อเข้าถึงอัลบั้มนั้นได้แทน shareableUrl จะใช้ไม่ได้หากเจ้าของปิด การแชร์ลิงก์ในแอป Google Photos หรือหากเลิกแชร์อัลบั้ม
shareToken	โทเค็นที่จะใช้เพื่อjoin ออก หรือเรียกรายละเอียดของอัลบั้มที่แชร์ในนามของผู้ใช้ที่ไม่ใช่เจ้าของ shareToken จะใช้ไม่ได้หากเจ้าของปิด การแชร์ลิงก์ในแอป Google Photos หรือหากเลิกแชร์อัลบั้ม
isJoinable	True หากผู้ใช้สามารถเข้าร่วมอัลบั้มได้
isJoined	True หากผู้ใช้เข้าร่วมอัลบั้ม สำหรับเจ้าของอัลบั้ม การดำเนินการดังกล่าวจะเป็นเช่นนี้เสมอ
isOwned	True หากผู้ใช้เป็นเจ้าของอัลบั้ม

ข้อควรระวัง: ทุกคนที่มี shareableUrl ของอัลบั้มจะสามารถดูเนื้อหาของอัลบั้มได้

ยกเลิกการแชร์อัลบั้ม

หากต้องการเลิกแชร์อัลบั้มที่แอปของคุณแชร์ไว้ก่อนหน้านี้ ให้โทรหา albums.unshare โดยใช้ albumId ของอัลบั้ม

นอกจากอัลบั้มจะไม่แชร์อีกต่อไปแล้ว สิ่งต่อไปนี้จะเกิดขึ้นด้วย

• ผู้ที่ไม่ใช่เจ้าของทุกคนจะสูญเสียสิทธิ์เข้าถึงอัลบั้ม ซึ่งรวมถึงผู้ที่เคยแชร์อัลบั้มกับตนผ่านแอป Google รูปภาพโดยเฉพาะด้วย
• เนื้อหาทั้งหมดที่เพิ่มเข้ามาโดยผู้ที่ไม่ใช่เจ้าของจะถูกนำออกจากอัลบั้ม
• หากผู้ใช้เพิ่มเนื้อหาของอัลบั้มลงในคลังเพลงแล้วก่อนหน้านี้ เนื้อหาจะยังคงอยู่ในคลังเพลงของผู้ใช้
• โทเค็นการแชร์ของอัลบั้มและ 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 ของอัลบั้มนั้นเป็นเท็จ
• โทเค็นการแชร์ถูกต้อง
• ฟิลด์ isJoinable ใน shareInfo ของอัลบั้มเป็นจริง

ข้อควรระวัง: หลังจากที่แอปของคุณแชร์อัลบั้มแล้ว เจ้าของสามารถปิดการแชร์ลิงก์หรือเลิกแชร์อัลบั้มในแอป 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
}

กำลังออกจากอัลบั้มที่แชร์

แอปของคุณสามารถออกจากอัลบั้มที่แชร์ในนามของผู้ใช้ได้โดยใช้โทเค็นการแชร์ของอัลบั้ม โดยเงื่อนไขต่อไปนี้ต้องเป็นจริง

• แอปของคุณสร้างและแชร์อัลบั้มแล้ว
• ขณะนี้ผู้ใช้เข้าร่วมอัลบั้มแล้ว นั่นคือ ช่อง isJoined ใน shareInfo ของอัลบั้มเป็นความจริง
• ผู้ใช้ที่เชื่อมต่อกับแอปของคุณไม่ใช่เจ้าของอัลบั้ม ซึ่งก็คือช่อง 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 ประกอบด้วยชื่อของผู้ใช้ที่เพิ่มรายการสื่อในอัลบั้มและ URL ฐานไปยังรูปโปรไฟล์ของผู้ใช้

ตัวอย่าง

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

หมายเหตุ: ระบบจะแสดงผลพร็อพเพอร์ตี้ contributorInfo หากผู้ใช้ได้ให้สิทธิ์เข้าถึงขอบเขต photoslibrary.sharing เท่านั้น