Основы языка

Понимание 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 .

Структура

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

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

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

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

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

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

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

• Обязательное или необязательное, указывающее, является ли поле обязательным или его можно пропустить.
• Полевая зависимость. Зависимости имеют только необязательные поля. Здесь описаны дополнительные проверки при использовании этого поля, например «Использовать поле B, только если установлено поле A» , или «При использовании поля A не задавать поле B или поле C» .
• Возможные значения. Например, ограниченный набор значений поля перечисления строкового типа или диапазон чисел, который можно использовать в поле числового типа.

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

Некоторые структуры могут представлять собой стартеры на основе расписания или изменения состояния устройства. Каждый тип 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 ). Например, при использовании 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 .

СпектрHSV

Тип 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

ФилдПат

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