แชร์สื่อ

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

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

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

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

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

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

โปรดคำนึงถึงสิ่งต่อไปนี้ก่อนที่จะแชร์อัลบั้ม

  • แอปของคุณสามารถแชร์ได้เฉพาะอัลบั้มที่แอปสร้างขึ้นเท่านั้น แอปของคุณไม่สามารถแชร์อัลบั้มที่แอปอื่นๆ รวมถึง Google Photos ได้
  • เมื่อแอปแชร์อัลบั้มผ่าน 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 หากผู้ใช้เป็นเจ้าของอัลบั้ม

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

หากต้องการเลิกแชร์อัลบั้มที่แอปของคุณแชร์ไว้ก่อนหน้านี้ ให้โทรหา 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 ของอัลบั้มเป็นค่าเท็จ
  • โทเค็นการแชร์ถูกต้อง
  • ฟิลด์ isJoinable ใน shareInfo ของอัลบั้มเป็นจริง

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"
  }
}