Structure APIs unter iOS

bookmark_border Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Auf Gebäude-APIs kann über die Home APIs für iOS zugegriffen werden.

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

import GoogleHomeSDK

Fehlerbehandlung

Einige Methoden in den Home APIs werfen eine HomeError. Wir empfehlen daher, einen do-catch-Block zu verwenden, um HomeError bei diesen Aufrufen zu fangen.

Prüfen Sie bei der Verarbeitung 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.

Gebäude-API

Home steht für das Zuhause-Diagramm und ist der Einstiegspunkt in die Gebäude API. Sie enthält Verweise auf Gebäude, Räume und Geräte.

Structure steht für ein Gebäude in Ihrem Zuhause-Diagramm. Er bietet Zugriff auf Strukturmetadaten wie id und name.

Mit structures() können Sie alle Gebäude in Ihrem Konto abrufen. Die Strukturen werden in Form eines Query zurückgegeben, was verschiedene Möglichkeiten zur Verwendung der Daten bietet:

Der structures().list()-Aufruf gibt möglicherweise nicht sofort eine gültige Gruppe von Gebäuden zurück. Wenn Ihre App reaktiv ist und stream() aufruft, um alle Strukturänderungen zu abonnieren, um die Benutzeroberfläche zu steuern, sollte schließlich eine gültige Liste der Strukturen zurückgegeben werden. Es gibt noch andere Situationen, in denen eine leere Strukturliste zurückgegeben werden kann, z. B. wenn die Verbindung des Smartphones 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)

Beispielaufrufe für Strukturen

Gebäude abrufen

Wenn du list() für ein Query<Structure> aufrufst, wird der letzte Satz 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()

Wenn Sie eine responsive App entwerfen, sollten Sie batched()- und stream()-Aufrufe anstelle von list() verwenden, da damit automatisch Daten generiert werden, wenn sich der Zuhause-Diagramm ändert.

Gebäudeeigenschaften abrufen

Mit der Liste der Gebäude können Sie auf die zugehörigen Properties 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 nach Name suchen

Wenn du den Namen eines Gebäudes kennst, kannst du 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
}

Von dort aus können Sie auf Unterkünfte, Zimmer und Geräte für jedes Gebäude zugreifen.

Mit mehreren Strukturen arbeiten

Wenn Sie mehrere Strukturen verwenden möchten, müssen Sie für jede Struktur einen separaten Verweis 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 mehr 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 für Gruppenbereiche

Liste der Räume abrufen

Mit der Klasse Home können Sie eine Liste der Räume abrufen und auf die zugehörigen Properties 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 einer 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 Raum 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 Gebäude, sind aber keinem Raum mehr zugewiesen.

Geräte in einen anderen Raum verschieben

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

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

API-Liste

Sobald eine Instanz von Home erstellt wurde, können Sie über diese auf die folgenden Gebäude-APIs zugreifen:

Structure bietet die folgenden APIs:

Room hat die folgenden APIs: