แสดงเนื้อหาในคลัง อัลบั้ม และรายการในสื่อ

ขอบเขตการให้สิทธิ์ที่จําเป็น

Google Photos Library API มีขอบเขตหลายอย่างในการเข้าถึงรายการสื่อและอัลบั้ม รายการสื่อที่แสดงกลับมาจากการโทรแต่ละครั้งจะแตกต่างกันตามขอบเขตที่นักพัฒนาแอปขอ

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

ภาพรวม

การใช้งาน API ที่สําคัญคือการแสดงรายการสื่อที่ผู้ใช้สํารองข้อมูลไว้ใน Google Photos รายการในอัลบั้มหนึ่งๆ หรือจากคลังภาพทั้งหมดของผู้ใช้ (มุมมองเริ่มต้นในแอป Google Photos) จะแสดงได้

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

การแสดงเนื้อหาในคลังและอัลบั้มจะแสดงรายการสื่อ ใส่ข้อความที่อยู่ในอัลบั้ม รวมอยู่ #39 รายการสื่ออธิบายรูปภาพ วิดีโอ หรือสื่ออื่นๆ mediaItem จะมีลิงก์โดยตรงไปยังสินค้า ลิงก์ไปยังรายการใน Google Photos และข้อมูลเมตาอื่นๆ ที่เกี่ยวข้อง โปรดดูข้อมูลเพิ่มเติมที่หัวข้อเข้าถึงรายการสื่อและ mediaItems

ข้อควรระวัง: อย่าแคชรูปภาพและวิดีโอของผู้ใช้ แต่ให้จัดเก็บรายการสื่อ id และขอรายละเอียดอีกครั้งเมื่อต้องการ รูปภาพอาจมีการเปลี่ยนแปลง และสิทธิ์เข้าถึง โดยตรงผ่าน baseUrl จะหมดอายุหลังจากผ่านไป 60 นาที โปรดดูข้อมูลเพิ่มเติมที่หัวข้อเข้าถึงรายการสื่อ

อัลบั้มรายชื่อ

คุณสามารถเรียกรายการอัลบั้มของผู้ใช้ได้โดยใช้ albums.list

REST

ตัวอย่างคําขอมีดังนี้

GET https://photoslibrary.googleapis.com/v1/albums

คําขอจะแสดงผลลัพธ์ต่อไปนี้

