واجهات برمجة التطبيقات للبنية

يمكن الوصول إلى واجهات برمجة التطبيقات في Structure من خلال واجهات برمجة التطبيقات في Home. استورِد هذه الحِزم في تطبيقك:

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

معالجة الأخطاء

يمكن أن تُعرِض أي طريقة في واجهات برمجة التطبيقات Home API خطأ 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() هي عملية قد لا تُعرِض على الفور قائمة جيدة بالهياكل. إذا كان تطبيقك يستجيب للطلبات ويشترك في هذه العملية لتحديد واجهة المستخدم، من المفترض أن يتم عرض قائمة صالحة بالهياكل في النهاية. هناك حالات أخرى قد يتم فيها عرض قائمة فارغة بالهياكل، على سبيل المثال، إذا انقطع الاتصال بشبكة الهاتف لدى المستخدم أو إذا أبطل المستخدم أذونات الوصول إلى تطبيقك. يجب التأكّد من معالجة هذه الحالات في تطبيقك.

بدلاً من ذلك، إذا كان مطلوبًا بشدة استخدام البرمجة الإلزامية بدلاً من البرمجة التفاعلية، يمكن استخدام عامل تدفق طرفي:

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، يُرجى الاطّلاع على مقالة تصميم إجراء مبرمَج.

قائمة واجهات برمجة التطبيقات

بعد إنشاء مثيل لبنية Home، يمكن من خلاله الوصول إلى واجهات برمجة تطبيقات Structure التالية:

بعد الحصول على Structure، يمكن الوصول إلى واجهات برمجة التطبيقات التالية من خلاله:

تتوفّر أيضًا بعض واجهات برمجة التطبيقات الشائعة (مثل devices() وid وname) Room.