واجهات برمجة تطبيقات 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() 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 نقطة رمز يونيكود (حرفًا)، ولن يتم عرض أي أخطاء. يتحمّل المطوّرون مسؤولية التعامل مع الأسماء الطويلة، ويمكنهم مثلاً تحديد ما إذا كانوا يريدون إعلام المستخدمين بأنّه سيتم اقتطاع الأسماء.

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