หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

Google Photos Library API มีขอบเขตหลายขอบเขตที่ใช้ในการเข้าถึงรายการสื่อและอัลบั้ม รายการสื่อที่แสดงผลจากการเรียกต่างๆ จะแตกต่างกันไปตามขอบเขตที่นักพัฒนาซอฟต์แวร์ได้ขอ

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

ภาพรวม

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

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

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

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

คุณเรียกดูรายการอัลบั้มของผู้ใช้ได้โดยใช้ 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 ในการเรียกต่อไปนี้

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 ซึ่งบอกแอปพลิเคชันว่ามีผลลัพธ์เพิ่มเติมที่ให้ดึงจากเซิร์ฟเวอร์

ตัวอย่าง

คุณต้องเพิ่ม 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 ที่ใช้ก่อนหน้านี้ในคำขอเดียวกัน