Structure APIs unter iOS

Auf die Structure APIs kann über die Home APIs für iOS zugegriffen werden.

Wenn Sie die Structure APIs verwenden möchten, müssen Sie zuerst das GoogleHomeSDK-Paket in Ihre App importieren:

import GoogleHomeSDK

Fehlerbehandlung

Einige Methoden in den Home APIs geben HomeError aus. Wir empfehlen daher, einen do-catch-Block zu verwenden, um HomeError bei diesen Aufrufen abzufangen.

Prüfen Sie beim Beheben von HomeError die Felder code und message, um herauszufinden, was schiefgelaufen ist.

Alle nicht behandelten Fehler führen zum Absturz Ihrer App.

Weitere Informationen finden Sie unter Fehlerbehandlung.

Structure API

Home stellt den Home-Graphen dar und ist der Einstiegspunkt für die Structure API. Sie enthält Verweise auf Gebäude, Räume und Geräte.

Structure stellt eine Struktur in Ihrem Home Graph dar. Es bietet Zugriff auf Strukturmetadaten wie id und name.

Verwenden Sie structures(), um alle Strukturen in Ihrem Konto abzurufen. Die Strukturen werden in Form eines Query zurückgegeben, das verschiedene Möglichkeiten bietet, die Daten zu nutzen:

Der structures().list()-Aufruf gibt möglicherweise nicht sofort einen gültigen Satz von Strukturen zurück. Wenn Ihre App reaktiv ist und stream() aufruft, um alle Strukturänderungen für die Benutzeroberfläche zu abonnieren, sollte schließlich eine gültige Liste von Strukturen zurückgegeben werden. Es gibt auch andere Situationen, in denen eine leere Strukturliste zurückgegeben werden kann, z. B. wenn die Verbindung zum Smartphone des Nutzers unterbrochen wird oder der Nutzer die Berechtigungen für Ihre App widerrufen hat. Sie sollten diese Fälle in Ihrer App berücksichtigen.

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

Beispiel für Strukturaufrufe

Eine Reihe von Strukturen abrufen

Wenn Sie list() für ein Query<Structure> aufrufen, wird die letzte Gruppe von Elementen zurückgegeben:

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

Beim Entwerfen einer reaktiven App sollten Sie batched()- und stream()-Aufrufe anstelle von list() verwenden, da diese automatisch Daten erzeugen, wenn sich der Home-Graph ändert.

Struktureigenschaften abrufen

Anhand der Liste der Gebäude können Sie auf die zugehörigen Eigenschaften zugreifen:

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

Gebäude anhand des Namens suchen

Wenn Sie den Namen einer Struktur kennen, können Sie auch über das Attribut name darauf zugreifen:

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

Von dort aus können Sie auf die Properties, Räume und Geräte für jede Struktur zugreifen.

Mit mehreren Strukturen arbeiten

Wenn Sie mehrere Strukturen verwenden möchten, müssen Sie für jede Struktur eine separate Referenz abrufen:

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
}

Zimmer

Ein Raum enthält eine Gruppe von Geräten. Ein Raum ist immer Teil einer Struktur und eine Struktur kann mehrere Räume haben. Wenn Sie einen Raum aus einem Gebäude entfernen, werden die Geräte in diesem Raum nicht aus dem Gebäude entfernt. Wenn der Raum jedoch gelöscht wird, werden die Geräte in diesem Raum nicht zugewiesen.

Verwende Home.rooms(), um alle Räume im Konto abzurufen, und dann roomID = device.roomID, um die entsprechenden Geräte in jedem Raum anzuzeigen.

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)

Beispielanrufe in Räumen

Liste der Räume abrufen

Mit der Klasse Home können Sie eine Liste der Räume abrufen und auf die zugehörigen Eigenschaften zugreifen:

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

Chatroom erstellen

So erstellen Sie einen neuen Raum in einem 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
}

Raum löschen

Alternativ können Sie einen Raum löschen:

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

Sie können einen Raum auch anhand seiner ID löschen:

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

Wenn ein Raum mit Geräten gelöscht wird, befinden sich die Geräte weiterhin im Zuhause, sind aber keinem Raum mehr zugewiesen.

Geräte in einen anderen Raum verschieben

Mit Structure können Sie ein Gerät auch in einen anderen Raum verschieben:

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

Namen eines Raums ändern

Rufen Sie die Methode setName(_:) auf, um den Namen eines Raums zu ändern:

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

Wenn Sie den Namen eines Raums ändern, bleibt die ursprüngliche Room-Struktur unverändert und die Änderung wird im zurückgegebenen aktualisierten Room-Objekt widergespiegelt.

Namen werden abgeschnitten, wenn sie das Limit von 60 Unicode-Codepunkten (Zeichen) überschreiten. Es werden keine Fehler ausgegeben. Entwickler sind dafür verantwortlich, lange Namen zu verarbeiten. Sie können beispielsweise entscheiden, ob sie Nutzer darüber informieren möchten, dass Namen gekürzt werden.

Gerätegruppen

Eine Gerätegruppe ist eine nutzerdefinierte Sammlung von Geräten innerhalb einer einzelnen Struktur.

Wie physische Räume gehören Gerätegruppen zu einer einzelnen Struktur. Im Gegensatz zu Räumen sind Gerätegruppen jedoch logische Gruppierungen. Ein Gerät kann gleichzeitig mehreren Gerätegruppen angehören. Gerätegruppen können bis zu 100 Geräte enthalten.

Gerätegruppen werden durch die Group-Entität dargestellt, die sich von HomeDevice unterscheidet.

Liste der Gerätegruppen abrufen

So sehen Sie alle Gerätegruppen in einer Struktur:

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

Gerätegruppe erstellen

Verwenden Sie GroupManagementTrait für die Struktur, um eine Gerätegruppe zu erstellen:

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

Gruppenmitgliedschaft verwalten

So fügen Sie einer bestehenden Gruppe Mitglieder hinzu:

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

So entfernen Sie Mitglieder aus einer Gruppe:

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

Name einer Gerätegruppe ändern

Wenn Sie eine Gerätegruppe umbenennen möchten, aktualisieren Sie das Feld name des GroupTrait:

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

Gerätegruppe löschen

So löschen Sie eine Gerätegruppe aus einem Zuhause:

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

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