ภาพรวมของ Home API

Google Home API สำหรับ Android มีแพลตฟอร์ม API แบบรวมเพื่อให้นักพัฒนาแอปโต้ตอบกับสถานะของเอนทิตีในบ้านของผู้ใช้ เอนทิตีเหล่านี้สามารถอธิบายอุปกรณ์และข้อมูลที่ไม่ใช่อุปกรณ์ซึ่งเชื่อมโยงกับโครงสร้างและห้องของผู้ใช้

Home API จะกำหนดเอนทิตีต่อไปนี้ที่ผู้ใช้โต้ตอบได้

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

รูปที่ 1 แสดงสถาปัตยกรรมนี้

ประเภทอุปกรณ์ Home API อาจรองรับ Matter ซึ่งเป็นมาตรฐานแบบเปิดสำหรับสมาร์ทโฮม หรือเป็นอุปกรณ์ Cloud-to-cloud ในระบบนิเวศของ Google Home อุปกรณ์บางประเภทอาจรวมฟังก์ชันการทำงานจากทั้ง 2 ประเภท ดูข้อมูลเพิ่มเติมได้ที่ประเภทอุปกรณ์ที่รองรับ

ใน Matter ฟังก์ชันการทำงานของอุปกรณ์จะจัดกลุ่มตามคลัสเตอร์ ซึ่งแสดงใน Home API เป็นMatterลักษณะมาตรฐาน Home API รองรับชุดคลัสเตอร์Matterมาตรฐานตามที่ระบุไว้ในข้อกำหนดMatterปัจจุบัน

ในระบบนิเวศของ Google Home ฟังก์ชันการทำงานของอุปกรณ์จะจัดกลุ่มตามลักษณะสมาร์ทโฮม ซึ่งแสดงใน Home API เป็นลักษณะสมาร์ทโฮมของ Google Home API รองรับชุดลักษณะสมาร์ทโฮมตามที่ระบุไว้ในโปรแกรม Cloud-to-cloud

นอกจากนี้ยังมีลักษณะอื่นๆ เช่น กลุ่มที่เจาะจงผู้ผลิตและลักษณะแพลตฟอร์ม ดูข้อมูลเพิ่มเติมได้ที่โมเดลข้อมูล

ภาษา

Home API เขียนด้วยภาษา Kotlin และมีอินเทอร์เฟซ Kotlin ที่เป็นรูปแบบที่ใช้ Flow เพื่อจัดการสถานะและการติดตาม ซึ่งมีข้อดีหลายประการเหนือกว่า API การสมัครใช้บริการมาตรฐาน

เราขอแนะนำให้ทำความคุ้นเคยกับเอกสารประกอบของ Kotlin เกี่ยวกับโคโริวทีน, Flow และ Jetpack Compose หากยังไม่ได้ดำเนินการ

• พัฒนาแอป Android ด้วย Kotlin
• เรียนรู้ Kotlin สําหรับ Android
• โคโรทีน Kotlin ใน Android โค้ดแล็บต่อไปนี้อาจมีประโยชน์
  • Codelab - ใช้โคโรทีน Kotlin ในแอป Android
  • Codelab - เรียนรู้โคโริวทีนขั้นสูงด้วย Kotlin Flow และ LiveData
• Kotlin Flow ใน Android และโดยเฉพาะอย่างยิ่ง StateFlow
• สถานะและ Jetpack Compose โดยเฉพาะฟังก์ชัน collectAsStateWithLifecycle() ฟังก์ชันนี้จะจัดการการสมัครและยกเลิกการสมัครรับข้อมูลจากโฟลว์โดยอัตโนมัติ โดยขึ้นอยู่กับว่า UI ที่แสดงสถานะนั้นอยู่เบื้องหน้าจริงหรือไม่
  • Codelab — สถานะใน Jetpack
• หากคุณทํางานกับ Automation API การอ่านเกี่ยวกับตัวสร้างที่ปลอดภัยต่อประเภทของ Kotlin จะมีประโยชน์ในการทําความเข้าใจวิธีการทํางานของ Automation DSL

ตัวระบุเอนทิตี

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

ดูอินเทอร์เฟซ HasId เพื่อดูว่าเอนทิตีใดมีรหัส

การแมปคำศัพท์

เอนทิตีใน Home API จะแมปกับแนวคิด Matter และ Cloud-to-cloud ดังนี้

API สำหรับ Home	Matter	Cloud-to-cloud
ลักษณะ	คลัสเตอร์	ลักษณะ
แอตทริบิวต์	แอตทริบิวต์	แอตทริบิวต์ สถานะ
คำสั่ง	คำสั่ง	คำสั่ง
กิจกรรม	กิจกรรม	การตอบกลับเพื่อติดตามผล การแจ้งเตือน