Principes de base du langage

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

Comprendre le langage YAML

YAML est un langage populaire utilisé pour spécifier la configuration logicielle. Il permet de représenter des informations structurées de manière claire et lisible. Voici quelques notions de base que vous devez connaître sur le YAML avant de créer votre première automatisation. Pour en savoir plus sur YAML en général, consultez la spécification de la version 1.1.

Paires clé/valeur

Les documents YAML sont essentiellement une collection de paires clé-valeur. Dans l'exemple suivant, la clé est name et la valeur est TV on lights off. La clé et la valeur sont séparées par un deux-points suivi d'un espace. Les deux caractères sont obligatoires pour un fichier YAML bien formé.

name: TV on lights off

Valeurs

La valeur associée à une clé peut être aussi simple qu'une chaîne, un nombre ou une date, ou aussi complexe qu'une autre collection de paires clé-valeur.

Cordes

Si une valeur de chaîne commence par l'un des caractères suivants: [, {, ", ' ou #, ou si la chaîne contient : (un deux-points suivi d'espaces), elle doit être placée entre guillemets.

Les guillemets simples et doubles sont acceptés, mais le guillemet fermant doit correspondre au guillemet ouvrant.

Citation correcte:

name: 'TV on lights off'

name: "TV on lights off"

Usage incorrect des guillemets (guillemets incohérents):

name: 'TV on lights off"

Les guillemets sont facultatifs pour tous les autres types de chaînes.

Si vous avez besoin d'une chaîne multiligne, consultez la section de la spécification YAML sur les scalaires multilignes.

name: "[1] TV"
name: '{1} TV'
name: '#TV'
name: '"1" TV'
name: "'1' TV"
name: "\"1\" TV"
name: "TV: bedroom"

Paires clé-valeur imbriquées

Ici, la valeur de la clé metadata est une liste de deux paires clé-valeur (name et description):

metadata:
  name: TV on lights off
  description: Turn off lights when TV turns on

Retrait

YAML utilise des retraits pour indiquer la structure. Dans l'exemple précédent, name et description sont mis en retrait (de deux espaces) pour indiquer qu'il s'agit d'enfants de la clé metadata.

La mise en retrait est stricte en YAML. Une structure enfant doit avoir une indentation plus profonde que sa structure parente, et les paires clé-valeur de même niveau doivent avoir la même indentation.

metadata:
  name:
    en: TV on lights off
  description:
    en: Turn off lights when TV turns on

Plusieurs valeurs

Si une clé donnée comporte plusieurs valeurs, chaque valeur est listée sur une nouvelle ligne, et chaque ligne commence par un trait d'union et un espace. Dans l'exemple suivant, il existe deux listes:

1. Une automatisation peut comporter plusieurs starters. Par conséquent, le premier déclencheur commence par un trait d'union et un espace.
2. weekday peut avoir plusieurs valeurs. Par conséquent, chaque valeur est mise en retrait et commence par un tiret et un espace.

starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

Commentaires

Tout texte suivant un # est considéré comme un commentaire et est ignoré par le moteur d'automatisation.

Une ligne commençant par # est un commentaire.

Un commentaire peut apparaître sur la même ligne que le contenu du script, mais # doit être précédé d'un espace.

# This is a comment. It will be ignored.
name: chromecast #This is a TV.

Script d'automatisation

La spécification de la syntaxe des scripts d'automatisation s'appelle le schéma.

Le schéma "Automations" définit deux structures de données:

• Une seule paire clé-valeur est appelée champ.
• Une collection de champs définis par le schéma est appelée struct.

Struct

Le langage de script d'automatisation définit plusieurs "blocs" ou structures de données standards, appelés structs.

Examinez la struct automation, qui définit quatre champs:

La section Référence fournit des définitions de schéma pour toutes les structures disponibles.

Les noms de clé sont uniques dans une struct donnée et sont sensibles à la casse.

Les types de valeurs possibles sont les suivants:

• Un type primitif: booléen, nombre, chaîne, heure, etc.
• Type Struct: collection de champs.
• Tableau du type de données. Le tableau est indiqué par []. Par exemple, [string] est un tableau de chaînes, et [Starter] est un tableau de structures de démarrage.
• Autres types spéciaux: Entity, FieldPath.

La description de chaque champ contient des informations importantes, y compris les suivantes:

• "Obligatoire" ou "Facultatif", indiquant si le champ est obligatoire ou s'il peut être ignoré.
• Dépendance de champ. Seules les dépendances sont associées aux champs facultatifs. Il décrit les vérifications supplémentaires lorsque vous utilisez ce champ, par exemple Utiliser le champ B uniquement si le champ A est défini ou Lorsque le champ A est utilisé, ne pas définir le champ B ou le champ C.
• Valeurs possibles Par exemple, l'ensemble de valeurs limité d'un champ Enum de type chaîne ou une plage de nombres pouvant être utilisés dans un champ de type nombre.

Struct typée

Certaines structures peuvent représenter des déclencheurs en fonction d'un calendrier ou d'un changement d'état de l'appareil. Chaque type de starter doit fournir un ensemble distinct de champs.

# A time schedule starter.
starter:
  type: time.schedule
  at: 10:00

# A device state change starter.
starter:
  type: device.state.OnOff
  device: TV - Living Room
  state: on
  is: true

Un starter est une struct typée, qui est étendue par d'autres structs enfants dans le champ type, tels que time.schedule ou device.state.OnOff, pour fournir différentes fonctions. Les structs condition et action sont également typées.

Les champs supplémentaires de la structure doivent respecter la spécification de la structure enfant (type). Par exemple, lorsque vous utilisez device.state.OnOff comme type, seuls les champsspécifiés pour ce type sont valides dans cette struct starter.

Tableau

En YAML, un tableau de valeurs commence par - (un tiret suivi d'un espace). Le tableau peut contenir plusieurs valeurs Struct ou plusieurs valeurs primitives. Toutefois, les valeurs du tableau doivent être du même type.

Lorsque le tableau ne contient qu'un seul élément, vous pouvez omettre le tiret et l'espace:

# The starters field accepts an array of Starter Structs.
# This is the standard format.
starters:
- type: time.schedule
  at: sunset
- type: time.schedule
  at: sunrise

# The dash can be omitted if the array only has one item.
# This is also valid.
starters:
  type: time.schedule
  at: sunset

Les tableaux multidimensionnels, comme [[1, 2], [3, 4]], ne sont pas compatibles avec l'écriture de script d'automatisation. L'analyseur de langage aplatit automatiquement un tableau multidimensionnel en un tableau à dimension unique, dans ce cas [1, 2, 3, 4].

# INVALID: multi-dimensional array
- - 1
  - 2
- - 3
  - 4

Primitif

Le schéma de script Automations accepte les types de données primitifs suivants:

Couleur

Les couleurs peuvent être spécifiées de trois manières : à l'aide des types primitifs ColorHex ou ColorTemperature, ou à l'aide du type composé SpectrumHSV.

SpectrumHSV

Le type SpectrumHSV spécifie une couleur à l'aide de trois champs numériques:

• La teinte correspond à la longueur d'onde de la couleur.
• La saturation indique l'intensité de la couleur.
• La valeur indique la luminosité ou l'obscurité relative de la couleur.

Dynamique

Parfois, le type de données d'une clé n'est pas fixe. Il peut s'agir de l'un des types primitifs, en fonction des valeurs d'autres champs.

is est un exemple de champ de type de données dynamique. Le type réel est déterminé par les valeurs des champs type et state.

# The 'is' field accepts a number type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1

# The 'is' field accepts a boolean type.
type: device.state.OnOff
device: My TV - Living Room
state: on
is: false

Entité

Format de chaîne spécial permettant d'identifier de manière unique une entité appartenant à l'utilisateur, telle qu'un appareil ou une pièce.

L'appareil est l'entité la plus couramment utilisée dans les automatisations. Le format de la chaîne d'entité est device name - room name.

# The device field accepts a Device Entity type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1

FieldPath

Format de chaîne spécial utilisé pour localiser un élément de données dans une charge utile de données. Dans l'exemple suivant, currentVolume est le FieldPath du champ state.

# The state field accepts a FieldPath type.
starters:
  type: device.state.Volume
  device: My TV - Living Room
  state: currentVolume
  is: 5

D'autres FieldPaths peuvent nécessiter plusieurs niveaux pour accéder à l'élément requis, et le format diffère entre le déclencheur et l'action.

Les déclencheurs utilisent une notation à points, avec l'ensemble du chemin d'accès dans le même champ. Cela est principalement effectué à des fins de comparaison dans la logique de démarrage. Par exemple, pour utiliser la température de couleur comme déclencheur, vous devez utiliser color.colorTemperature pour l'état:

starters:
- type: device.state.ColorSetting
  device: My Device - Room Name
  state: color.colorTemperature
  is: 2000K

Les actions, en revanche, utilisent des champs imbriqués. Pour définir la couleur d'une ampoule sur bleu, au lieu de color.name et is: blue, procédez comme suit:

actions:
- type: device.command.ColorAbsolute
  devices: My Device - Room Name
  color:
    name: blue