iOS'te Structure API'leri

Structure API'lere iOS için Home API'ler aracılığıyla erişilebilir.

Structure API'leri ile çalışmak için önce GoogleHomeSDK paketini uygulamanıza aktarın:

import GoogleHomeSDK

Hata işleme

Home API'lerindeki bazı yöntemler HomeError oluşturur. Bu nedenle, bu çağrılarda HomeError yakalamak için do-catch bloğu kullanmanızı öneririz.

HomeError işlenirken neyin yanlış gittiğini öğrenmek için code ve message alanlarını kontrol edin.

İşlenmeyen hatalar, uygulamanızın kilitlenmesine neden olur.

Daha fazla bilgi için Hata işleme bölümüne bakın.

Structure API

Home, Ev grafiğini temsil eder ve Structure API'nin giriş noktasıdır. Yapılar, odalar ve cihazlarla ilgili referanslar sağlar.

Structure, ev grafiğinizdeki bir yapıyı temsil eder. id ve name gibi yapı meta verilerine erişim sağlar.

Hesabınızdaki tüm yapıları almak için structures() öğesini kullanın. Yapılar, verilerinin tüketilmesi için çeşitli seçenekler sunan bir Query biçiminde döndürülür:

structures().list() çağrısı, geçerli bir yapı kümesini hemen döndürmeyebilir. Uygulamanız tepkisel ise ve kullanıcı arayüzünü yönlendirmek için tüm yapı değişikliklerine abone olmak üzere stream() işlevini çağırıyorsa sonunda geçerli bir yapı listesi döndürülmelidir. Boş bir yapı listesinin döndürülebileceği başka durumlar da vardır. Örneğin, kullanıcının telefonunun bağlantısı kesilirse veya kullanıcı, uygulamanızın izinlerini iptal ederse. Bu durumları uygulamanızda ele aldığınızdan emin olmalısınız.

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

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

Örnek Structure calls

Bir yapı grubu alma

list() üzerinde Query<Structure> çağrısı yapıldığında en son öğe grubu döndürülür:

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

Tepkisel bir uygulama tasarlarken batched() ve stream() çağrılarını kullanmak isteyeceksiniz. Çünkü bunlar, ana grafik değiştiğinde verileri otomatik olarak üretir.list()

Yapı özelliklerini alma

Elinizde yapıların listesi varken özelliklerine erişebilirsiniz:

// 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 = try await structureChanges.first!

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

Yapıları ada göre bulma

Bir yapının adını biliyorsanız name özelliğini kullanarak da erişebilirsiniz:

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

Buradan her yapı için mülklere, odalara ve cihazlara erişilebilir.

Birden fazla yapıyla çalışma

Birden fazla yapı kullanmak için her yapıya ayrı bir referans alın:

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

Odalar

Bir oda, bir grup cihaz içerir. Bir oda her zaman bir yapının parçasıdır ve bir yapıda birden fazla oda olabilir. Bir yapının odadan kaldırılması, o odadaki cihazları yapıdan kaldırmaz. Ancak oda silinirse odadaki cihazların ataması kaldırılır.

Hesaptaki tüm odaları almak için Home.rooms(), her odadaki ilgili cihazları göstermek için roomID = device.roomID kullanın.

self.home.rooms().batched()
  .combineLatest(self.home.devices().batched())
  .receive(on: DispatchQueue.main)
  .catch { error in
    Logger.error("Failed to load rooms and devices: \(error)")
    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)

Örnek oda aramaları

Oda listesini alma

Home sınıfını kullanarak odaların listesini alabilir ve bu odaların özelliklerine erişebilirsiniz:

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) ")

Oda oluştur

Structure içinde yeni bir oda oluşturmak için:

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

Oda silme

Alternatif olarak, bir odayı şu şekilde de silebilirsiniz:

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

Ayrıca, bir odayı kimliğini kullanarak da silebilirsiniz:

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

Cihaz içeren bir oda silinirse cihazlar yapıda kalmaya devam eder ancak artık bir odaya atanmaz.

Cihazları farklı bir odaya taşıma

Structure simgesiyle cihazları farklı bir odaya da taşıyabilirsiniz:

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

Odanın adını değiştirme

Bir odanın adını değiştirmek için setName(_:) yöntemini çağırın:

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

Bir odanın adı değiştirildiğinde orijinal Room yapısı aynı kalır ve değişiklik, döndürülen güncellenmiş Room nesnesine yansıtılır.

Adlar, 60 Unicode kod noktası (karakter) sınırını aşarsa kesilir ve hata verilmez. Geliştiriciler, uzun adları işlemeyle sorumludur ve örneğin, adların kısaltılacağı konusunda kullanıcıları bilgilendirmek isteyip istemediklerine karar verebilirler.

API listesi

Home örneği oluşturulduktan sonra aşağıdaki Yapı API'lerine bu örnek üzerinden erişilebilir:

Structure aşağıdaki API'leri içerir:

Room aşağıdaki API'lere sahiptir: