Основы языка

Разберитесь в 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.

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

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

Схема Automations определяет несколько структур данных:

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

Структура

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

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

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

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

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

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

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

• Обязательный или необязательный параметр, указывающий, является ли поле обязательным или его можно пропустить.
• Зависимость полей. Зависимости имеют только необязательные поля. Здесь описываются дополнительные проверки при использовании этого поля, например: «Использовать поле B только если поле A задано» или «При использовании поля A не задавать поля B или C» .
• Возможные значения. Например, ограниченный набор значений поля перечисления типа 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 ). Например, при использовании device.state.OnOff в качестве type , толькополя, указанные для этого типа действительны в этой 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

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

В стартовых элементах используется точечная нотация, при этом весь путь указывается в одном поле. Это делается в основном для целей сравнения в логике стартовых элементов. Например, чтобы использовать цветовую температуру в качестве стартового элемента, следует использовать 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