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

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

ก่อนจะเริ่ม

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

แบบสํารวจสําหรับ `mediaSourcesSet`

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

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

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

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

เมื่อ mediaSourcesSet เป็น true สำหรับอุปกรณ์หนึ่งๆ คุณสามารถเริ่มดึงข้อมูลรายการสื่อที่ผู้ใช้เลือก

ใช้ปลายทาง mediaItems.list: ส่งคําขอ GET ไปยัง https://photosambient.googleapis.com/v1/mediaItems โดยระบุ deviceId ในเส้นทาง
จัดการการแบ่งหน้า (หากจำเป็น): การตอบกลับอาจมีการแบ่งหน้า ใช้พารามิเตอร์ pageSize เพื่อระบุจำนวนรายการสูงสุดที่จะแสดง และ pageToken จากการตอบกลับก่อนหน้าเพื่อดึงข้อมูลหน้าถัดไปของผลการค้นหา
ประมวลผลรายการสื่อ: การตอบกลับจะมีอาร์เรย์ของออบเจ็กต์ AmbientMediaItem โดยแต่ละรายการแสดงรายการสื่อที่เลือก ออบเจ็กต์เหล่านี้ประกอบด้วยรายละเอียดที่สำคัญ เช่น
- id: ตัวระบุที่ไม่ซ้ำกันสำหรับรายการสื่อ
- creationTime: การประทับเวลาของเวลาที่สร้างรายการสื่อ
- mediaFile: ออบเจ็กต์ที่มีรายละเอียดในการเข้าถึงเนื้อหาจริง

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

URL ฐาน

URL พื้นฐานใน Google Photos API ให้สิทธิ์เข้าถึงไบต์ดิบของรายการสื่อ ซึ่งช่วยให้แอปของคุณดาวน์โหลดหรือแสดงรายการเหล่านั้นได้ URL เหล่านี้จะรวมอยู่ในคําตอบเมื่อแสดงรายการอัลบั้ม (Library API) หรือเข้าถึงรายการสื่อ (ทั้ง Library และ 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`=w`max-width`-h`max-height` ตัวอย่างการแสดงรายการสื่อที่มีความกว้างไม่เกิน 2048 พิกเซลและสูงไม่เกิน 1024 พิกเซลมีดังนี้ https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
`c`	คำอธิบาย พารามิเตอร์ครอบตัด `c` หากต้องการครอบตัดรูปภาพให้มีความกว้างและความสูงตรงกับขนาดที่ระบุ ให้ต่อ URL พื้นฐานกับพารามิเตอร์ `-c` ที่ไม่บังคับ พร้อมกับพารามิเตอร์ `w` และ `h` ที่ต้องระบุ ขนาด (เป็นพิกเซล) ควรอยู่ในช่วง [1, 16383] หากความกว้างหรือความสูงของรูปภาพเกินขนาดที่ขอ ระบบจะปรับขนาดรูปภาพให้เล็กลงและครอบตัด (โดยคงสัดส่วนภาพไว้) ตัวอย่างเช่น `base-url`=w`max-width`-h`max-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

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 พื้นฐานสำหรับการดาวน์โหลดวิดีโออาจใช้เวลา 2-3 วินาทีในการแสดงผลไบต์ ก่อนใช้พารามิเตอร์นี้ ให้ตรวจสอบว่าช่อง `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 กับพารามิเตอร์ URL พื้นฐานของรูปภาพอย่างน้อย 1 รายการ ตัวอย่างเช่น `base-url`=w`max-width`-h`max-height`-no ตัวอย่างต่อไปนี้แสดงภาพขนาดย่อของวิดีโอที่มีความกว้าง 1280 พิกเซลและสูง 720 พิกเซลโดยไม่มีปุ่มเล่นวางซ้อน https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

dv

คำอธิบาย

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

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

URL พื้นฐานสำหรับการดาวน์โหลดวิดีโออาจใช้เวลา 2-3 วินาทีในการแสดงผลไบต์

ก่อนใช้พารามิเตอร์นี้ ให้ตรวจสอบว่าช่อง 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 กับพารามิเตอร์ URL พื้นฐานของรูปภาพอย่างน้อย 1 รายการ

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

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 ฐานรูปภาพ

dv

คำอธิบาย

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

w, h, c และ d

คำอธิบาย

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

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

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

ก่อนจะเริ่ม

แบบสํารวจสําหรับ mediaSourcesSet

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

URL ฐาน

URL ฐานของรูปภาพ

URL หลักของวิดีโอ

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

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

แบบสํารวจสําหรับ `mediaSourcesSet`