iOS पर Structure APIs

iOS के लिए Home APIs के ज़रिए, स्ट्रक्चर के लिए एपीआई ऐक्सेस किए जा सकते हैं.

स्ट्रक्चर एपीआई का इस्तेमाल करने के लिए, सबसे पहले GoogleHomeSDK पैकेज को अपने ऐप्लिकेशन में इंपोर्ट करें:

import GoogleHomeSDK

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

Home API में कुछ तरीके HomeError दिखाते हैं. इसलिए, हमारा सुझाव है कि आप उन कॉल पर HomeError को पकड़ने के लिए, do-catch ब्लॉक का इस्तेमाल करें.

HomeError को मैनेज करते समय, गड़बड़ी के बारे में जानने के लिए इसके code और message फ़ील्ड देखें.

अगर किसी गड़बड़ी को ठीक नहीं किया जाता है, तो आपका ऐप्लिकेशन क्रैश हो जाएगा.

ज़्यादा जानकारी के लिए, गड़बड़ी ठीक करना लेख पढ़ें.

Structure API

Home होम ग्राफ़ को दिखाता है. साथ ही, यह Structure API का एंट्री पॉइंट है. इससे स्ट्रक्चर, कमरों, और डिवाइसों के रेफ़रंस मिलते हैं.

Structure, आपके होम ग्राफ़ में मौजूद स्ट्रक्चर को दिखाता है. इससे id और name जैसे स्ट्रक्चर मेटाडेटा का ऐक्सेस मिलता है.

अपने खाते में मौजूद सभी स्ट्रक्चर पाने के लिए, structures() का इस्तेमाल करें. स्ट्रक्चर को Query के तौर पर दिखाया जाता है. इससे इसके डेटा को इस्तेमाल करने के कई तरीके मिलते हैं:

एपीआई ब्यौरा
stream() यह फ़ंक्शन, एक Publisher दिखाता है. इसमें बदलाव होने पर, हर ऑब्जेक्ट को अलग-अलग दिखाया जाता है.
batched() यह एक Publisher दिखाता है, जो मौजूदा नतीजे को ऑब्जेक्ट के Set के तौर पर दिखाता है. एमिट किया गया हर Set, ऑब्जेक्ट ग्राफ़ की मौजूदा स्थिति को दिखाता है.
list() यह फ़ंक्शन, मौजूदा नतीजे को ऑब्जेक्ट के Set के तौर पर दिखाता है.

ऐसा हो सकता है कि structures().list() कॉल से, मान्य स्ट्रक्चर का सेट तुरंत न मिले. अगर आपका ऐप्लिकेशन, यूज़र इंटरफ़ेस (यूआई) को चलाने के लिए, स्ट्रक्चर में होने वाले सभी बदलावों की सदस्यता लेने के लिए stream() को कॉल करता है, तो आखिर में स्ट्रक्चर की मान्य सूची दिखनी चाहिए. ऐसी अन्य स्थितियां भी हो सकती हैं, जब स्ट्रक्चर की खाली सूची दिखाई जा सकती है. उदाहरण के लिए, अगर उपयोगकर्ता के फ़ोन का इंटरनेट कनेक्शन बंद हो जाता है या उपयोगकर्ता ने आपके ऐप्लिकेशन को दी गई अनुमतियां रद्द कर दी हैं. आपको अपने ऐप्लिकेशन में इन मामलों को हैंडल करना चाहिए.

@Published public private(set) var structures: [Structure] = []
private var structuresCancellable: AnyCancellable?

  self.structuresCancellable = home
    .structures()
    .batched()
    .receive(on: DispatchQueue.main)
    .map { Array($0) }
    .catch {
      // Failed to load structures
      return Just([Structure]())
    }
    .assign(to: \.structures, on: self)

स्ट्रक्चर्ड कॉल के सैंपल

स्ट्रक्चर का सेट पाना

Query<Structure> पर list() को कॉल करने पर, एलिमेंट का सबसे हाल का सेट मिलता है:

// Get a stream of all structures accessible to the user
let allStructuresChanges = self.home.structures()
let allStructures = try? await allStructuresChanges.list()

रीऐक्टिव ऐप्लिकेशन डिज़ाइन करते समय, आपको list() के बजाय batched() और stream() कॉल का इस्तेमाल करना चाहिए, क्योंकि होम ग्राफ़ में बदलाव होने पर ये अपने-आप डेटा जनरेट करते हैं.

स्ट्रक्चर प्रॉपर्टी पाना

स्ट्रक्चर की सूची की मदद से, इनके लिए प्रॉपर्टी ऐक्सेस की जा सकती हैं:

// Get a stream of changes taking place on a structure.
let structureChanges = try await home.structures().list().filter { $0.id == structureID }

// Get a snapshot of the structure.
let structure = structureChanges.first!

// Get structure properties
print("id \(structure.id) ")
print("name \(structure.name) ")

नाम से कोई होम ढूंढना

अगर आपको किसी स्ट्रक्चर का नाम पता है, तो name प्रॉपर्टी का इस्तेमाल करके भी उसे ऐक्सेस किया जा सकता है:

do {
  structure1 = try await home.structures().list().first(where: { $0.name == "Main House" })
} catch let _ as HomeError {
  // Code for handling the exception
}

यहां से, हर स्ट्रक्चर के लिए प्रॉपर्टी, कमरे, और डिवाइसों को ऐक्सेस किया जा सकता है.

एक से ज़्यादा स्ट्रक्चर के साथ काम करना

एक से ज़्यादा स्ट्रक्चर का इस्तेमाल करने के लिए, हर स्ट्रक्चर का अलग रेफ़रंस पाएं:

var structure1: Structure!
var structure2: Structure!
do {
  structure1 = try await home.structures().list().first(where: { $0.name == "Main House" })
} catch let _ as HomeError {
  // Code for handling the exception
}
do {
  structure2 = try await home.structures().list().first(where: { $0.name == "Guest Cottage" })
} catch let _ as HomeError {
  // Code for handling the exception
}

कमरे

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

खाते में मौजूद सभी कमरों को वापस पाने के लिए, Home.rooms() का इस्तेमाल करें. इसके बाद, हर कमरे में मौजूद डिवाइसों को दिखाने के लिए, roomID = device.roomID का इस्तेमाल करें.

self.home.rooms().batched()
  .combineLatest(self.home.devices().batched())
  .receive(on: DispatchQueue.main)
  .catch { error in
    // Failed to load rooms and devices
    return Just((Set<Room>(), Set<HomeDevice>()))
  }
  .map { rooms, devices in
    var devicesByRoom = [Room: [HomeDevice]]()
    for room in rooms where room.structureID == currentStructureID {
      devicesByRoom[room] = devices.filter { $0.roomID == room.id }
    }
    return devicesByRoom
  }.assign(to: &self.$devicesByRoom)

सैंपल रूम कॉल

कमरों की सूची पाना

Home क्लास का इस्तेमाल करके, कमरों की सूची पाई जा सकती है. साथ ही, उनके लिए प्रॉपर्टी ऐक्सेस की जा सकती हैं:

let allRoomsChanges = self.home.rooms()
let allRooms = try await allRoomsChanges.list()
let room = allRooms.first!
XCTAssertTrue(allRooms.contains(room))

print("id \(room.id) ")
print("name \(room.name) ")

चैट रूम बनाएं

Structure में नया रूम बनाने के लिए:

let testName = "Test Room Name"
var newRoom: Room!
do {
  newRoom = try await structure.createRoom(name: testName)
  XCTAssertNotNil(newRoom)
} catch let _ as HomeError {
  // Code for handling the exception
}

किसी रूम को मिटाना

इसके अलावा, किसी रूम को मिटाने के लिए:

val roomToDelete = structure.rooms().list().filter { it.name == "room_id1" }.firstOrNull()
    structure.deleteRoom(roomToDelete!!)

रूम के आईडी का इस्तेमाल करके भी उसे मिटाया जा सकता है:

let roomToDelete = allRooms.first(where: { $0.id == room.id })
if let roomToDelete1 = roomToDelete {
  do {
    try await structure.deleteRoom(roomToDelete1)
  } catch let _ as HomeError {
    // Code for handling the exception
  }
}

अगर डिवाइसों वाले किसी रूम को मिटा दिया जाता है, तो डिवाइस अब भी स्ट्रक्चर में मौजूद रहेंगे. हालांकि, उन्हें किसी रूम के लिए असाइन नहीं किया जाएगा.

डिवाइसों को किसी दूसरे रूम में ले जाना

Structure की मदद से, किसी डिवाइस को दूसरे रूम में भी ट्रांसफ़र किया जा सकता है:

do {
  try await structure.move(device: light, to: room)
} catch let _ as HomeError {
  // Code for handling the exception
}

किसी रूम का नाम बदलना

किसी रूम का नाम बदलने के लिए, setName(_:) तरीके को कॉल करें:

let updatedRoom = try await theRoom.setName("new room name")

किसी कमरे का नाम बदलने पर, ओरिजनल Room स्ट्रक्चर में कोई बदलाव नहीं होता है. हालांकि, अपडेट किए गए Room ऑब्जेक्ट में बदलाव दिखता है.

अगर नाम में 60 यूनिकोड कोड पॉइंट (वर्ण) से ज़्यादा हैं, तो उन्हें छोटा कर दिया जाएगा. हालांकि, कोई गड़बड़ी नहीं दिखेगी. डेवलपर, लंबे नामों को मैनेज करने के लिए ज़िम्मेदार होते हैं. उदाहरण के लिए, वे यह तय कर सकते हैं कि उन्हें उपयोगकर्ताओं को यह बताना है या नहीं कि नाम छोटा कर दिया जाएगा.

डिवाइस ग्रुप

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

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

डिवाइस ग्रुप को Group इकाई के तौर पर दिखाया जाता है. यह HomeDevice से अलग होती है.

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

किसी स्ट्रक्चर में मौजूद सभी डिवाइस ग्रुप देखने के लिए:

for await groups in structure.deviceGroups.batched() {
  for group in groups {
    print("Found group: \(group.name) with ID: \(group.id)")
  }
}

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

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

let groupsManagementTrait = try await structure.traits(Google.GroupManagementTrait)
let _ = try await groupsManagementTrait.createUserDefinedGroup(withName: "Kitchen Lights",
         withDevices: [light1, light2])

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

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

let groupManagementTrait = try await structure.traits(Google.GroupManagementTrait.self)
groupManagementTrait.addGroupMembers(
  groupObjectId: group.id,
  memberDeviceObjectIds = [light3.id],
)

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

let groupManagementTrait = try await structure.traits(Google.GroupManagementTrait.self)
_ = try await groupManagementTrait.removeGroupMembers(
            groupObjectId: group.id,
            memberDeviceObjectIdsArray: Array(removedIDs)

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

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

let groupTrait = group.traits.get(Google.GroupTrait.self)
_ = try await groupTrait.update { $0.name = "Movie Corner" }

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

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

let groupManagementTrait = try await structure.traits.get(Google.GroupManagementTrait.self)

_ = try await groupManagementTrait.deleteGroup(groupObjectId: group.id)