Conceptos básicos de idiomas

Comprende YAML

YAML es un lenguaje popular que se usa para especificar la configuración del software. Proporciona una forma clara y legible de representar información estructurada. Estos son algunos conceptos básicos que debes comprender sobre YAML antes de crear tu primera automatización con 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 que el formato YAML sea correcto.

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 otra colección de pares clave-valor.

Strings

Si un valor de cadena comienza con uno de los siguientes caracteres: [, {, ", ' o #, o si la cadena contiene : (un signo de dos puntos seguido de espacios), debe incluirse entre comillas.

Se aceptan comillas simples y dobles, pero la comilla de cierre debe coincidir con la de apertura.

Citas correctas:

name: 'TV on lights off'

name: "TV on lights off"

Citas incorrectas (citas que no coinciden):

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 indicar la estructura. En el ejemplo anterior, name y description tienen una sangría (de dos espacios) para indicar que son 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 principal, 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 muestra en una línea nueva y cada línea comienza con un guion y un espacio. En el siguiente ejemplo, hay dos listas:

1. Una automatización puede tener varios starters, por lo que el primer activador comienza con un guion y un espacio.
2. weekday puede 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

Todo el 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 del guion, pero el # 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 Automatizaciones se denomina esquema.

El esquema de 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 secuencias de comandos de automatización define varios "bloques" o estructuras de datos estándar, denominados Structs.

Echa un vistazo a la estructura automation, que define cuatro campos:

La sección Referencia proporciona definiciones de esquema para todos los Structs disponibles.

Los nombres de las claves son únicos dentro de un Struct determinado y distinguen mayúsculas de minúsculas.

Los tipos de valores posibles son los siguientes:

• Un tipo primitivo: bool, número, cadena, hora, etcétera.
• Un tipo Struct: Es una colección de campos.
• Es 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 structs de inicio.
• Otros tipos especiales: Entity y FieldPath.

La descripción de cada campo contiene información importante, como la siguiente:

• Obligatorio o opcional, indica si el campo es obligatorio o si se puede omitir.
• Es la dependencia del campo. Solo los campos opcionales tienen dependencias. En este campo, se describen las verificaciones adicionales que se realizan cuando se usa este campo, como Usa el campo B solo si se configuró el campo A o Cuando se usa el campo A, no configures el campo B ni el campo C.
• Valores posibles. Por ejemplo, el conjunto de valores limitado de un campo Enum de tipo string o un rango de números que se pueden usar en un campo de tipo número.

Struct con escritura

Algunos objetos Struct pueden representar activadores basados en un programa horario 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 con escritura, 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 con escritura.

Los campos adicionales de Struct deben seguir la especificación de Struct secundario (type). Por ejemplo, cuando se usa device.state.OnOff como type, solo son válidos los camposespecificados para ese tipo en ese Struct starter.

Array

En YAML, un array de valores comienza con - (un guion seguido de un espacio). El array puede contener varios valores Struct o varios valores primitivos. 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 se admiten en las secuencias de comandos de automatización. El analizador de lenguaje aplanará automáticamente un array multidimensional en un array unidimensional, en este caso, [1, 2, 3, 4].

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

Básico

El esquema de secuencias de comandos de Automations admite los siguientes tipos de datos primitivos:

Color

Los colores se pueden especificar de tres maneras: con los tipos primitivos ColorHex o ColorTemperature, o con el tipo compuesto SpectrumHSV.

SpectrumHSV

El tipo SpectrumHSV especifica un color con tres campos numéricos:

• Tono corresponde a la longitud de onda del color.
• Saturación indica la intensidad del color.
• El valor indica la claridad u 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 propiedad del usuario, como un dispositivo o una habitación.

El dispositivo 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 fragmento de datos en una carga útil de datos. En el siguiente ejemplo, currentVolume es el FieldPath para el campo state.

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

Otros FieldPaths pueden requerir varios niveles para llegar al elemento requerido, y el formato difiere entre el inicio y la acción.

Los iniciadores usan una notación de puntos, con toda la ruta de acceso en el mismo campo. Esto se hace principalmente con fines de comparación en la lógica inicial. Por ejemplo, para usar la temperatura de color como punto de partida, 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