Основы языка

Что такое YAML

YAML – популярный язык, используемый для указания конфигурации программного обеспечения. Он обеспечивает понятный, удобочитаемый способ представления структурированной информации. Вот несколько основных вещей, которые вам нужно понять о YAML, прежде чем создавать свою первую автоматизацию на основе скриптов. Подробную информацию о YAML можно найти в спецификации версии 1.1.

Пары "ключ-значение"

Документы YAML представляют собой набор пар "ключ-значение". В примере ниже ключ – name, а значение – TV on lights off. Ключ и значение разделяются двоеточием и пробелом. Оба символа необходимы для корректного YAML.

name: TV on lights off

Значения

Значение, связанное с ключом, может быть простым, например строкой, числом или датой, или сложным, например другой коллекцией пар "ключ-значение".

Струны

Если строковое значение начинается с одного из следующих символов: [, {, ", ' или #, или строка содержит : (двоеточие, за которым следуют пробелы), оно должно быть заключено в кавычки.

Допускаются как одинарные, так и двойные кавычки, но закрывающая кавычка должна соответствовать открывающей.

Правильное цитирование

name: 'TV on lights off'

name: "TV on lights off"

Неправильное использование кавычек (несоответствие кавычек):

name: 'TV on lights off"

Для всех остальных типов строк кавычки необязательны.

Если вам нужна многострочная строка, ознакомьтесь с разделом спецификации YAML, посвященным многострочным скалярам.

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

Вложенные пары "ключ-значение"

В этом примере значение ключа metadata – это список из двух пар "ключ-значение" (name и description):

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

Отступ

В YAML для обозначения структуры используются отступы. В предыдущем примере name и description имеют отступ (два пробела), чтобы обозначить, что они являются дочерними элементами ключа metadata.

В YAML отступы строго регламентированы. Дочерняя структура должна иметь более глубокий отступ, чем родительская, а пары "ключ-значение" одного уровня должны иметь одинаковый отступ.

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

Несколько значений

Если у ключа несколько значений, каждое из них указывается в новой строке, которая начинается с дефиса и пробела. В примере ниже есть два списка:

1. У автоматизации может быть несколько условий starters, поэтому первое условие начинается с тире и пробела.
2. У weekday может быть несколько значений, поэтому каждое из них имеет дополнительный отступ и начинается с тире и пробела.

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

Комментарии

Любой текст после # считается комментарием и игнорируется механизмом автоматизации.

Строка, начинающаяся с символа #, является комментарием.

Комментарий может находиться в одной строке с кодом скрипта, но # должен быть отделен от него пробелом.

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

Скрипт автоматизации

Спецификация синтаксиса скриптов автоматизации называется схемой.

Схема автоматизации определяет пару структур данных:

• Отдельная пара "ключ-значение" называется полем.
• Набор полей, определенных схемой, называется структурой.

Структура

В скриптовом языке автоматизации определено несколько стандартных блоков, или структур данных, которые называются структурами.

Рассмотрим структуру automation, которая определяет четыре поля:

В разделе Справочник приведены определения схем для всех доступных структур.

Названия ключей уникальны в пределах структуры и чувствительны к регистру.

Возможные типы значений:

• Примитивный тип: bool, number, string, time и т. д.
• Тип Struct: набор полей.
• Массив типа данных. Массив обозначается символом []. Например, [string] – это массив строк, а [Starter] – массив структур Starter.
• Другие специальные типы: Entity, FieldPath.

В описании каждого поля содержится важная информация, в том числе:

• Обязательное или необязательное поле.
• Зависимость полей. Зависимости есть только у необязательных полей. Здесь описываются дополнительные проверки при использовании этого поля, например Использовать поле Б, только если задано поле А или Если используется поле А, не задавать поле Б или поле В.
• Возможные значения. Например, ограниченный набор значений поля Enum типа string или диапазон чисел, которые можно использовать в поле типа number.

Типизированная структура

Некоторые структуры могут представлять собой стартеры, основанные на расписании или изменении состояния устройства. Для каждого типа starter должен быть указан отдельный набор полей.

# 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

starter – это типизированная структура, которая расширяется другими дочерними структурами в поле type, например time.schedule или device.state.OnOff, для обеспечения различных функций. Структуры condition и action также типизированы.

Дополнительные поля в Struct должны соответствовать спецификации дочернего Struct (type). Например, если в качестве type используется device.state.OnOff, то в структуре starter будут действительны только поля, указанные для этого типа: .

Массив

В YAML массив значений начинается с - (тире и пробел). Массив может содержать несколько значений Struct или Primitive. но значения в массиве должны быть одного типа.

Если массив содержит один элемент, дефис и пробел можно опустить:

# 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

Многомерные массивы, такие как [[1, 2], [3, 4]], не поддерживаются в скриптах автоматизации. Синтаксический анализатор языка автоматически преобразует многомерный массив в одномерный, в данном случае – [1, 2, 3, 4].

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

Примитивный

Схема скриптов автоматизации поддерживает следующие примитивные типы данных:

Цвет

Цвета можно указать одним из трех способов: с помощью простых типов ColorHex или ColorTemperature или составного типа SpectrumHSV.

SpectrumHSV

Тип SpectrumHSV задает цвет с помощью трех числовых полей:

• Оттенок соответствует длине волны цвета.
• Насыщенность указывает на интенсивность цвета.
• Значение указывает на относительную яркость или темноту цвета.

Динамическая

Иногда тип данных ключа не фиксирован. Это может быть один из примитивных типов, основанный на значениях из других полей.

Пример поля с динамическим типом данных – is. Фактический тип определяется значениями полей type и 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

Объект

Специальный строковый формат для уникальной идентификации принадлежащего пользователю объекта, например устройства или комнаты.

Устройство – это самый распространенный объект, используемый в автоматизациях. Формат строки объекта: 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

Специальный строковый формат, используемый для поиска фрагмента данных в полезной нагрузке. В примере ниже currentVolume – это FieldPath для поля state.

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

Для других FieldPath может потребоваться несколько уровней, чтобы добраться до нужного элемента, а формат различается между условием и действием.

В стартерах используется точечная нотация, при которой весь путь указывается в одном поле. Это делается в основном для сравнения в логике начальных условий. Например, чтобы использовать в качестве условия цветовую температуру, укажите для состояния значение color.colorTemperature:

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

Однако в действиях используются вложенные поля. Чтобы изменить цвет лампочки на синий, вместо color.name и is: blue нужно сделать следующее:

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