Основы языка

Понять 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.

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

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

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

• Отдельная пара ключ-значение называется Полем .
• Коллекция полей, определяемых схемой, называется Struct .

Структура

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

Взгляните на структуру automation , которая определяет четыре поля:

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

Имена ключей уникальны в пределах данной структуры и чувствительны к регистру.

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

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

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

• Обязательное или необязательное, указывает, является ли поле обязательным или его можно пропустить.
• Зависимость полей. Зависимости есть только у необязательных полей. Здесь описываются дополнительные проверки при использовании этого поля, например , «Использовать поле B только если задано поле A» или «При использовании поля A не задавать поле B или поле C» .
• Возможные значения. Например, ограниченный набор значений поля 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 Field, такими как time.schedule или device.state.OnOff , для предоставления различных функций. Структуры condition и action также типизированы.

Дополнительные поля в структуре должны соответствовать спецификации дочерней структуры ( 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

Примитивный

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

Цвет

Цвета можно указать одним из трех способов — с помощью примитивных типов 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