ساختار APIها در اندروید

APIهای ساختار (Structure APIs) را می‌توان از طریق APIهای صفحه اصلی (Home APIs) برای اندروید (Android) دسترسی پیدا کرد. این بسته‌ها را به برنامه خود وارد کنید:

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

مدیریت خطا

هر متدی در APIهای Home می‌تواند یک HomeException ایجاد کند، بنابراین توصیه می‌کنیم از یک بلوک try-catch برای گرفتن HomeException در تمام فراخوانی‌ها استفاده کنید.

هنگام مدیریت HomeException ، فیلدهای error.code و error.message آن را بررسی کنید تا متوجه شوید چه مشکلی پیش آمده است. ممکن است کدهای خطای فرعی نیز وجود داشته باشد، بنابراین متد getSubErrorCodes() را فراخوانی کرده و نتیجه را بررسی کنید.

هرگونه خطای مدیریت نشده منجر به از کار افتادن برنامه شما خواهد شد.

برای اطلاعات بیشتر، به بخش مدیریت خطا مراجعه کنید.

نمونه تماس‌ها

دریافت لیست سازه‌ها

پس از مقداردهی اولیه، فراخوانی 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")))

تغییر نام یک اتاق

برای تغییر نام یک اتاق، متد setName() را فراخوانی کنید:

livingRoom.setName("Living Room")

اگر تعداد کاراکترهای نام‌ها از حد مجاز ۶۰ کاراکتر یونیکد بیشتر شود، نام‌ها کوتاه می‌شوند و هیچ خطایی رخ نمی‌دهد. توسعه‌دهندگان مسئول مدیریت نام‌های طولانی هستند و برای مثال، می‌توانند تصمیم بگیرند که آیا می‌خواهند به کاربران اطلاع دهند که نام‌ها کوتاه خواهند شد یا خیر.

اتوماسیون‌ها

نقطه ورود به API اتوماسیون از طریق یک ساختار است. برای کسب اطلاعات بیشتر در مورد اتوماسیون‌ها در APIهای خانگی، به نمای کلی API اتوماسیون در اندروید مراجعه کنید.

لیست API

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

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

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