API Structure sur iOS

Les API de structure sont accessibles via les API Home pour iOS.

Pour utiliser les API de structure, importez d'abord 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 do-catch block 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 la section Gestion des erreurs.

API de structure

Home représente le graphique Home et constitue le point d'entrée de l'API de structure. Il 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 la 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'une Query, qui offre plusieurs façons de consommer ses données :

L'appel structures().list() peut ne pas renvoyer immédiatement un ensemble de structures valide. Si votre application est réactive et appelle stream() pour s'abonner à toutes les modifications de structure afin de piloter l'interface utilisateur, une liste de structures valide doit finir par être renvoyée. Dans d'autres cas, 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 de 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 {
      // Failed to load structures
      return Just([Structure]())
    }
    .assign(to: \.structures, on: self)

Exemples d'appels de structure

Obtenir un ensemble de structures

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

// Get a stream of all structures accessible to the user
let allStructuresChanges = 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 main, 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 = 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 _ 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 _ 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
}

Pièces

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 de cette pièce ne sont pas supprimés de la structure. Toutefois, si la pièce est supprimée, les appareils de cette pièce ne sont plus attribué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
    // 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)

Exemples d'appels de pièce

Obtenir la liste des pièces

À l'aide de la classe Home, vous pouvez obtenir la liste des pièces 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 une pièce

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

Supprimer une pièce

Vous pouvez également supprimer une pièce :

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

Si une pièce contenant des appareils est supprimée, les appareils restent dans la structure, mais ne sont plus attribué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 _ as HomeError {
  // Code for handling the exception
}

Modifier le nom d'une pièce

Appelez la setName(_:) méthode 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é.

Les noms seront tronqués s'ils dépassent la limite de 60 points de code Unicode (caractères), et aucune erreur ne sera générée. Les développeurs sont responsables de la gestion des noms longs et peuvent, par exemple, décider s'ils souhaitent informer les utilisateurs que les noms seront tronqués.