แชร์สื่อ

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

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

โทเค็นที่ใช้ในการเข้าร่วม ออก หรือเรียกดูรายละเอียดของอัลบั้มที่แชร์ในนามของผู้ใช้ที่ไม่ใช่เจ้าของ

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 เป็น false
  • โทเค็นการแชร์ถูกต้อง
  • ช่อง 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"
  }
}