ממשקי Structure API ב-Android

אפשר לגשת אל Structure APIs דרך Home APIs ל-Android. מייבאים את החבילות האלה לאפליקציה:

import com.google.home.Home
import com.google.home.Id
import com.google.home.Structure

טיפול בשגיאות

כל שיטה ב-Home APIs יכולה להחזיר HomeException, ולכן מומלץ להשתמש בבלוק try-catch כדי לזהות HomeException בכל הקריאות.

כשמטפלים ב-HomeException, בודקים את השדות code ו-message כדי להבין מה השתבש.

חריגים שלא טופלו יגרמו לקריסת האפליקציה.

מידע נוסף זמין במאמר בנושא טיפול בשגיאות.

דוגמאות לשיחות

קבלת רשימה של מבנים

אחרי האתחול, שיחה ל-structures() מחזירה Flow של מבנים שאפשר לגשת אליהם:

// Get a flow of all structures accessible to the user
val allStructuresFlow: HomeObjectsFlow<Structure> = home.structures()

// Calling list() on a HomeObjectsFlow returns the first Set of elements.
val allStructures: Set<Structure> = allStructuresFlow.list()

‫structures() API הוא תהליך שאולי לא יחזיר מיד רשימה תקפה של מבנים. אם האפליקציה שלכם היא ריאקטיבית והיא נרשמת ל-Flow הזה כדי להפעיל את ממשק המשתמש, בסופו של דבר אמורה לחזור רשימה תקינה של מבנים. יש מצבים אחרים שבהם יכול להיות שתוחזר רשימה ריקה של מבנים, למשל אם הטלפון של המשתמש מאבד את הקישוריות או אם המשתמש ביטל את ההרשאות לאפליקציה שלכם. חשוב לטפל במקרים האלה באפליקציה שלכם.

לחלופין, אם נדרש שימוש בתכנות אימפרטיבי במקום בתכנות ריאקטיבי, אפשר להשתמש באופרטור של זרימת נתונים בטרמינל:

val everyStructure = withTimeout(5000) { home.structures().first { it.isNotEmpty() } }

הקריאה הזו ממתינה לרשימה תקינה של מבנים שתגיע דרך התהליך, ומסתיימת אם הרשימה לא מתקבלת בתוך פרק הזמן הקצוב שמוגדר באפליקציה.

קבלת מאפייני מבנה

אחרי שיוצרים את רשימת המבנים, אפשר לגשת למאפיינים שלהם:

// Get a flow on a structure. Flow emits new values on structure metadata changes: name.
val structureFlow: Flow<Structure> = home.structures().itemFlow(myStructureId)

// Get a snapshot of the structure.
val structure: Structure = structureFlow.first()

// Get structure properties
println("id ${structure.id}")
println("name ${structure.name}")

חיפוש מבנה לפי שם

אם אתם יודעים את השם של מבנה, אתם יכולים לגשת אליו גם באמצעות המאפיין name property:

val myHome = home.structures().list().first { it.name == "My home" }

משם אפשר לגשת לנכסים, לחדרים ולמכשירים של כל מבנה.

עבודה עם כמה מבנים

כדי להשתמש ביותר ממבנה אחד, צריך לקבל הפניה נפרדת לכל מבנה:

var structure1: Structure? = null
var structure2: Structure? = null

try {
  structure1 = home.structures().list().firstOrNull { it.name == "Main House" }
} catch (e: HomeException) {
  // Code for handling the exception
}
try {
  structure2 = home.structures().list().firstOrNull { it.name == "Guest Cottage" }
} catch (e: HomeException) {
  // Code for handling the exception
}

קבלת רשימת חדרים

אחרי שיוצרים את המבנה, אפשר לקבל רשימה של החדרים ולגשת למאפיינים שלהם:

val allRoomsFlow: HomeObjectsFlow<Room> = structure.rooms()
val allRooms: Set<Room> = allRoomsFlow.list()
val room: Room = allRooms.first()

println("id ${room.id}")
println("name ${room.name}")

יצירת חדר

כדי ליצור חדר חדש:

val testName = "Test Room Name"
val newRoom: Room = structure.createRoom(testName)

איך מוחקים חדרים

אפשר גם למחוק חדר:

val roomToDelete = structure.rooms().list().filter { it.name == "room_id1" }.firstOrNull()
    structure.deleteRoom(roomToDelete!!)

אפשר גם למחוק חדר רק באמצעות המזהה שלו:

val roomToDelete1 = allRooms.filter { it.id == testRoomId }.firstOrNull()
structure.deleteRoom(roomToDelete1!!)

אם חדר עם מכשירים נמחק, המכשירים עדיין יהיו במבנה, אבל לא ישויכו יותר לחדר.

העברת מכשירים לחדר אחר

אחרי שיוצרים מבנה, אפשר להעביר מכשירים לחדר אחר במבנה:

val room2 = structure.rooms().get(Id("room_id_other_structure"))
    val device1 = structure.devices().get(Id("device_id1"))
    structure.moveDevicesToRoom(room2!!, listOf(device1!!))

אם יש לכם רק מזהי מכשירים ומזהי חדרים, אתם יכולים גם להעביר מכשירים:

structure.moveDevicesToRoom(Id("room_id_other_structure"), listOf(Id("device_id1")))

שינוי השם של חדר

מתקשרים לשיטה setName() כדי לשנות את השם של החדר:

livingRoom.setName("Living Room")

שמות שיכילו יותר מ-60 תווים יחתכו, ולא יוצגו שגיאות. המפתחים אחראים לטיפול בשמות ארוכים. לדוגמה, הם יכולים להחליט אם הם רוצים להודיע למשתמשים שהשמות יקוצרו.

פעולות אוטומטיות

נקודת הכניסה ל-Automation API היא דרך מבנה. מידע נוסף על אוטומציות בממשקי ה-API של Home זמין במאמר סקירה כללית על Automation API ב-Android.

רשימת ממשקי API

אחרי שיוצרים מופע של Home, אפשר לגשת דרכו לממשקי ה-API הבאים של המבנה:

אחרי שיהיה לכם Structure, תוכלו לגשת לממשקי ה-API הבאים דרכו:

חלק מממשקי ה-API הנפוצים (כמו devices(),‏ id ו-name) זמינים גם ב-Room.