Structure API di iOS

Structure API dapat diakses melalui Home API untuk iOS.

Untuk menggunakan Structure API, impor paket GoogleHomeSDK terlebih dahulu ke dalam aplikasi Anda:

import GoogleHomeSDK

Penanganan error

Beberapa metode di Home API memunculkan HomeError, jadi sebaiknya Anda menggunakan blok do-catch untuk menangkap HomeError pada panggilan tersebut.

Saat menangani HomeError, periksa kolom code dan message untuk mengetahui penyebab masalahnya.

Error yang tidak ditangani akan menyebabkan aplikasi Anda error.

Untuk mengetahui informasi selengkapnya, lihat Penanganan error.

Structure API

Home merepresentasikan grafik Home, dan merupakan titik entri ke Structure API. Menyediakan referensi ke struktur, ruangan, dan perangkat.

Structure merepresentasikan struktur di grafik Rumah Anda. API ini memberikan akses ke metadata struktur seperti id dan name.

Gunakan structures() untuk mendapatkan semua struktur di akun Anda. Struktur ditampilkan dalam bentuk Query, yang menawarkan pilihan cara menggunakan datanya:

Panggilan structures().list() mungkin tidak langsung menampilkan kumpulan struktur yang valid. Jika aplikasi Anda reaktif dan memanggil stream() untuk berlangganan semua perubahan struktur untuk mendorong UI, daftar struktur yang valid pada akhirnya akan ditampilkan. Ada situasi lain saat daftar struktur kosong dapat ditampilkan, misalnya jika ponsel pengguna kehilangan konektivitas atau jika pengguna telah mencabut izin ke aplikasi Anda. Anda harus memastikan untuk menangani kasus ini di aplikasi Anda.

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

Contoh panggilan Struktur

Mendapatkan serangkaian struktur

Memanggil list() pada Query<Structure> akan menampilkan Set elemen terbaru:

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

Saat mendesain aplikasi reaktif, Anda sebaiknya menggunakan panggilan batched() dan stream() daripada list(), karena panggilan ini otomatis menghasilkan data saat grafik beranda berubah.

Mendapatkan properti struktur

Dengan daftar struktur yang ada, Anda dapat mengakses propertinya:

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

Menemukan struktur berdasarkan nama

Jika mengetahui nama struktur, Anda juga dapat mengaksesnya menggunakan properti name:

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

Dari sana, properti, ruangan, dan perangkat untuk setiap struktur dapat diakses.

Bekerja dengan beberapa struktur

Untuk menggunakan lebih dari satu struktur, dapatkan referensi terpisah untuk setiap struktur:

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
}

Kamar

Ruangan berisi sekelompok perangkat. Ruang selalu menjadi bagian dari struktur dan struktur dapat memiliki beberapa ruang. Menghapus ruangan dari struktur tidak akan menghapus perangkat di ruangan tersebut dari struktur. Namun, jika ruangan dihapus, perangkat di ruangan tersebut akan dibatalkan penetapannya.

Gunakan Home.rooms() untuk mengambil semua ruangan dalam akun, lalu gunakan roomID = device.roomID untuk menampilkan perangkat yang sesuai di setiap ruangan.

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)

Panggilan Sample Room

Mendapatkan daftar ruang

Dengan menggunakan class Home, Anda bisa mendapatkan daftar ruang dan mengakses propertinya:

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

Buat ruang

Untuk membuat ruangan baru di 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
}

Menghapus ruangan

Atau, Anda dapat menghapus ruangan:

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

Anda juga dapat menghapus ruang menggunakan ID-nya:

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

Jika ruangan dengan perangkat dihapus, perangkat akan tetap berada dalam struktur, tetapi tidak lagi ditetapkan ke ruangan.

Memindahkan perangkat ke ruangan lain

Structure juga memungkinkan Anda memindahkan perangkat ke ruangan lain:

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

Mengubah nama ruangan

Panggil metode setName(_:) untuk mengubah nama ruangan:

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

Saat mengubah nama ruangan, struct Room asli tetap sama dan perubahan tercermin dalam objek Room yang diperbarui yang ditampilkan.

Nama akan dipotong jika melebihi batas 60 poin kode Unicode (karakter) dan tidak ada error yang akan ditampilkan. Developer bertanggung jawab untuk menangani nama panjang dan, misalnya, dapat memutuskan apakah mereka ingin memberi tahu pengguna bahwa nama akan dipangkas.

Grup perangkat

Grup perangkat mewakili kumpulan perangkat yang ditentukan pengguna dalam satu struktur.

Seperti ruang fisik, grup perangkat termasuk dalam satu struktur. Namun, tidak seperti ruangan, grup perangkat adalah pengelompokan logis. Perangkat dapat termasuk dalam beberapa grup perangkat secara bersamaan. Grup perangkat dapat berisi hingga 100 perangkat.

Grup perangkat diwakili oleh entitas Group, yang berbeda dari HomeDevice.

Mendapatkan daftar grup perangkat

Untuk mengamati semua grup perangkat dalam struktur:

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

Membuat grup perangkat

Gunakan GroupManagementTrait pada struktur untuk membuat grup perangkat:

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

Mengelola keanggotaan grup

Untuk menambahkan anggota ke grup yang ada:

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

Untuk menghapus anggota dari grup:

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

Mengubah nama grup perangkat

Untuk mengganti nama grup perangkat, perbarui kolom name GroupTrait:

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

Menghapus grup perangkat

Untuk menghapus grup perangkat dari struktur:

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

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