เริ่มต้นใช้งาน 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 v4 ที่ถูกต้อง

   เมื่อสร้างอุปกรณ์สำเร็จแล้ว 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 แสดงผลเป็นจริง แอปพลิเคชันของคุณ จะเริ่มดึงข้อมูลรายการสื่อที่ผู้ใช้เลือกได้

   เรียกใช้เมธอด 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: ดูเอกสารประกอบอ้างอิง แบบละเอียดสำหรับเมธอด พารามิเตอร์คำขอและการตอบกลับ และรหัสข้อผิดพลาดทั้งหมดที่ใช้ได้