แสดงรายการสื่อและอัลบั้มที่แอปสร้างขึ้น

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

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

ภาพรวม

Library API ช่วยให้คุณแสดงรายการและเข้าถึงรายการสื่อที่แอปพลิเคชันของคุณ สร้าง แล้ว

คุณลักษณะสำคัญบางประการของการแสดงรายการสื่อมีดังต่อไปนี้

  • แสดงรายการสื่อจากอัลบั้มที่สร้างโดยแอปที่เฉพาะเจาะจงหรือทั้งแอป คลัง

  • ใช้ตัวกรอง (วันที่ หมวดหมู่เนื้อหา ประเภทสื่อ) เมื่อแสดงข้อมูลเพื่อจำกัดผลการค้นหาให้แคบลง

  • เรียกข้อมูลออบเจ็กต์ mediaItem พร้อมรายละเอียดที่สำคัญ เช่น ลิงก์โดยตรงและข้อมูลเมตา

การแสดงรายการเนื้อหาในคลังเพลงและอัลบั้มจะแสดงรายการสื่อ ส่วนเสริมที่เป็นส่วนหนึ่งของอัลบั้ม ผลิตภัณฑ์ดังกล่าว รายการสื่อจะอธิบายรูปภาพ วิดีโอ หรือสื่ออื่นๆ ต 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"
}

อัลบั้มที่ส่งคืนแต่ละอัลบั้มจะมีรหัสซึ่งสามารถใช้เรียกเนื้อหาของ ตามที่แสดงในแสดงเนื้อหาของอัลบั้ม และ ประกอบด้วยชื่อและจำนวนรายการสื่อภายในวิดีโอ

productUrl ชี้ไปที่อัลบั้มใน Google Photos ที่สามารถ เปิดโดยผู้ใช้

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

การตอบกลับยังมี nextPageToken ด้วย ดูข้อมูลเพิ่มเติมได้ที่การแบ่งหน้า

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

แสดงเนื้อหาไลบรารีที่แอปสร้างขึ้น

คุณสามารถแสดงรายการสื่อทั้งหมดจากคลังภาพ 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"
}

การตอบกลับจะมีรายการรายการสื่อที่จัดเรียงจากล่าสุดไปจนถึงล่าสุด ดูข้อมูลเพิ่มเติมได้ที่ 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"
}

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

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

การใส่เลขหน้าสำหรับ 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 ที่ใช้ก่อนหน้านี้ไม่ควรจะใช้ในบัญชีเดียวกัน อีกครั้ง