{
  "albums": [
    {
      "id": "album-id",
      "title": "album-title",
      "productUrl": "album-product-url",
      "coverPhotoBaseUrl": "album-cover-base-url_do-not-use-directly",
      "coverPhotoMediaItemId": "album-cover-media-item-id",
      "isWriteable": "whether-you-can-write-to-this-album",
      "mediaItemsCount": "number-of-media-items-in-album"
    },
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all albums in the user's library
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums();

  for (Album album : response.iterateAll()) {
    // Get some properties of an album
    String id = album.getId();
    String title = album.getTitle();
    String productUrl = album.getProductUrl();
    String coverPhotoBaseUrl = album.getCoverPhotoBaseUrl();
    // The cover photo media item id field may be empty
    String coverPhotoMediaItemId = album.getCoverPhotoMediaItemId();
    boolean isWritable = album.getIsWriteable();
    long mediaItemsCount = album.getMediaItemsCount();
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums in the user's library
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // Get some properties of an album
        $albumId = $album->getId();
        $title = $album->getTitle();
        $productUrl = $album->getProductUrl();
        $coverPhotoBaseUrl = $album->getCoverPhotoBaseUrl();
        // The cover photo media item id field may be empty
        $coverPhotoMediaItemId = $album->getCoverPhotoMediaItemId();
        $isWriteable = $album->getIsWriteable();
        $totalMediaItems = $album->getTotalMediaItems();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

อัลบั้มที่แสดงผลแต่ละอัลบั้มจะมีรหัสที่ใช้ในการดึงเนื้อหาของอัลบั้มตามที่แสดงในการแสดงเนื้อหาอัลบั้ม รวมถึงชื่อและจํานวนสื่อที่มีอยู่ในนั้น

productUrl จะชี้ไปที่อัลบั้มใน Google Photos ซึ่งผู้ใช้จะเปิดได้

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

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

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

• ผู้ที่สร้างอัลบั้ม
• มีการแชร์หรือไม่
• ขอบเขตที่ผู้ใช้อนุมัติ

การตั้งค่าสถานะนี้อาจเปลี่ยนแปลงหากเกณฑ์ข้อใดข้อหนึ่งเหล่านี้มีการเปลี่ยนแปลง โปรดดูรายละเอียดเพิ่มเติมที่หัวข้อสร้างอัลบั้ม โดยการตอบกลับจะมี nextPageToken รวมอยู่ด้วย ดูข้อมูลเพิ่มเติมได้ในการใส่เลขหน้า

การตอบกลับสําหรับอัลบั้มที่ว่างเปล่าจะแตกต่างกันไป กล่าวคือ mediaItemsCount และ coverPhotoMediaItemId จะตั้งค่าเป็น 0 ตามค่าเริ่มต้น และไม่มีการตอบกลับในการตอบสนอง REST และโปรดทราบว่า coverPhotoBaseUrl ชี้ไปยังรูปภาพตัวยึดตําแหน่งเริ่มต้น

เนื้อหาในคลังภาพ

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

หากต้องการเรียกรายการสื่อ ให้เรียก mediaItems.list

REST

ตัวอย่างคําขอมีดังนี้

GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
}

คําขอ GET ส่งคืนการตอบกลับต่อไปนี้:

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all media items in the user's library
  // Iterate over all the retrieved media items
  // Pagination is handled automatically
  ListMediaItemsPagedResponse response = photosLibraryClient.listMediaItems();
  for (MediaItem item : response.iterateAll()) {
    // Get some properties of a media item
    String id = item.getId();
    String description = item.getDescription();
    String mimeType = item.getMimeType();
    String productUrl = item.getProductUrl();
    String filename = item.getFilename();
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all media items in the user's library
    // Iterate over all the retrieved media items
    // Pagination is handled automatically
    $response = $photosLibraryClient->listMediaItems();
    foreach ($response->iterateAllElements() as $item) {
        // Get some properties of a media item
        /* @var $item \Google\Photos\Library\V1\MediaItem */
        $id = $item->getId();
        $description = $item->getDescription();
        $mimeType = $item->getMimeType();
        $productUrl = $item->getProductUrl();
        $filename = $item->getFilename();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

การตอบกลับจะประกอบด้วยรายการสื่อที่เรียงลําดับจากล่าสุดถึงล่าสุด ดูข้อมูลเพิ่มเติมได้ที่ mediaItems และยังมีnextPageTokenซึ่งมีคําอธิบายรายละเอียดเพิ่มเติมในการใส่เลขหน้า

แสดงเนื้อหาอัลบั้ม

หากต้องการแสดงรายการสื่อทั้งหมดในอัลบั้ม ให้เพิ่มช่อง albumId ลงในคําขอการค้นหา ดูข้อมูลเพิ่มเติมเกี่ยวกับ albumId ได้ที่การแสดงอัลบั้มและการแสดงอัลบั้มที่แชร์ หาก albumId ไม่ถูกต้อง ระบบจะแสดงข้อผิดพลาด Bad Request หากรหัสถูกต้องแต่อัลบั้มไม่มีผู้ใช้ที่ตรวจสอบสิทธิ์แล้ว ระบบจะแสดงข้อผิดพลาด Not Found ดูรายละเอียดเพิ่มเติมเกี่ยวกับการจัดการข้อผิดพลาดได้ที่เคล็ดลับประสิทธิภาพและแนวทางปฏิบัติแนะนํา

REST

ตัวอย่างคําขอมีดังนี้

POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
  "albumId": "album-id"
}

คําขอ POST จะแสดงผลการตอบกลับต่อไปนี้

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all media items in an album
  // Provide the ID of the album as a parameter in the searchMediaItems call
  // Iterate over all the retrieved media items
  SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(albumId);

  for (MediaItem item : response.iterateAll()) {
    // ...
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all media items in an album
    // Provide the ID of the album as a parameter in the searchMediaItems call
    // Iterate over all the retrieved media items
    $response = $photosLibraryClient->searchMediaItems(['albumId' => $albumId]);
    foreach ($response->iterateAllElements() as $item) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

การตอบกลับมี nextPageToken และรายการสื่อ ซึ่งแตกต่างจากรายการเนื้อหาห้องสมุด ที่รายการสื่อจะส่งคืนตามลําดับในอัลบั้ม ดูรายละเอียดเพิ่มเติมได้ที่ mediaItems และการใส่เลขหน้า ผู้ใช้แก้ไขคําสั่งซื้อได้จากอินเทอร์เฟซของ Google Photos

หากตั้งค่า albumId ไว้ คุณจะใช้ตัวกรองเมื่อแสดงเนื้อหาอัลบั้มไม่ได้ การดําเนินการนี้จะทําให้เกิดข้อผิดพลาด Bad Request

แสดงรายการอัลบั้มที่แชร์

คุณจะเรียกดูรายการอัลบั้มทั้งหมดที่ผู้ใช้แชร์หรือแชร์กับผู้ใช้ได้ ซึ่งจะคล้ายกับแท็บการแชร์ในแอป Google Photos

อัลบั้มที่แชร์ที่ผู้ใช้เพิ่มลงในคลังภาพของ Google Photos จะแสดงในรายชื่ออัลบั้มด้วย เรียกรายการต่อไปนี้เพื่อแสดงรายการอัลบั้มที่แชร์ผ่าน Library API

REST

ตัวอย่างคําขอมีดังนี้

GET https://photoslibrary.googleapis.com/v1/sharedAlbums

คําขอจะแสดงผลลัพธ์ต่อไปนี้

{
  "sharedAlbums": [...]
  "nextPageToken": "token-for-pagination"
}

Java

try {
  // Make a request to list all albums that have been shared by the user
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums();

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums that have been shared by the user
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listSharedAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

รายการอัลบั้มจะรวมอยู่ใน sharedAlbums ดูข้อมูลเพิ่มเติมได้ที่รายชื่ออัลบั้ม การตอบกลับจะมี nextPageToken รวมอยู่ด้วย สําหรับข้อมูลเพิ่มเติม โปรดดูการใส่เลขหน้า

อัลบั้มที่แอปของคุณสร้างและแชร์จะมีพร็อพเพอร์ตี้ shareInfo เพิ่มเติม โปรดดูรายละเอียดเพิ่มเติมที่หัวข้อแชร์สื่อ

แสดงอัลบั้มแอปที่สร้างแล้ว

คุณสามารถแสดงรายการอัลบั้มที่แอปสร้างขึ้นด้วยการตั้งค่า excludeNonAppCreatedData เป็น true ในการเรียกต่อไปนี้

• albums.list
• sharedAlbums.list

REST

ต่อไปนี้เป็นคําขอ GET ที่แสดงอัลบั้มทั้งหมดจากคลังภาพ Google Photos ที่แอปของคุณสร้างขึ้นเท่านั้น

GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

ต่อไปนี้เป็นคําขอ GET สําหรับรายการอัลบั้มที่แชร์ทั้งหมดจากคลังภาพ Google Photos ที่แอปของคุณสร้างขึ้นเท่านั้น

GET https://photoslibrary.googleapis.com/v1/sharedAlbums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

Java

try {
  // Make a request to list all albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

try {
  // Make a request to list all shared albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response =
      photosLibraryClient.listSharedAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Make a request to list all albums that have been created by your app
    $response = $photosLibraryClient->listAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

try {
    // Make a request to list all shared albums that have been created by your app
    $response = $photosLibraryClient->listSharedAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

การใส่เลขหน้าสําหรับ REST

ในการปรับปรุงประสิทธิภาพ วิธีที่แสดงผลการค้นหาจํานวนมาก (เช่น วิธีรายการ) อาจใส่เลขหน้าคําตอบ พารามิเตอร์ pageSize จะระบุจํานวนผลการค้นหาสูงสุดในแต่ละหน้า

สําหรับการโทรไปที่ mediaItems:search และ mediaItems:list ขนาดหน้าเว็บเริ่มต้นคือ 25 รายการ เราขอแนะนําให้ใช้ขนาดหน้านี้เนื่องจากจะรักษาสมดุลระหว่างขนาดของการตอบกลับกับอัตราการส่งโฆษณา หน้าค้นหาสื่อและรายการคําขอมีขนาดสูงสุดของหน้า 100 รายการ

ขนาดเริ่มต้นและที่แนะนําของอัลบั้มเมื่อแสดงอัลบั้มคือ 20 อัลบั้ม โดยมีได้สูงสุด 50 อัลบั้ม

เมื่อจํานวนผลลัพธ์ที่ใช้ได้มากกว่าขนาดหน้า การตอบกลับจะมี nextPageToken ซึ่งระบุแอปพลิเคชันของคุณที่มีผลการค้นหาเพิ่มเติมซึ่งต้องดึงจากเซิร์ฟเวอร์

หมายเหตุ: พารามิเตอร์ pageSize คือค่าสูงสุด อาจมีการแสดงผลลัพธ์น้อยกว่าที่ขอ

ตัวอย่าง

คุณต้องเพิ่ม nextPageToken ต่อท้ายคําขอที่ตามมาในพารามิเตอร์pageToken ดังที่แสดงในตัวอย่างต่อไปนี้ ระบุ pageToken ร่วมกับพารามิเตอร์อื่นๆ ที่จําเป็นสําหรับการดําเนินการ ไม่ว่าจะเป็นเนื้อหาของคําขอหรือพารามิเตอร์การค้นหา

คําขอ #1

{
  "pageSize": "5",
  "filters": { … }
}

คําตอบ #1

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

คําขอ #2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

คําตอบ #2

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

ใช้รูปแบบนี้ต่อจนกว่าจะไม่มีออบเจ็กต์ nextPageToken อีก

nextPageToken ใช้ได้กับคําขอเดียวกันเท่านั้น หากมีการเปลี่ยนแปลงพารามิเตอร์ใดก็ตาม ไม่ควรใช้ nextPageToken ที่ใช้ก่อนหน้านี้ในคําขอเดียวกัน

หมายเหตุ: การมีอยู่ของ nextPageToken คือตัวบ่งชี้เดียวว่าจะเรียกผลลัพธ์จากเซิร์ฟเวอร์เพิ่มหรือไม่ อย่านับจํานวนผลการค้นหา เพื่อพิจารณาว่าคุณควรใช้nextPageTokenหรือไม่ คําขออาจแสดงผลการค้นหาน้อยกว่าที่ขอในขนาดหน้า หากมี nextPageToken ให้ส่งคําขอผลลัพธ์เพิ่มเติมหลังจากคําขอแรก