API Structure sur iOS

Les API Structure sont accessibles 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 exception HomeError. Nous vous recommandons donc d'utiliser un bloc do-catch pour intercepter HomeError lors de ces appels.

Lorsque vous gérez des HomeError, vérifiez leurs champs code et message pour connaître l'origine du problème.

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 Home 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 Home Graph. 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 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 de structures valide doit être renvoyée à terme. 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 veiller à 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 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 = 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 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
}

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 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
    // 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 Room

Obtenir la liste des salles

À l'aide de la classe Home, vous pouvez obtenir une 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 un salon

Pour créer un salon dans un 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 un espace :

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

Vous pouvez également supprimer un salon à 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 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 _ 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é.

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. Par exemple, ils peuvent décider d'informer les utilisateurs que les noms seront tronqués.

Groupes d'appareils

Un groupe d'appareils représente une collection d'appareils définie par l'utilisateur au sein d'une même structure.

Comme les pièces physiques, les groupes d'appareils appartiennent à une seule structure. Mais contrairement aux pièces, les groupes d'appareils sont des regroupements logiques. Un appareil peut appartenir à plusieurs groupes d'appareils à la fois. Les groupes d'appareils peuvent contenir jusqu'à 100 appareils.

Les groupes d'appareils sont représentés par l'entité Group, qui est distincte de HomeDevice.

Obtenir la liste des groupes d'appareils

Pour observer tous les groupes d'appareils d'une structure :

for await groups in structure.deviceGroups.batched() {
  for group in groups {
    print("Found group: \(group.name) with ID: \(group.id)")
  }
}

Créer un groupe d'appareils

Utilisez GroupManagementTrait sur la structure pour créer un groupe d'appareils :

let groupsManagementTrait = try await structure.traits(Google.GroupManagementTrait)
let _ = try await groupsManagementTrait.createUserDefinedGroup(withName: "Kitchen Lights",
         withDevices: [light1, light2])

Gérer les groupes

Pour ajouter des membres à un groupe existant :

let groupManagementTrait = try await structure.traits(Google.GroupManagementTrait.self)
groupManagementTrait.addGroupMembers(
  groupObjectId: group.id,
  memberDeviceObjectIds = [light3.id],
)

Pour supprimer des membres d'un groupe :

let groupManagementTrait = try await structure.traits(Google.GroupManagementTrait.self)
_ = try await groupManagementTrait.removeGroupMembers(
            groupObjectId: group.id,
            memberDeviceObjectIdsArray: Array(removedIDs)

Modifier le nom d'un groupe d'appareils

Pour renommer un groupe d'appareils, mettez à jour le champ name de GroupTrait :

let groupTrait = group.traits.get(Google.GroupTrait.self)
_ = try await groupTrait.update { $0.name = "Movie Corner" }

Supprimer un groupe d'appareils

Pour supprimer un groupe d'appareils d'une structure :

let groupManagementTrait = try await structure.traits.get(Google.GroupManagementTrait.self)

_ = try await groupManagementTrait.deleteGroup(groupObjectId: group.id)