Structurer des API

Vous pouvez accéder aux API Structure via les API Home. Importez ces packages dans votre application:

import com.google.home.Home
import com.google.home.Id
import com.google.home.Structure

Gestion des exceptions

Toute méthode des API Home peut générer une exception HomeException. Nous vous recommandons donc d'utiliser un bloc try-catch pour intercepter les exceptions HomeException sur tous les appels.

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

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

Pour en savoir plus, consultez la section Gestion des erreurs.

Exemples d'appels

Obtenir la liste des structures

Une fois initialisé, un appel structures() renvoie un flux de structures auquel vous avez accès:

// Get a flow of all structures accessible to the user
val allStructuresFlow: HomeObjectsFlow<Structure> = home.structures()

// Calling list() on a HomeObjectsFlow returns the first Set of elements.
val allStructures: Set<Structure> = allStructuresFlow.list()

L'API structures() est un flux qui ne renvoie pas nécessairement immédiatement une liste valide de structures. Si votre application est réactive et s'abonne à ce flux pour piloter l'UI, une liste valide de structures devrait être renvoyée. 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.

Si le langage impératif est fortement requis au lieu du langage réactif, vous pouvez également utiliser un opérateur de flux terminal:

val everyStructure = withTimeout(5000) { home.structures().first { it.isNotEmpty() } }

Cet appel attend qu'une liste valide de structures soit transmise via le flux et expire si la liste n'est pas reçue dans un délai défini par l'application.

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 flow on a structure. Flow emits new values on structure metadata changes: name.
val structureFlow: Flow<Structure> = home.structures().itemFlow(myStructureId)

// Get a snapshot of the structure.
val structure: Structure = structureFlow.first()

// Get structure properties
println("id ${structure.id}")
println("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:

val myHome = home.structures().list().first { it.name == "My home" }

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? = null
var structure2: Structure? = null

try {
  structure1 = home.structures().list().firstOrNull { it.name == "Main House" }
} catch (e: HomeException) {
  // Code for handling the exception
}
try {
  structure2 = home.structures().list().firstOrNull { it.name == "Guest Cottage" }
} catch (e: HomeException) {
  // Code for handling the exception
}

Obtenir la liste des salles

Une fois que vous avez une structure en main, vous pouvez obtenir la liste des pièces et accéder aux propriétés associées:

val allRoomsFlow: HomeObjectsFlow<Room> = structure.rooms()
val allRooms: Set<Room> = allRoomsFlow.list()
val room: Room = allRooms.first()

println("id ${room.id}")
println("name ${room.name}")

Créer un salon

Pour créer une pièce:

val testName = "Test Room Name"
val newRoom: Room = structure.createRoom(testName)

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 salle à l'aide d'un simple ID:

val roomToDelete1 = allRooms.filter { it.id == testRoomId }.firstOrNull()
structure.deleteRoom(roomToDelete1!!)

Si vous supprimez une pièce contenant 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

Une fois que vous avez créé une structure, vous pouvez déplacer des appareils vers une autre pièce de cette structure:

val room2 = structure.rooms().get(Id("room_id_other_structure"))
    val device1 = structure.devices().get(Id("device_id1"))
    structure.moveDevicesToRoom(room2!!, listOf(device1!!))

Si vous ne disposez que des ID de l'appareil et de la pièce, vous pouvez également déplacer des appareils:

structure.moveDevicesToRoom(Id("room_id_other_structure"), listOf(Id("device_id1")))

Automatisations

Le point d'entrée de l'API Automation passe par une structure. Pour en savoir plus sur les automatisations dans les API Home, consultez la section Concevoir une automatisation.

Liste des API

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

API Description
structures() Récupérez toutes les structures du compte Google. Affiche un objet HomeObjectsFlow qui fournit d'autres options de récupération et de filtrage.

Une fois que vous disposez d'un Structure, les API suivantes sont accessibles via celui-ci:

API Description
automations() Répertorie toutes les automatisations appartenant à la structure. Seules les automatisations créées via les API Home sont renvoyées.
createAutomation(automation) Créez une instance d'automatisation pour une structure.
createRoom(name) Créez une salle avec le nom donné par l'utilisateur.
deleteAutomation(automationId) Supprimez une instance d'automatisation à l'aide de son ID.
deleteRoom(roomId) Supprimez une pièce en indiquant son ID.
devices() Récupérez tous les appareils de la structure. Renvoie un objet HomeObjectsFlow.
getAutomation(automationId) Obtenez une instance d'automatisation à partir de son ID.
getSourceConnectivity(trait) Obtenir les métadonnées d'un trait spécifique Renvoie un objet SourceConnectivity.
has(trait) Vérifiez si la caractéristique actuellement demandée est compatible avec l'appareil.
id Identifiant système unique de la structure.
moveDevicesToRoom(roomId, deviceIds) Déplacez les appareils vers un autre ID de pièce dans la structure.
name Nom de la structure fourni par l'utilisateur.
rooms() Obtenez toutes les pièces de la structure. Renvoie un objet HomeObjectsFlow.
trait(trait) Obtenez un instantané actuel des attributs des traits.

Certaines API courantes (telles que devices(), id et name) sont également disponibles pour un Room.