แสดงรายการและเรียกข้อมูลรายการสื่อ

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

ก่อนจะเริ่มต้น

  • ตรวจสอบการตั้งค่าอุปกรณ์: ตรวจสอบว่าคุณได้สร้างและ กำหนดค่าอุปกรณ์สำหรับผู้ใช้เรียบร้อยแล้ว
  • ทำความเข้าใจขั้นตอน Ambient API: ดู ขั้นตอน Ambient API เพื่อทำความเข้าใจ กระบวนการโดยรวม โดยเฉพาะขั้นตอนที่เกี่ยวข้องกับการสำรวจmediaSourcesSet

แบบสำรวจสำหรับ mediaSourcesSet

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

เรียกใช้เมธอด devices.get เป็นระยะๆ สำหรับ deviceId ที่เฉพาะเจาะจง ตรวจสอบฟิลด์ mediaSourcesSet ในการตอบกลับ AmbientDevice โดยจะเริ่มที่ false เมื่อผู้ใช้เลือกแหล่งที่มาของสื่อได้สำเร็จแล้ว ฟิลด์นี้จะเปลี่ยนเป็น true

การตอบกลับ AmbientDevice มี pollingConfig ที่มี pollInterval ซึ่งคุณควรใช้เป็นแนวทางสำหรับความถี่ในการสำรวจ

แสดงรายการรายการสื่อ

เมื่อ mediaSourcesSet true สำหรับอุปกรณ์แล้ว คุณจะเริ่มดึงข้อมูลสื่อ ที่ผู้ใช้เลือกได้

  1. ใช้ปลายทาง mediaItems.list: ส่งคำขอ GET ไปยัง https://photosambient.googleapis.com/v1/mediaItems โดยระบุ deviceId ในเส้นทาง

  2. จัดการการแบ่งหน้า (หากจำเป็น): คำตอบอาจมีการแบ่งหน้า ใช้พารามิเตอร์ pageSize เพื่อระบุจำนวนสูงสุดของรายการที่จะแสดง และใช้ pageToken จากการตอบกลับก่อนหน้าเพื่อดึงข้อมูลหน้าถัดไปของผลลัพธ์

  3. ประมวลผลรายการสื่อ: การตอบกลับจะมีอาร์เรย์ของออบเจ็กต์ AmbientMediaItem ซึ่งแต่ละออบเจ็กต์แสดงถึงรายการสื่อที่เลือก ออบเจ็กต์เหล่านี้มีรายละเอียดที่สำคัญ เช่น

    • id: ตัวระบุที่ไม่ซ้ำกันสำหรับรายการสื่อ
    • creationTime: การประทับเวลาเมื่อสร้างรายการสื่อ
    • mediaFile: ออบเจ็กต์ที่มีรายละเอียดในการเข้าถึงเนื้อหาจริง

ฟิลด์ mediaFile มี baseUrl baseUrl คือสิ่งที่คุณ จะใช้สร้าง URL เพื่อเข้าถึงเนื้อหาของรายการสื่อที่ความละเอียดหรือรูปแบบต่างๆ

URL ฐาน

URL ฐานใน Google Photos API ช่วยให้เข้าถึงไบต์ดิบของรายการสื่อได้ ซึ่งจะช่วยให้แอปของคุณดาวน์โหลดหรือแสดงรายการสื่อได้ URL เหล่านี้จะรวมอยู่ในคำตอบเมื่อแสดงรายการอัลบั้ม (Library API) หรือเข้าถึงรายการสื่อ (ทั้ง Library API และ Picker API) โปรดทราบว่า URL ฐานต้องมี พารามิเตอร์เพิ่มเติมจึงจะทำงานได้อย่างถูกต้อง

สำหรับ Picker API

ออบเจ็กต์ PickedMediaItem.mediaFile ทั้งหมดมี baseUrl

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

สำหรับ Library API

URL ฐานจะใช้งานได้เป็นเวลา 60 นาที

URL ฐานต่างๆ มีดังนี้

  • baseUrl: เข้าถึงรูปภาพ ภาพขนาดย่อสำหรับวิดีโอ หรือดาวน์โหลดไบต์ของวิดีโอโดยตรง
  • coverPhotoBaseUrl: เข้าถึงภาพหน้าปกของอัลบั้มโดยตรง
  • profilePictureBaseUrl: เข้าถึงรูปโปรไฟล์ของเจ้าของ mediaItem โดยตรง

URL หลักของรูปภาพ

รายการต่อไปนี้คือตัวเลือกที่คุณใช้กับ URL ฐานของรูปภาพได้

พารามิเตอร์
w, h

คำอธิบาย

พารามิเตอร์ความกว้าง w และความสูง h

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

ตัวอย่างเช่น

base-url=wmax-width-hmax-height

ตัวอย่างการแสดงรายการสื่อที่มีความกว้างไม่เกิน 2048 พิกเซลและความสูงไม่เกิน 1024 พิกเซลมีดังนี้

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

คำอธิบาย

พารามิเตอร์ c

หากต้องการครอบตัดรูปภาพให้มีความกว้างและความสูง ตรงตามขนาดที่ระบุ ให้ต่อ URL ฐานกับพารามิเตอร์ -c ที่ไม่บังคับ พร้อมกับพารามิเตอร์ w และ h ที่บังคับ

