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

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

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

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

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

การสร้างอุปกรณ์ที่คล่องตัวด้วย OAuth

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

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

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

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

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

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

ดึงข้อมูลอุปกรณ์

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

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

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

ลบอุปกรณ์

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

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

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

ข้อควรพิจารณาและแนวทางปฏิบัติแนะนำที่สำคัญ

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

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