สร้างและจัดการอุปกรณ์

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

สร้างอุปกรณ์

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

เมื่อแอปสร้างอุปกรณ์โดยใช้เมธอด devices.create เรียบร้อยแล้ว Ambient API จะแสดงผลออบเจ็กต์ AmbientDevice ที่มี id ที่ Google สร้างขึ้น จัดเก็บ id นี้อย่างปลอดภัยและเชื่อมโยงกับผู้ใช้

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

การสร้างอุปกรณ์ที่มีประสิทธิภาพมากขึ้นด้วย OAuth

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

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

ขีดจำกัดของอุปกรณ์

แอปพลิเคชันสามารถสร้างอุปกรณ์ได้สูงสุด 100 เครื่องต่อผู้ใช้ 1 ราย หากเกินขีดจำกัดนี้ API จะแสดงข้อผิดพลาด RESOURCE_EXHAUSTED

จัดการอุปกรณ์

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

เรียกข้อมูลอุปกรณ์

หากต้องการดึงข้อมูลเกี่ยวกับอุปกรณ์ที่ต้องการ ให้ใช้เมธอด devices.get ร่วมกับ id ที่ไม่ซ้ำกัน ซึ่งมีประโยชน์ในการตรวจสอบสถานะของอุปกรณ์ เช่น mediaSourcesSet เป็นจริงหรือไม่

อัปเดตอุปกรณ์

คุณสามารถอัปเดตพร็อพเพอร์ตี้บางอย่างของอุปกรณ์ที่มีอยู่ เช่น ชื่อที่แสดง โดยใช้เมธอด devices.patch ซึ่งช่วยให้ผู้ใช้ปรับเปลี่ยนอุปกรณ์ในแบบของตัวเองและทำให้ระบุอุปกรณ์ได้ง่ายขึ้นภายใน Google Photos

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

ลบอุปกรณ์

ใช้กลยุทธ์ในการลบอุปกรณ์เพื่อล้างข้อมูลอย่างเหมาะสมและควบคุมผู้ใช้ คุณลบอุปกรณ์ได้โดยใช้วิธี devices.delete

พิจารณาสถานการณ์ต่อไปนี้สำหรับการลบอุปกรณ์

• การยกเลิกการเชื่อมต่อของผู้ใช้: หากผู้ใช้ยกเลิกการเชื่อมต่อแอปพลิเคชันของคุณจากบัญชี Google Photos คุณควรลบอุปกรณ์ที่เกี่ยวข้อง
• อุปกรณ์ที่ไม่มีเจ้าของ: หากไม่พบ id แต่ยังมี requestId ที่ใช้ในระหว่างการสร้าง คุณสามารถใส่ requestId นั้นใน devices.delete เพื่อนำอุปกรณ์ที่ไม่มีเจ้าของออก ซึ่งจะช่วยป้องกันไม่ให้มีรายการที่ซ้ำกันโดยไม่ตั้งใจและทำให้บัญชีของผู้ใช้สะอาดสะอ้าน

สิ่งสำคัญที่ต้องคำนึงถึงและแนวทางปฏิบัติแนะนำ

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

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

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