iOS पर Structure APIs

iOS के लिए, Home API की मदद से स्ट्रक्चर एपीआई को ऐक्सेस किया जा सकता है.

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

import GoogleHomeSDK

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

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

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

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

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

स्ट्रक्चर एपीआई

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

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 की सीमा से ज़्यादा है, तो नाम काट दिया जाएगा. साथ ही, कोई गड़बड़ी नहीं दिखेगी. डेवलपर, लंबे नामों को हैंडल करने के लिए ज़िम्मेदार होते हैं. उदाहरण के लिए, वे यह तय कर सकते हैं कि उन्हें उपयोगकर्ताओं को यह बताना है या नहीं कि नाम काट दिए जाएंगे.