Android पर Structure API

स्ट्रक्चर एपीआई को Android के लिए Home APIs के ज़रिए ऐक्सेस किया जा सकता है. इन पैकेज को अपने ऐप्लिकेशन में इंपोर्ट करें:

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

गड़बड़ी ठीक करना

Home API में मौजूद कोई भी तरीका, HomeException को थ्रो कर सकता है. इसलिए, हमारा सुझाव है कि आप सभी कॉल पर HomeException को कैच करने के लिए, try-catch ब्लॉक का इस्तेमाल करें.

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
            }
        }
    }
}

डिवाइस ग्रुप

डिवाइस ग्रुप, किसी एक स्ट्रक्चर में मौजूद डिवाइसों का कलेक्शन होता है. इसे उपयोगकर्ता तय करता है. ग्रुप की सदस्यता, Google की सेवाओं में बनी रहती है. साथ ही, यह स्ट्रक्चर के अन्य सदस्यों और स्ट्रक्चर का ऐक्सेस रखने वाले अन्य ऐप्लिकेशन को दिखती है.

फ़िज़िकल रूम की तरह ही, डिवाइस ग्रुप भी एक ही स्ट्रक्चर से जुड़े होते हैं. हालांकि, रूम के उलट, डिवाइस ग्रुप लॉजिकल ग्रुप होते हैं. किसी डिवाइस को एक साथ कई डिवाइस ग्रुप में शामिल किया जा सकता है. डिवाइस ग्रुप में ज़्यादा से ज़्यादा 100 डिवाइस शामिल किए जा सकते हैं.

किसी ग्रुप में मौजूद डिवाइसों के साथ इंटरैक्ट करने के लिए, सीधे तौर पर उसके सदस्य डिवाइसों को बार-बार इस्तेमाल करें (ग्रुप के सदस्य डिवाइसों के साथ इंटरैक्ट करना देखें) या DeviceGroup पर डिवाइस टाइप के किसी हिस्से को टारगेट करें (डिवाइस ग्रुप को कंट्रोल करना देखें).

डिवाइस ग्रुप की सूची देखना

किसी स्ट्रक्चर में मौजूद सभी डिवाइस ग्रुप देखने के लिए, home.entities(DeviceGroup) को कॉल करें और स्ट्रक्चर के आईडी के हिसाब से फ़िल्टर करें:

home.entities(DeviceGroup).collect { allGroups ->
  val structureGroups = allGroups.filter { it.structureId == structure.id }
  for (group in structureGroups) {
    val groupName = group.trait(Group)?.Name
    println("Found group: $groupName with ID: ${group.id.id}")
  }
}

ग्रुप में शामिल डिवाइसों के साथ इंटरैक्ट करना

group.devices() का इस्तेमाल करके, किसी ग्रुप के सदस्य डिवाइसों को बार-बार दोहराने से, आपको अलग-अलग सदस्यों पर बेहतर कंट्रोल मिलता है. साथ ही, एक ही अनुरोध में निर्देशों का बैच बनाया जा सकता है. इसके अलावा, सदस्यों के एट्रिब्यूट को एग्रीगेट किया जा सकता है या लिखा जा सकता है.

उदाहरण के लिए, किसी ग्रुप के साथ काम करने वाले सभी सदस्यों को किसी ट्रेट के लिए कमांड के साथ एक ही बैच में अनुरोध भेजने के लिए:

val members = group.devices(enableMultipartDevices = true).first()
val onOffTraits = members.mapNotNull { device ->
  device.partOrNull(OnOffLightDevice).first()?.standardTraits?.onOff
}

val responses = home.sendBatchedCommands {
  onOffTraits.map { onOff ->
    add(onOff.onBatchable())
  }
}

for (response in responses) {
  response.getOrThrow()
}

किसी ग्रुप में मौजूद, एक जैसे सभी डिवाइसों के लिए भी किसी एट्रिब्यूट को अपडेट किया जा सकता है. उदाहरण के लिए, सभी DimmableLightDevice डिवाइसों पर onTransitionTime को 1u पर सेट करना. इसके बाद, तय समयसीमा के अंदर अपडेट पूरा होने का इंतज़ार करें:

val members = group.devices(enableMultipartDevices = true).first()

withTimeout(5.seconds) {
  members.map { device ->
    async {
      val light = device.partOrNull(DimmableLightDevice).first()
      val levelControl = light?.standardTraits?.levelControl
      if (
        levelControl?.supports(
          LevelControl.Attribute.onTransitionTime
        ) == true
      ) {
        levelControl.update { setOnTransitionTime(1u) }
      }
    }
  }.awaitAll()
}

किसी ग्रुप के सदस्यों के लिए किसी एट्रिब्यूट को एग्रीगेट करने के लिए, जैसे कि ग्रुप में मौजूद सभी कलर टेंपरेचर लाइट के लिए, कम से कम colorTempPhysicalMaxMireds का पता लगाना:

val members = group.devices(enableMultipartDevices = true).first()
val minMaxMireds: UShort? = members.mapNotNull { device ->
  val light = device.partOrNull(ColorTemperatureLightDevice).first()
  light?.standardTraits?.colorControl?.colorTempPhysicalMaxMireds
}.minOrNull()

डिवाइस ग्रुप बनाना

डिवाइस ग्रुप बनाने के लिए, स्ट्रक्चर पर GroupManagement का इस्तेमाल करें:

val groupManagement = structure.trait(GroupManagementTrait)
val response = groupManagement?.createUserDefinedGroup(
  name = "Living room lights",
  memberDeviceObjectIds = listOf(light1.id.id, light2.id.id)
)

ग्रुप की सदस्यता मैनेज करना

किसी मौजूदा ग्रुप में सदस्यों को जोड़ने के लिए:

structure.trait(GroupManagementTrait)?.addGroupMembers(
  groupObjectId = group.id.id,
  memberDeviceObjectIds = listOf(light3.id.id)
)

किसी ग्रुप से सदस्यों को हटाने के लिए:

structure.trait(GroupManagementTrait)?.removeGroupMembers(
  groupObjectId = group.id.id,
  memberDeviceObjectIds = listOf(light1.id.id)
)

डिवाइस ग्रुप का नाम बदलना

किसी डिवाइस ग्रुप का नाम बदलने के लिए, ग्रुप के GroupTrait पर नाम एट्रिब्यूट को अपडेट करें:

group.trait(GroupTrait)?.update {
  name = "Movie corner"
}

किसी डिवाइस ग्रुप को मिटाना

किसी स्ट्रक्चर से डिवाइस ग्रुप को मिटाने के लिए:

structure.trait(GroupManagementTrait)?.deleteGroup(
  groupObjectId = group.id.id
)

ऑटोमेशन

ऑटोमेशन एपीआई का एंट्री पॉइंट, स्ट्रक्चर के ज़रिए होता है. Home APIs में ऑटोमेशन के बारे में ज़्यादा जानने के लिए, Android पर Automation API की खास जानकारी देखें.