iOS'te Structure API'leri

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

Structure API'lerle çalışmak için öncelikle GoogleHomeSDK paketini uygulamanıza aktarın:

import GoogleHomeSDK

Hata işleme

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

HomeError işlerken 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, Home 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()'ı kullanın. Yapılar, verilerinin kullanım şekliyle ilgili seçenekler sunan bir Query biçiminde döndürülür:

structures().list() çağrısı, geçerli bir yapı grubu 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 telefonu bağlantıyı kaybederse 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 {
      // Failed to load structures
      return Just([Structure]())
    }
    .assign(to: \.structures, on: self)

Örnek Structure Calls

Bir yapı grubu alma

Query<Structure> üzerinde list() adlı işlevi çağırmak, en son öğe grubunu döndürür:

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

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

Yapı özelliklerini alma

Elinizde yapıların listesi varken bunların ö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 = 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 _ 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 _ 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
}

Odalar

Bir odada bir grup cihaz bulunur. Bir oda her zaman bir yapının parçasıdır ve bir yapıda birden fazla oda olabilir. Bir odayı yapıdan kaldırmak, 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
    // 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)

Örnek Room görüşmeleri

Odaların listesini alma

Home sınıfını kullanarak odaların listesini alabilir ve ö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 _ as HomeError {
  // Code for handling the exception
}

Oda silme

Alternatif olarak, bir odayı silebilirsiniz:

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

Ayrıca, odaları kimliklerini kullanarak da silebilirsiniz:

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

Cihazların bulunduğu bir oda silinirse cihazlar yapıda kalmaya devam eder ancak artık bir odaya atanmaz.

Cihazları farklı bir odaya taşıma

Structure simgesi, cihazları farklı bir odaya taşımanıza da olanak tanır:

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

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

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

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 kısaltılır ve hata verilmez. Geliştiriciler, uzun adları işlemeyle sorumludur ve örneğin, kullanıcılara adların kısaltılacağını bildirmek isteyip istemediklerine karar verebilirler.

Cihaz grupları

Cihaz grubu, tek bir yapı içindeki kullanıcı tanımlı cihaz koleksiyonunu temsil eder.

Fiziksel odalar gibi, cihaz grupları da tek bir yapıya aittir. Ancak odaların aksine, cihaz grupları mantıksal gruplandırmalardır. Bir cihaz aynı anda birden fazla cihaz grubuna ait olabilir. Cihaz grupları en fazla 100 cihaz içerebilir.

Cihaz grupları, HomeDevice öğesinden farklı olan Group öğesiyle temsil edilir.

Cihaz gruplarının listesini alma

Bir yapıdaki tüm cihaz gruplarını gözlemlemek için:

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

Cihaz grubu oluşturma

Cihaz grubu oluşturmak için yapıda GroupManagementTrait simgesini kullanın:

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

Grup üyeliğini yönetme

Mevcut bir gruba üye eklemek için:

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

Gruptan üye çıkarmak için:

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

Cihaz grubunun adını değiştirme

Bir cihaz grubunu yeniden adlandırmak için GroupTrait alanının name bölümünü güncelleyin:

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

Cihaz grubunu silme

Bir cihaz grubunu yapıdan silmek için:

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

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