ממשקי Structure API ב-Android

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

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

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

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

כשמטפלים בשגיאה HomeException, צריך לבדוק את השדות error.code ו- error.message כדי להבין מה השתבש. יכול להיות שיהיו גם קודי שגיאה משניים, לכן צריך להתקשר לשיטה getSubErrorCodes() ולבדוק את התוצאה.

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

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

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

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

אחרי האתחול, שיחה ל-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 התווים (נקודות קוד Unicode) ייחתכו, ולא יוצגו שגיאות. המפתחים אחראים לטפל בשמות ארוכים, והם יכולים להחליט למשל אם הם רוצים ליידע את המשתמשים שהשמות יקוצרו.

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

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