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

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

การแสดงเนื้อหาที่สร้างในแอปต้องใช้ขอบเขต 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 ที่เคยใช้ในคําขอเดียวกัน