Comprendre YAML
YAML est un langage populaire utilisé pour spécifier la configuration logicielle. Il offre une manière claire et intelligible de représenter des informations structurées. Voici quelques informations de base à connaître sur YAML avant de créer votre première automatisation à l'aide de scripts. 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 le signe deux-points, suivi d'un espace. Ces 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 basique qu'une chaîne, un nombre ou une date, ou aussi complexe qu'une autre collection de paires clé/valeur.
Strings
Si une valeur de chaîne commence par l'un des caractères suivants: [, {, ", ' ou #, ou si la chaîne contient : (deux-points suivis 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 d'ouverture.
Citation correcte:
name: 'TV on lights off'
name: "TV on lights off"
Citations incorrectes (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 valeurs 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 désigner la structure. Dans l'exemple précédent, name et description sont mis en retrait (de deux espaces) pour indiquer qu'il s'agit des enfants de la clé metadata.
La mise en retrait est stricte en YAML. Une structure enfant doit avoir un retrait plus profond que son parent, et les paires clé-valeur de même niveau doivent avoir le même retrait.
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 répertoriée sur une nouvelle ligne, et chaque ligne commence suivie d'un tiret et d'un espace. L'exemple suivant comporte deux listes:
- Une automatisation peut avoir plusieurs
starters. Par conséquent, le premier déclencheur commence par un tiret et un espace. weekdaypeut avoir plusieurs valeurs. Par conséquent, chaque valeur est davantage 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 le # 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 du script d'automatisations est appelée schéma.
Le schéma d'automatisations définit deux structures de données:
- Une paire clé-valeur unique est appelée Champ.
- Un ensemble de champs définis par le schéma est appelé Struct.
Struct
Le langage de script d'automatisation définit plusieurs "blocs" ou structures de données standards, appelés structs.
Examinez le struct automation, qui définit quatre champs:
| Clé | Type | Description |
|---|---|---|
|
|
Facultatif. Nom de l'automatisation. Les utilisateurs ne peuvent pas le voir, cette information est uniquement destinée aux développeurs. |
|
|
|
Obligatoire. Liste de déclencheurs. |
|
|
|
Facultatif. Condition. |
|
|
|
[Action] |
Obligatoire. Une liste d'actions |
La section Référence fournit les définitions de schéma pour tous les objets struct disponibles.
Les noms de clé sont uniques au sein d'un objet Struct donné et sont sensibles à la casse.
Les types de valeurs possibles sont les suivants:
- Un type primitif: valeur booléenne, nombre, chaîne, heure, etc.
- Type Struct: une collection de champs.
- Tableau du type de données. Un tableau est désigné par
[]. Par exemple,[string]est un tableau de chaînes, et[Starter]est un tableau de structs Starter. - Autres types spéciaux: Entity, FieldPath.
La description de chaque Champ contient des informations importantes, y compris:
- Obligatoire ou facultatif, indiquant si le champ est obligatoire ou s'il peut être ignoré.
- Dépendance de champ. Seuls les champs facultatifs comportent des dépendances. Cela décrit les vérifications supplémentaires liées à l'utilisation de 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 ni le champ C.
- Valeurs possibles. Par exemple, l'ensemble de valeurs limité d'un champ d'énumération de type chaîne ou une plage de nombres pouvant être utilisé dans un champ de type numérique.
Struct typé
Certains objets STRUCT peuvent représenter des déclencheurs basés sur une programmation temporelle ou un changement d'état d'un appareil. Chaque type d'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 un struct typé, qui est étendu par d'autres structs enfants dans le champ type, tels que time.schedule ou device.state.OnOff, pour fournir différentes fonctions. Les objets struct condition et action sont également des objets typés.
Les champs supplémentaires du struct doivent respecter la spécification du struct enfant (type). Par exemple, lorsque vous utilisez device.state.OnOff comme type, seuls les champssont spécifiés pour ce type
sont valides dans ce 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 contient 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, tels que [[1, 2], [3, 4]], ne sont pas compatibles avec les scripts d'automatisation. L'analyseur de langage aplatit automatiquement un tableau multidimensionnel en un tableau à une seule dimension, dans ce cas, [1, 2, 3, 4].
# INVALID: multi-dimensional array
- - 1
- 2
- - 3
- 4
Primitif
Les types de données primitifs suivants sont compatibles avec le schéma de script d'automatisations:
|
Valeur booléenne |
|
|
Nombre |
Nombre entier ou décimal |
|
Chaîne |
Texte brut Il n'est pas nécessaire de placer les chaînes entre guillemets, sauf dans des cas spécifiques. |
|
Date |
Jour et mois. Format : MM-JJ ou MM/JJ.
|
|
Temps |
Heure de la journée Il peut s'agir de l'heure de l'horloge ou du soleil.
Pour l'heure, il peut être au format AM/PM ou 24 h. Les secondes sont facultatives.
Pour l'heure du soleil,
|
|
DateTime |
Année, mois, jour et heure. Un espace blanc est requis entre les parties "Date" et "Heure". Le format de date est AAAA-MM-JJ ou AAAA/MM/JJ. Le format de l'heure est identique au format [Heure](#time). Le fuseau horaire n'est pas accepté.
|
|
Jour de la semaine |
|
|
Durée |
Une période de temps.
|
| ColorHex |
Code hexadécimal à six chiffres qui représente une couleur. Il n'y a pas de caractère
|
| Température | Données de température normale. Ajoutez toujours
|
| ColorTemperature |
Température de couleur en Kelvin.
|
Couleur
Les couleurs peuvent être spécifiées de trois manières : à l'aide des types primitifs ColorHex ou ColorTemperature, ou du type composé SpectrumHSV.
SpectrumHSV
Le type SpectrumHSV spécifie une couleur à l'aide de trois champs numériques:
- 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 (appareil ou salle, par exemple).
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 une donnée dans une charge utile de données. Dans l'exemple suivant, currentVolume est le chemin d'accès FieldPath pour le 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 FieldPath peuvent nécessiter plusieurs niveaux pour accéder à l'élément requis, et le format diffère entre "starter" et "action".
Les déclencheurs utilisent une notation par points, le tracé complet étant dans le même champ. Cette opération est principalement effectuée à des fins de comparaison dans la logique de démarrage. Par exemple, pour utiliser la température des couleurs 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
En revanche, les actions utilisent des champs imbriqués. Pour changer la couleur d'une ampoule en 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