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

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

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

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

يمكن لأي طريقة في واجهات برمجة تطبيقات 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()

واجهة برمجة التطبيقات 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")

سيتم اقتطاع الأسماء إذا تجاوزت الحدّ الأقصى البالغ 60 نقطة رمز يونيكود (حرفًا)، ولن يتم عرض أي أخطاء. يتحمّل المطوّرون مسؤولية التعامل مع الأسماء الطويلة، ويمكنهم مثلاً تحديد ما إذا كانوا يريدون إعلام المستخدمين بأنّه سيتم اقتطاع الأسماء.

عمليات التشغيل الآلي

نقطة الدخول إلى Automation API هي من خلال بنية. لمزيد من المعلومات حول ميزة "التشغيل الآلي" في واجهات برمجة التطبيقات الخاصة بمنزل Google، يُرجى الاطّلاع على نظرة عامة على Automation API على Android.