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

bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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 هي من خلال بنية. لمزيد من المعلومات حول ميزة "التشغيل الآلي" في واجهات برمجة التطبيقات الخاصة بمنصة Home، يُرجى الاطّلاع على نظرة عامة على Automation API على Android.

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

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

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

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