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 por humanos de representar información estructurada. A continuación, se indican algunos aspectos básicos que debes comprender sobre YAML antes de crear tu primera automatización de secuencia 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 se delimitan con dos puntos seguidos de un espacio. Ambos caracteres son obligatorios para que el archivo YAML tenga el formato 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 : (dos puntos seguidos de espacios), debe estar entre comillas.

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

Uso correcto de comillas:

name: 'TV on lights off'

name: "TV on lights off"

Uso incorrecto de comillas (comillas 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 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 la sangría para denotar 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 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 uno 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 y, por lo tanto, 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

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 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 automatizaciones 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 automatizaciones define varios "bloques" o estructuras de datos estándar, que se denominan Structs.

Echa un vistazo al Struct automation, que define cuatro campos:

En la sección Referencia , se proporcionan definiciones de esquemas 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: 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 structs de inicio.
• Otros tipos especiales: Entity, FieldPath.

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

• Obligatorio frente a opcional, que indica si el campo es obligatorio o si se puede omitir.
• Dependencia de campos Solo los campos opcionales tienen dependencias. En esta sección, se describen las verificaciones adicionales cuando se usa este campo, como Usa el campo B solo si el campo A está configurado 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 cadena o un rango de números que se puede usar en un campo de tipo número.

Struct con tipo

Algunos Structs pueden representar activadores basados en 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 un Struct con tipo, que se extiende por otros Structs secundarios en el campo type, como time.schedule o device.state.OnOff, para proporcionar diferentes funciones. Los Structs condition y action también tienen tipos.

Los campos adicionales en Struct deben seguir la especificación de Struct secundario (type). Por ejemplo, cuando usas device.state.OnOff como type, solo los campos especificados para ese tipo son válidos 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 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 arrays multidimensionales, como [[1, 2], [3, 4]], no se admiten en las secuencias de comandos de automatización. El analizador de lenguaje compactará 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 automatizaciones 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:

• El matiz corresponde a la longitud de onda del color.
• La 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 que pertenece al 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 la 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 la 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

Otras rutas de campo pueden requerir varios niveles para llegar al elemento requerido, y el formato difiere entre el activador y la acción.

Los principiantes 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 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