ขนาด (เป็นพิกเซล) ควรอยู่ในช่วง [1, 16383] หากความกว้างหรือความสูงของรูปภาพเกินขนาดที่ขอ ระบบจะลดขนาดและครอบตัดรูปภาพ (คงสัดส่วนภาพไว้)

ตัวอย่างเช่น

base-url=wmax-width-hmax-height-c

ในตัวอย่างนี้ แอปพลิเคชันจะแสดงรายการสื่อที่มีความกว้าง 256 พิกเซลและสูง 256 พิกเซลพอดี เช่น ภาพขนาดย่อ

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

คำอธิบาย

พารามิเตอร์ d ของการดาวน์โหลด

หากต้องการดาวน์โหลดรูปภาพโดยเก็บข้อมูลเมตา Exif ทั้งหมดไว้ ยกเว้นข้อมูลเมตาตำแหน่ง ให้ต่อ URL ฐานกับพารามิเตอร์ d

ตัวอย่างเช่น

base-url=d

ในตัวอย่างนี้ แอปพลิเคชันจะดาวน์โหลดรูปภาพที่มีข้อมูลเมตาทั้งหมด ยกเว้นข้อมูลเมตาของตำแหน่ง

https://lh3.googleusercontent.com/p/Az....XabC=d

URL ฐานของวิดีโอ

รายการตัวเลือกที่คุณใช้กับ URL ฐานของวิดีโอได้มีดังนี้

พารามิเตอร์
dv

คำอธิบาย

หากต้องการเข้าถึงไบต์ของวิดีโอ mediaItem ให้ต่อกัน baseUrl กับวิดีโอที่ดาวน์โหลด dv พารามิเตอร์

พารามิเตอร์ dv จะขอวิดีโอต้นฉบับเวอร์ชันคุณภาพสูงที่แปลงรหัสแล้ว พารามิเตอร์ใช้ร่วมกับพารามิเตอร์ w และ h ไม่ได้

URL ฐานสำหรับการดาวน์โหลดวิดีโออาจใช้เวลาไม่กี่วินาทีในการ ส่งคืนไบต์

ก่อนใช้พารามิเตอร์นี้ ให้ตรวจสอบว่าฟิลด์ mediaMetadata.status ของรายการสื่อเป็น READY มิฉะนั้น หากรายการสื่อประมวลผลไม่เสร็จ คุณอาจได้รับข้อผิดพลาด

ตัวอย่างเช่น

base-url=dv

ตัวอย่างต่อไปนี้แสดงวิธีดาวน์โหลดไบต์ของวิดีโอ

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h, c และ d

คำอธิบาย

หากต้องการเข้าถึงภาพปกของวิดีโอ ให้ใช้พารามิเตอร์ URL ฐานของรูปภาพ

โดยค่าเริ่มต้น ภาพปกวิดีโอทั้งหมดจะมีภาพซ้อนทับของปุ่มเล่น ดูพารามิเตอร์ -no เพื่อนำภาพซ้อนทับนี้ออก

ตัวอย่างเช่น

ดูตัวอย่างได้ที่ตาราง URL ฐานของรูปภาพ

no

คำอธิบาย

พารามิเตอร์ no ที่ซ้อนทับภาพปก

หากต้องการดึงภาพปกของวิดีโอโดยไม่มีปุ่มเล่นซ้อนทับ ให้ต่อ URL ฐานกับพารามิเตอร์ no

ต้องใช้พารามิเตอร์ no ร่วมกับพารามิเตอร์ต่อไปนี้อย่างน้อย 1 รายการ พารามิเตอร์ URL ฐานของรูปภาพ

ตัวอย่างเช่น

base-url=wmax-width-hmax-height-no

ตัวอย่างต่อไปนี้แสดงภาพปกวิดีโอที่มีความกว้าง 1280 พิกเซลและสูง 720 พิกเซล และไม่มีการซ้อนทับปุ่มเล่น

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

URL ฐานของรูปภาพเคลื่อนไหว

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

พารามิเตอร์
dv

คำอธิบาย

หากต้องการดึงข้อมูลองค์ประกอบวิดีโอของรายการสื่อภาพเคลื่อนไหว ให้ใช้ พารามิเตอร์ dv เช่นเดียวกับที่คุณใช้ดาวน์โหลดจาก URL ฐานของวิดีโอ
w, h, c และ d

คำอธิบาย

หากต้องการดึงองค์ประกอบรูปภาพของรายการสื่อรูปภาพเคลื่อนไหว ให้ใช้รูปแบบสำหรับURL ฐานของรูปภาพ

นโยบายและการกรองเนื้อหา

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

  • รูปภาพที่ใช้งานได้ (เช่น ภาพหน้าจอ เอกสาร ใบเสร็จ)
  • รูปภาพที่อาจแสดงผลไม่ดีบนหน้าจอขนาดใหญ่ (เช่น ความละเอียดต่ำมาก เบลอ มีเกรนมากเกินไป)
  • เนื้อหาที่ระบบระบุว่ามีความเป็นส่วนตัวหรือมีความละเอียดอ่อนสูง ซึ่งอาจไม่ ได้มีไว้สำหรับการแสดงต่อสาธารณะในสภาพแวดล้อมที่ใช้ร่วมกัน

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

ขั้นตอนถัดไป