API Structure sur iOS

Vous pouvez accéder aux API Structure via les API Home pour iOS.

Pour utiliser les API Structure, commencez par importer le package GoogleHomeSDK dans votre application :

import GoogleHomeSDK

Gestion des exceptions

Certaines méthodes des API Home génèrent une HomeError. Nous vous recommandons donc d'utiliser un bloc do-catch pour intercepter HomeError lors de ces appels.

Lorsque vous gérez HomeError, vérifiez ses champs code et message pour savoir ce qui s'est mal passé.

Toute erreur non gérée entraînera le plantage de votre application.

Pour en savoir plus, consultez Gestion des erreurs.

Structure API

Home représente le graphique Home et constitue le point d'entrée de l'API Structure. Elle fournit des références aux structures, aux pièces et aux appareils.

Structure représente une structure dans votre graphique Home. Il permet d'accéder aux métadonnées de structure telles que id et name.

Utilisez structures() pour obtenir toutes les structures de votre compte. Les structures sont renvoyées sous la forme d'un Query, qui offre plusieurs façons de consommer ses données :

L'appel structures().list() ne renvoie pas forcément immédiatement un ensemble de structures valides. Si votre application est réactive et appelle stream() pour s'abonner à toutes les modifications de structure afin de piloter l'UI, une liste valide de structures devrait finir par être renvoyée. Il existe d'autres situations dans lesquelles une liste de structures vide peut être renvoyée, par exemple si le téléphone de l'utilisateur perd la connectivité ou si l'utilisateur a révoqué les autorisations accordées à votre application. Vous devez vous assurer de gérer ces cas dans votre application.

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

Exemples d'appels de structure

Obtenir un ensemble de structures

L'appel de list() sur un Query<Structure> renvoie l'ensemble d'éléments le plus récent :

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

Lorsque vous concevez une application réactive, vous devez utiliser les appels batched() et stream() plutôt que list(), car ils génèrent automatiquement des données lorsque le graphique Home change.

Obtenir les propriétés de la structure

Une fois la liste des structures en votre possession, vous pouvez accéder à leurs propriétés :

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

Rechercher une structure par son nom

Si vous connaissez le nom d'une structure, vous pouvez également y accéder à l'aide de la propriété name :

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

Vous pouvez ensuite accéder aux propriétés, aux pièces et aux appareils de chaque structure.

Travailler avec plusieurs structures

Pour utiliser plusieurs structures, obtenez une référence distincte pour chacune d'elles :

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
}

Chambres

Une pièce contient un groupe d'appareils. Une pièce fait toujours partie d'une structure, et une structure peut comporter plusieurs pièces. Si vous supprimez une pièce d'une structure, les appareils qui s'y trouvent ne sont pas supprimés de la structure. Toutefois, si la pièce est supprimée, les appareils qui s'y trouvent ne sont plus associés.

Utilisez Home.rooms() pour récupérer toutes les pièces du compte, puis utilisez roomID = device.roomID pour afficher les appareils correspondants dans chaque pièce.

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)

Exemples d'appels Room

Obtenir la liste des salles

À l'aide de la classe Home, vous pouvez obtenir une liste des salles et accéder à leurs propriétés :

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

Créer un salon

Pour créer une pièce dans 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
}

Supprimer une pièce

Vous pouvez également supprimer un salon :

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

Vous pouvez également supprimer une pièce à l'aide de son 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
  }
}

Si une pièce contenant des appareils est supprimée, les appareils resteront dans la structure, mais ne seront plus associés à une pièce.

Déplacer des appareils dans une autre pièce

Structure vous permet également de déplacer un appareil dans une autre pièce :

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

Modifier le nom d'une pièce

Appelez la méthode setName(_:) pour modifier le nom d'une pièce :

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

Lorsque vous modifiez le nom d'une pièce, la structure Room d'origine reste la même et la modification est reflétée dans l'objet Room mis à jour renvoyé.

Liste des API

Une fois une instance de Home créée, les API Structure suivantes sont accessibles via celle-ci :

Structure comporte les API suivantes :

Room comporte les API suivantes :