يمكن الوصول إلى واجهات برمجة تطبيقات البنية من خلال واجهات برمجة تطبيقات الشاشة الرئيسية لنظام التشغيل Android. يُرجى استيراد هذه الحِزم إلى تطبيقك:
import com.google.home.Home
import com.google.home.Id
import com.google.home.Structure
معالجة الأخطاء
يمكن لأي طريقة في واجهات برمجة تطبيقات المنزل طرح
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 حرفًا)، ولن يتم عرض أي أخطاء. المطوّرون مسؤولون عن معالجة الأسماء الطويلة، ويمكنهم مثلاً تحديد ما إذا كانوا يريدون إبلاغ المستخدمين بأنّه سيتم اقتطاع الأسماء.
عرض أنواع الأجهزة التي منح المستخدم أذونات الوصول إليها
في نظام Google Home، يمكن للمستخدمين منح أذونات الوصول إلى جميع الأجهزة من نوع معيّن في آن واحد لمعظم أنواع الأجهزة. بالنسبة إلى أنواع الأجهزة الحساسة أو المحظورة، مثل الأقفال أو الكاميرات أو أجراس الأبواب، يجب أن يمنح المستخدمون إذن الوصول إليها بشكل فردي.
لتحديد ما إذا كان المستخدم قد منح إذن الوصول إلى نوع جهاز حسّاس أو محظور، استخدِم الدالة consentedDeviceTypes() على مستوى البنية:
import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch
/**
* Example of how an app may monitor which device types have been granted access by a user.
*/
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
// Obtain the flow of consented device type factories
val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
structure.consentedDeviceTypes()
myScope.launch {
consentedTypesFlow.collect { consentedSet ->
// Check if the user has consented to share a specific restricted
// type, such as a Doorbell or Camera.
val hasCameraAccess = consentedSet.any {
it.toString() == "matter.google.type.GoogleDoorbellDevice"
}
if (hasCameraAccess) {
// Enable features that require camera access
} else {
// Inform the user or disable camera-specific features
}
}
}
}
عمليات التشغيل الآلي
نقطة الدخول إلى Automation API هي من خلال بنية. لمزيد من المعلومات حول عمليات التشغيل الآلي في واجهات برمجة تطبيقات المنزل، يُرجى الاطّلاع على نظرة عامة على Automation API على Android.