API Structure sur iOS

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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

Pour utiliser les API 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 exception HomeError. Nous vous recommandons donc d'utiliser un bloc do-catch pour intercepter les exceptions HomeError sur 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 Structure

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

Structure représente une structure dans votre graphique de la maison. 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:

Il est possible que l'appel structures().list() ne renvoie pas 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'UI, une liste valide de structures devrait être renvoyée à terme. Il existe d'autres situations où 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. Veillez à 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

Appeler 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 des appels batched() et stream() plutôt que list(), car ils génèrent automatiquement des données lorsque le graphique de la maison 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 = try await structureChanges.first!

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

Rechercher une structure par 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.

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

Utilisez Home.rooms() pour récupérer toutes les pièces du compte, puis 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 la liste des salles et accéder aux propriétés associées:

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 chambre à 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 vous supprimez une pièce avec des appareils, ceux-ci 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 vers 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 le changement est reflété dans l'objet Room mis à jour renvoyé.

Liste des API

Une fois une instance de Home créée, les API Structure suivantes y sont accessibles:

Structure dispose des API suivantes:

Room dispose des API suivantes: