เริ่มต้นใช้งาน Ambient API

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

ขั้นตอนการเรียกใช้ Ambient API

รายละเอียดการทำงานของ Ambient API ในการเชื่อมต่ออุปกรณ์ จากนั้นดึงข้อมูลและแสดงรายการสื่อมีดังนี้

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

2. เริ่มการให้สิทธิ์ OAuth 2.0 (และสร้างอุปกรณ์ได้หากต้องการ): เริ่มขั้นตอนการOAuth 2.0 สำหรับทีวีและอุปกรณ์อินพุตแบบจำกัดด้วยการขอรหัสการให้สิทธิ์

   หมายเหตุ: Ambient API รองรับตัวเลือกในการใส่พารามิเตอร์ state ในคําขอการให้สิทธิ์ ซึ่งจะสั่งให้ Ambient API พยายามสร้างอุปกรณ์ใหม่ด้วยเมื่อได้รับสิทธิ์เรียบร้อยแล้ว

3. สร้างอุปกรณ์ใหม่: แอปของคุณสร้างอุปกรณ์ในบัญชี Google Photos ของผู้ใช้โดยการเรียกใช้ CreateDevice และระบุ UUID เวอร์ชัน 4 ที่ถูกต้อง

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

4. แสดง settingsUri: ออบเจ็กต์ AmbientDevice มี settingsUri แสดง URI นี้ต่อผู้ใช้ โดยปกติจะเป็นคิวอาร์โค้ดที่ผู้ใช้สแกนโดยใช้อุปกรณ์เคลื่อนที่ได้ URI นี้จะนําผู้ใช้ไปยังแอป Google Photos ซึ่งผู้ใช้สามารถกําหนดค่าแหล่งที่มาของสื่อ (เช่น อัลบั้ม) ที่ต้องการแสดงบนอุปกรณ์แอมเบียนท์

5. ตรวจสอบ mediaSourcesSet: แอปพลิเคชันควรเรียกใช้เมธอด GetDevice เป็นระยะๆ โดยระบุ deviceId เพื่อตรวจสอบสถานะของอุปกรณ์ที่ทำงานอยู่รอบๆ ตรวจสอบช่อง mediaSourcesSet ในAmbientDeviceตอบ โดยค่าเริ่มต้นจะเป็นเท็จ

   เมื่อผู้ใช้เลือกแหล่งที่มาของสื่อในแอป Google Photos เรียบร้อยแล้ว ช่องนี้จะเปลี่ยนเป็น "จริง"

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

6. ดึงข้อมูลรายการสื่อ: เมื่อ mediaSourcesSet แสดงผลเป็น true แอปพลิเคชันของคุณจะเริ่มดึงข้อมูลรายการสื่อที่ผู้ใช้เลือก

   เรียกใช้เมธอด ListMediaItems โดยระบุ deviceId API จะแสดงListMediaItemsResponseที่มีรายการAmbientMediaItemออบเจ็กต์ AmbientMediaItem แต่ละรายการจะมีรายละเอียด เช่น ออบเจ็กต์ id, createTime และออบเจ็กต์ MediaFile ที่มีข้อมูลเมตาเพิ่มเติม MediaFile มี baseUrl ที่คุณสามารถใช้เพื่อดึงข้อมูลไบต์จริงของรายการสื่อ อ่านคู่มือแสดงรายการและดึงข้อมูลรายการสื่อเพื่อดูรายละเอียดเกี่ยวกับพารามิเตอร์ baseUrl เพิ่มเติม

7. แสดงรายการสื่อ: ใช้ baseUrl จาก MediaFile เพื่อดาวน์โหลดและแสดงเนื้อหาสื่อบนอุปกรณ์แอมเบียนท์

สิ่งสำคัญที่ต้องคำนึงถึง

ขีดจำกัดและการจัดการอุปกรณ์

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

โปรดดูรายละเอียดเพิ่มเติมในคำแนะนำเกี่ยวกับสร้างและจัดการอุปกรณ์

วิธีทำงานกับรายการสื่อ

• การใช้รายการสื่อ: ทำความเข้าใจวิธีดึงข้อมูลและจัดการเนื้อหารายการสื่ออย่างถูกต้องโดยใช้ baseUrl รวมถึงการตรวจสอบสิทธิ์หรือพารามิเตอร์ที่จำเป็น
• การจัดการข้อผิดพลาด: ใช้การจัดการข้อผิดพลาดที่มีประสิทธิภาพสำหรับการเรียก API ซึ่งรวมถึงสถานการณ์ต่างๆ เช่น NOT_FOUND สำหรับอุปกรณ์, FAILED_PRECONDITION หากไม่ได้ตั้งค่าแหล่งที่มาของสื่อ และ RESOURCE_EXHAUSTED หากถึงขีดจำกัดของอุปกรณ์

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

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

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