Structure APIs unter iOS

Auf die Gebäude-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 Verarbeiten 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 steht für das Zuhause-Diagramm und ist der Einstiegspunkt für die Structure API. Sie enthält Verweise auf Gebäude, Räume und Geräte.

Structure steht für eine Struktur in Ihrem Home-Diagramm. Sie bietet Zugriff auf Strukturmetadaten wie id und name.

Mit structures() können Sie alle Strukturen in Ihrem Konto abrufen. 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 {
      Logger.error("Failed to load structures: \($0)")
      return Just([Structure]())
    }
    .assign(to: \.structures, on: self)

Beispiele 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 = try await 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

Mit der Liste der Gebäude können Sie auf die Attribute 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 = try await structureChanges.first!

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

Gebäude anhand des Namens finden

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 error as HomeError {
  // Code for handling the exception
}

Dort können Sie auf die Immobilien, Zimmer 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 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
}

Zimmer

Ein Raum enthält eine Gruppe von Geräten. Ein Raum ist immer Teil eines Gebäudes und ein Gebäude 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.

Verwenden Sie 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
    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)

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 Attribute 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 error as HomeError {
  // Code for handling the exception
}

Raum löschen

Alternativ können Sie einen Chatroom auch so löschen:

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

Sie können ein Zimmer 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 error 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 kannst du ein Gerät auch in einen anderen Raum verschieben:

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

Name 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.

API-Liste

Nachdem eine Instanz von Home erstellt wurde, sind die folgenden Structure APIs darüber zugänglich:

Das Structure hat die folgenden APIs:

Room hat die folgenden APIs: