API Structure su iOS

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

È possibile accedere alle API Structure tramite le API Home per iOS.

Per utilizzare le API Structure, importa prima il pacchetto GoogleHomeSDK nella tua app:

import GoogleHomeSDK

Gestione degli errori

Alcuni metodi nelle API Home generano un HomeError, pertanto ti consigliamo di utilizzare un blocco do-catch per intercettare HomeError in queste chiamate.

Quando gestisci HomeError, controlla i campi code e message per scoprire cosa è andato storto.

Eventuali errori non gestiti causeranno l'arresto anomalo dell'app.

Per ulteriori informazioni, consulta Gestione degli errori.

API Structure

Home rappresenta il grafo della casa ed è il punto di contatto dell'API Structure. Fornisce riferimenti a strutture, stanze e dispositivi.

Structure rappresenta una struttura nel grafico della casa. Fornisce l'accesso ai metadati della struttura, come id e name.

Utilizza structures() per visualizzare tutte le strutture nel tuo account. Le strutture vengono restituite sotto forma di Query, che offre una scelta di modi per utilizzare i relativi dati:

La chiamata structures().list() potrebbe non restituire immediatamente un insieme valido di strutture. Se la tua app è reattiva e chiama stream() per iscriversi a tutte le modifiche della struttura per gestire l'interfaccia utente, dovrebbe essere restituito un elenco valido di strutture. Esistono altre situazioni in cui potrebbe essere restituito un elenco di strutture vuoto, ad esempio se lo smartphone dell'utente perde la connettività o se l'utente ha revocato le autorizzazioni per la tua app. Assicurati di gestire questi casi nella tua app.

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

Chiamate di esempio alla struttura

Ottenere un insieme di strutture

La chiamata a list() su un Query<Structure> restituisce l'insieme di elementi più recente:

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

Quando progetti un'app reattiva, ti consigliamo di utilizzare le chiamate batched() e stream() anziché list(), perché producono automaticamente dati quando il grafico della casa cambia.

Recupera le proprietà della struttura

Una volta ottenuto l'elenco delle strutture, puoi accedere alle relative proprietà:

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

Trovare una struttura per nome

Se conosci il nome di una struttura, puoi accedervi anche utilizzando la proprietà name:

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

Da qui, puoi accedere a proprietà, stanze e dispositivi per ogni struttura.

Lavorare con più strutture

Per utilizzare più di una struttura, ottieni un riferimento separato per ogni struttura:

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
}

Camere

Una stanza contiene un gruppo di dispositivi. Una camera fa sempre parte di una struttura e una struttura può avere più camere. La rimozione di una stanza da una struttura non comporta la rimozione dei dispositivi al suo interno. Tuttavia, se la stanza viene eliminata, i dispositivi al suo interno vengono annullati.

Utilizza Home.rooms() per recuperare tutte le stanze dell'account, quindi roomID = device.roomID per visualizzare i dispositivi corrispondenti in ogni stanza.

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)

Chiamate di esempio con Room

Ottenere un elenco di stanze

Utilizzando la classe Home, puoi ottenere un elenco di stanze e accedere alle proprietà corrispondenti:

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

Crea una stanza virtuale

Per creare una nuova stanza in un 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
}

Eliminare una stanza

In alternativa, puoi eliminare una stanza:

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

Puoi anche eliminare una camera utilizzando il relativo ID:

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

Se una camera con dispositivi viene eliminata, i dispositivi rimarranno nella struttura, ma non saranno più assegnati a una camera.

Spostare i dispositivi in un'altra stanza

Structure ti consente anche di spostare un dispositivo in un'altra stanza:

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

Modificare il nome di una stanza

Chiama il metodo setName(_:) per modificare il nome di una stanza:

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

Quando cambi il nome di una stanza, la struttura Room originale rimane invariata e la modifica viene applicata all'oggetto Room aggiornato restituito.

elenco delle API

Una volta creata un'istanza di Home, tramite questa sono accessibili le seguenti API Structure:

Structure ha le seguenti API:

Room dispone delle seguenti API: