Comprende YAML
YAML es un lenguaje popular que se usa para especificar la configuración de software. Proporciona una forma clara y legible por humanos de representar información estructurada. A continuación, se incluyen algunos aspectos básicos que debes comprender sobre YAML antes de crear tu primera automatización de secuencias de comandos. Para obtener más información sobre YAML en general, consulta la especificación de la versión 1.1.
Pares clave-valor
Los documentos YAML son básicamente una colección de pares clave-valor. En el siguiente ejemplo, la clave es name y el valor es TV on lights off. La clave y el valor están delimitados por dos puntos seguidos de un espacio. Ambos caracteres son obligatorios para un archivo YAML bien formado.
name: TV on lights off
Valores
El valor asociado con una clave puede ser tan básico como una cadena, un número o una fecha, o tan complejo como otro conjunto de pares clave-valor.
Strings
Si un valor de cadena comienza con uno de los siguientes caracteres: [, {, ", ' o #, o si la cadena contiene : (dos puntos seguidos de espacios), debe escribirse entre comillas.
Se aceptan comillas simples y dobles, pero las comillas de cierre deben coincidir con las de apertura.
Comillas correctas:
name: 'TV on lights off'
name: "TV on lights off"
Comillas incorrectas (comillas no coincidentes):
name: 'TV on lights off"
Las comillas son opcionales para todos los demás tipos de cadenas.
Si necesitas una cadena de varias líneas, consulta la sección de la especificación de YAML sobre escalares de varias líneas.
name: "[1] TV"
name: '{1} TV'
name: '#TV'
name: '"1" TV'
name: "'1' TV"
name: "\"1\" TV"
name: "TV: bedroom"
Pares clave-valor anidados
Aquí, el valor de la clave metadata es una lista de dos pares clave-valor (name y description):
metadata:
name: TV on lights off
description: Turn off lights when TV turns on
Sangría
YAML usa sangría para denotar la estructura. En el ejemplo anterior, name y description tienen sangría (dos espacios) para indicar que son los elementos secundarios de la clave metadata.
La sangría es estricta en YAML. Una estructura secundaria debe tener una sangría más profunda que su elemento superior, y los pares clave-valor del mismo nivel deben tener la misma sangría.
metadata:
name:
en: TV on lights off
description:
en: Turn off lights when TV turns on
Varios valores
Si una clave determinada tiene varios valores, cada valor se indica en una línea nueva y cada línea comienza seguida de un guion y un espacio. En el siguiente ejemplo, hay dos listas:
- Una automatización puede tener varios
startersy, por lo tanto, el primer activador comienza con un guion y un espacio. weekdaypuede tener varios valores y, por lo tanto, cada valor tiene una sangría adicional y comienza con un guion y un espacio.
starters:
- type: time.schedule
at: SUNSET
weekday:
- MONDAY
- THURSDAY
state: on
Comentarios
Cualquier texto que siga a un # se considera un comentario y el motor de automatización lo ignora.
Una línea que comienza con # es un comentario.
Un comentario puede aparecer en la misma línea que el contenido de la secuencia de comandos, pero # debe estar precedido por un espacio.
# This is a comment. It will be ignored.
name: chromecast #This is a TV.
Secuencia de comandos de automatización
La especificación de la sintaxis de la secuencia de comandos de Automations se denomina esquema.
El esquema Automations define un par de estructuras de datos:
- Un solo par clave-valor se denomina campo.
- Una colección de campos definidos por el esquema se denomina struct.
Struct
El lenguaje de programación de automatización define varios "bloques" o estructuras de datos estándar, denominados Structs.
Observa la estructura automation, que define cuatro campos:
| Clave | Tipo | Descripción |
|---|---|---|
|
|
Opcional. Es el nombre de la automatización. Los usuarios no pueden verlo; es solo para referencia de los desarrolladores. |
|
|
|
[Starter] |
Obligatorio. Una lista de activadores. |
|
|
Opcional. Condición. |
|
|
|
[Action] |
Obligatorio. Una lista de acciones. |
La sección Referencia proporciona definiciones de esquemas para todas las estructuras disponibles.
Los nombres de clave son únicos dentro de una Struct determinada y distinguen mayúsculas de minúsculas.
Los tipos de valor posibles son los siguientes:
- Un tipo primitivo: bool, número, cadena, hora, etcétera.
- Un tipo de struct: una colección de campos.
- Un array del tipo de datos. El array se indica con
[]. Por ejemplo,[string]es un array de cadenas y[Starter]es un array de estructuras de partida. - Otros tipos especiales: Entidad, FieldPath.
La descripción de cada campo contiene información importante, como la siguiente:
- Obligatorio o opcional, que indica si el campo es obligatorio o si se puede omitir.
- Dependencia de campo Solo los campos opcionales tienen dependencias. Aquí se describen las verificaciones adicionales cuando se usa este campo, como Usar el campo B solo si se configura el campo A o Cuando se usa el campo A, no configurar el campo B ni el campo C.
- Valores posibles. Por ejemplo, el conjunto de valores limitado de un campo Enum de tipo de cadena o un rango de números que se pueden usar en un campo de tipo de número.
Struct escrito
Algunos Structs pueden representar activadores en función de un programa de tiempo o un cambio de estado del dispositivo. Cada tipo de starter debe proporcionar un conjunto distinto de campos.
# 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 es una estructura tipada, que se extiende con otras estructuras secundarias en el campo type, como time.schedule o device.state.OnOff, para proporcionar diferentes funciones. Los structs condition y action también son de tipo.
Los campos adicionales de la Struct deben seguir la especificación de la Struct secundaria (type). Por ejemplo, cuando se usa device.state.OnOff como type, solo los
camposcampos especificados para ese
tipo
son válidos en
esa estructura starter.
Array
En YAML, un array de valores comienza con - (un guion seguido de un espacio). El array puede contener varios valores de Struct o varios valores de Primitive. Sin embargo, los valores del array deben ser del mismo tipo.
Cuando el array contiene un solo elemento, puedes omitir el guion y el espacio:
# 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
Los arreglos multidimensionales, como [[1, 2], [3, 4]], no son compatibles con la escritura de secuencias de comandos de automatización. El analizador de lenguaje aplanará automáticamente un array multidimensional en un array de una sola dimensión, en este caso, [1, 2, 3, 4].
# INVALID: multi-dimensional array
- - 1
- 2
- - 3
- 4
Básico
El esquema de la secuencia de comandos de Automations admite los siguientes tipos de datos primitivos:
|
Bool |
|
|
Número |
Número entero o decimal |
|
String |
Texto sin formato No es necesario que las cadenas estén entre comillas, excepto en casos específicos. |
|
Fecha |
Mes y día. El formato es MM-DD o MM/DD.
|
|
Hora |
Hora del día. Puede ser la hora del reloj o la hora solar.
Para la hora del reloj, se puede usar el formato a.m./p.m. o de 24 h. Los segundos son opcionales.
Para la hora solar,
|
|
Fecha y hora |
Año, mes, día y hora del día. Se requiere un espacio en blanco entre la parte de la fecha y la parte de la hora. El formato de la fecha es AAAA-MM-DD o AAAA/MM/DD. El formato de la hora es el mismo que el de [Time](#time). No se admite la zona horaria.
|
|
Día de semana |
|
|
Duración |
Un período.
|
| ColorHex |
Es un código hexadecimal de seis dígitos que representa un color. No hay
|
| Temperatura | Datos de temperatura normal. Agrega siempre
|
| ColorTemperature |
Temperatura de color en Kelvin.
|
Color
Los colores se pueden especificar de una de las siguientes tres maneras: con los tipos primitivos ColorHex o ColorTemperature, o el tipo compuesto SpectrumHSV.
SpectrumHSV
El tipo SpectrumHSV especifica un color con tres campos numéricos:
- El matiz corresponde a la longitud de onda del color.
- Saturación indica la intensidad del color.
- El valor indica la claridad o oscuridad relativa del color.
Dinámico
A veces, el tipo de datos de una clave no es fijo. Puede ser uno de los tipos primitivos, según los valores de otros campos.
Un ejemplo de campo de tipo de datos dinámico es is. El tipo real se determina según los valores de los campos type y 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
Entidad
Es un formato de cadena especial para identificar de forma única una entidad que pertenece al usuario, como un dispositivo o una habitación.
Device es la entidad más común que se usa en las automatizaciones. El formato de cadena de la entidad es 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
Es un formato de cadena especial que se usa para ubicar un dato en una carga útil de datos. En el siguiente ejemplo, currentVolume es el FieldPath del campo state.
# The state field accepts a FieldPath type.
starters:
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 5
Es posible que otros FieldPaths requieran varios niveles para llegar al elemento requerido, y el formato difiere entre el activador y la acción.
Los activadores usan una notación de punto, con toda la ruta de acceso en el mismo campo. Esto se hace principalmente con fines de comparación en la lógica del activador. Por ejemplo, para usar la temperatura de color como activador, usarías color.colorTemperature para el estado:
starters:
- type: device.state.ColorSetting
device: My Device - Room Name
state: color.colorTemperature
is: 2000K
Sin embargo, las acciones usan campos anidados. Para cambiar el color de una bombilla a azul, en lugar de color.name y is: blue, debes hacer lo siguiente:
actions:
- type: device.command.ColorAbsolute
devices: My Device - Room Name
color:
name: blue