واجهات برمجة تطبيقات Structure على Android

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

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

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

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

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

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، يُرجى الاطّلاع على نظرة عامة على Automation API على Android.

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

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

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

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