ממשקי API של מבנה

אפשר לגשת לממשקי API של מבנים דרך ממשקי Home API. מייבאים את החבילות האלה לאפליקציה:

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() מחזירה זרימה של מבנים שזמינים לכם:

// 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()

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

לחלופין, אם יש צורך משמעותי בתכנות אימפרסיבית במקום בתכנות תגובה, אפשר להשתמש באופרטור של תהליך טרמינלי:

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:

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")))

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

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

רשימת ממשקי ה-API

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

API תיאור
structures() הצגת כל המבנים בחשבון Google. הפונקציה מחזירה HomeObjectsFlow שמספק אפשרויות אחזור וסינון נוספות.

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

API תיאור
automations() הצגת רשימה של כל הפעולות האוטומטיות ששייכות למבנה. המערכת מחזירה רק פעולות אוטומטיות שנוצרו באמצעות ממשקי ה-API של Home.
createAutomation(automation) יצירת מכונה של אוטומציה למבנה.
createRoom(name) יוצרים חדר עם השם שהמשתמש נתן לו.
deleteAutomation(automationId) מחיקת מופע של אוטומציה לפי המזהה שלו.
deleteRoom(roomId) למחוק את החדר באמצעות מזהה החדר.
devices() הצגת כל המכשירים במבנה. הפונקציה מחזירה HomeObjectsFlow.
getAutomation(automationId) אחזור מכונה של אוטומציה לפי המזהה שלה.
getSourceConnectivity(trait) אחזור מטא-נתונים של מאפיין מסוים. הפונקציה מחזירה SourceConnectivity.
has(trait) בודקים אם המכשיר תומך במאפיין הנוכחי המבוקש.
id מזהה המערכת הייחודי של המבנה.
moveDevicesToRoom(roomId, deviceIds) להעביר את המכשירים למזהה חדר אחר במבנה.
name השם של המבנה שסיפק המשתמש.
rooms() הצגת כל החדרים במבנה. הפונקציה מחזירה HomeObjectsFlow.
trait(trait) הצגת תמונת מצב עדכנית של מאפייני המאפיין.

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