ساختار API ها

APIهای ساختاری ممکن است از طریق APIهای Home قابل دسترسی باشند. این بسته ها را به برنامه خود وارد کنید:

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

رسیدگی به خطا

هر روشی در APIهای Home می‌تواند یک 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()

structures() API جریانی است که ممکن است بلافاصله لیست معتبری از ساختارها را برنگرداند. اگر برنامه شما واکنش‌پذیر است و برای هدایت UI در آن جریان مشترک است، در نهایت باید فهرست معتبری از ساختارها برگردانده شود. موقعیت‌های دیگری وجود دارد که می‌توان یک لیست ساختار خالی را برگرداند، برای مثال اگر تلفن کاربر اتصال را قطع کند یا کاربر مجوزهای برنامه شما را لغو کرده باشد. شما باید مطمئن شوید که این موارد را در برنامه خود مدیریت می کنید.

متناوباً، اگر به جای برنامه‌ریزی واکنشی، برنامه‌ریزی ضروری به شدت مورد نیاز باشد، می‌توان از یک اپراتور جریان ترمینال استفاده کرد:

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 از طریق یک ساختار است. برای کسب اطلاعات بیشتر در مورد اتوماسیون در APIهای Home، به طراحی یک اتوماسیون مراجعه کنید.

لیست API

هنگامی که یک نمونه از Home ایجاد می شود، API های ساختار زیر از طریق آن قابل دسترسی هستند:

هنگامی که یک Structure دارید، API های زیر از طریق آن قابل دسترسی هستند:

برخی از APIهای رایج (مانند devices() ، id و name ) نیز برای یک Room در دسترس هستند.