Podstawowe informacje o języku

Informacje o YAML

Popularnym językiem używanym do określania konfiguracji oprogramowania jest YAML. Pozwala w jasny i zrozumiały dla człowieka sposób przedstawienia uporządkowanych informacji. Oto kilka podstawowych rzeczy, które musisz wiedzieć o YAML przed utworzeniem pierwszej zautomatyzowanej automatyzacji. Więcej informacji o YAML znajdziesz w specyfikacji wersji 1.1.

Pary klucz-wartość

Dokumenty YAML to w zasadzie zbiory par klucz-wartość. W tym przykładzie klucz to name, a wartość to TV on lights off. Klucz i wartość są rozdzielone dwukropkiem, po którym następuje spacja. Prawidłowo sformatowany plik YAML wymaga obu znaków.

name: TV on lights off

Wartości

Wartość powiązana z kluczem może być tak podstawowa jak ciąg, liczba lub data albo być tak złożona jak inny zbiór par klucz-wartość.

Ciąg znaków

Jeśli wartość ciągu zaczyna się od jednego z tych znaków: [, {, ", ' lub # albo zawiera ciąg : (dwukropek, po którym następuje spacja), musi zostać ujęta w cudzysłów.

Akceptowane są zarówno cudzysłowy pojedyncze, jak i podwójne, jednak zamykający musi być taki sam jak cytat otwierający.

Prawidłowy cytat:

name: 'TV on lights off'

name: "TV on lights off"

Nieprawidłowy cytat (niedopasowane cudzysłowy):

name: 'TV on lights off"

Cudzysłowy są opcjonalne w przypadku wszystkich innych typów ciągów tekstowych.

Jeśli potrzebujesz ciągu wielowierszowego, zapoznaj się z sekcją specyfikacji YAML dotyczącej skalarów wielowierszowych.

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

Zagnieżdżone pary klucz-wartość

Wartość klucza metadata ma postać listy 2 par klucz-wartość (name i description):

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

Wcięcie

YAML używa wcięcia do oznaczenia struktury. W poprzednim przykładzie wartości name i description są wcięte (przez 2 spacje), aby wskazać, że są to elementy podrzędne klucza metadata.

Wcięcie w YAML jest rygorystyczne. Struktura podrzędna musi mieć głębsze wcięcie niż element nadrzędny, a pary klucz-wartość tego samego poziomu muszą mieć takie samo wcięcie.

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

Wiele wartości

Jeśli dany klucz ma wiele wartości, każda z nich jest wymieniona w nowym wierszu, a każda z nich zaczyna się od myślnika i spacji. W tym przykładzie są 2 listy:

  1. Automatyzacja może mieć wiele elementów starters, dlatego pierwszy początek zaczyna się od łącznika i spacji.
  2. weekday może mieć wiele wartości, dlatego każda z nich ma dodatkowe wcięcie i zaczyna się od łącznika i spacji.
starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

Komentarze

Każdy tekst występujący po # jest uznawany za komentarz i ignorowany przez mechanizm automatyzacji.

Wiersz zaczynający się od # to komentarz.

Komentarz może pojawić się w tym samym wierszu co treść skryptu, ale # musi być poprzedzony spacją.

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

Skrypt automatyzacji

Specyfikacja składni skryptu automatyzacji jest nazywana schematem.

Schemat automatyzacji definiuje 2 struktury danych:

  • Pojedyncza para klucz-wartość jest nazywana polem.
  • Zbiór pól zdefiniowanych przez schemat jest nazywany strukturą.

Uporządkowane

Język skryptów automatyzacji definiuje kilka standardowych „bloków” lub struktur danych nazywanych strukturami.

Spójrz na strukturę automation, która definiuje 4 pola:

Klucz Typ Opis

name

Ciąg

Opcjonalnie.

Nazwa automatyzacji.

Ta informacja nie jest widoczna dla użytkowników, tylko dla programistów.

starters

[Starter]

Wymagane.

Lista poleceń inicjujących.

condition

Stan

Opcjonalnie.

Warunek.

actions

[Działanie]

Wymagane.

Lista działań.

Sekcja Dokumentacja zawiera definicje schematów wszystkich dostępnych struktur.

Nazwy kluczy są unikalne w obrębie danego elementu Struct. Wielkość liter ma znaczenie.

Możliwe typy wartości:

  • Typ podstawowy: wartość logiczna, liczba, ciąg, czas itd.
  • Typ struktury: zbiór pól.
  • Tablica typu danych. Tablica jest oznaczona wartością []. Na przykład [string] jest tablicą ciągów tekstowych, a [Starter] to tablica obiektów Starter.
  • Inne typy szczególne: Entity, FieldPath.

Opis każdego Pola zawiera ważne informacje, m.in.:

  • Wymagane czy opcjonalne, wskazujące, czy pole jest obowiązkowe, czy można je pominąć.
  • Zależność pól. Tylko pola opcjonalne zawierają zależności. Opisuje to dodatkowe kontrole, które należy wykonać podczas korzystania z tego pola, np. Używaj pola B tylko wtedy, gdy pole A jest ustawione lub Gdy jest używane pole A, nie ustawiaj pola B ani C.
  • Możliwe wartości. Może to być na przykład ograniczony zestaw wartości w polu Enum ciągu znaków lub zakres liczb, których można użyć w polu typu Liczba.

Typowy stylizowany

Niektóre Structs mogą reprezentować polecenia inicjujące na podstawie harmonogramu czasu lub zmiany stanu urządzenia. Każdy typ starter musi zapewniać osobny zestaw Pól.

# 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

Element starter to typowy struktura, która jest rozszerzona przez inne struktury podrzędne w polu type, np. time.schedule lub device.state.OnOff, na potrzeby udostępniania innych funkcji. Struktury condition i action również są wpisane.

Dodatkowe pola w elemencie Struct muszą być zgodne ze specyfikacją podrzędną Struct (type). Jeśli na przykład jako type używasz device.state.OnOff, tylkopola określone dla tego typu są prawidłowe w tym elemencie starter struct.

Tablica

W YAML tablica wartości zaczyna się od - (myślnika, po którym następuje spacja). Tablica może zawierać wiele wartości Struct lub wiele wartości podstawowych. Wartości w tablicy muszą jednak być tego samego typu.

Jeśli tablica zawiera jeden element, możesz pominąć łącznik i spację:

# 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

Tablice wielowymiarowe, takie jak [[1, 2], [3, 4]], nie są obsługiwane w przypadku skryptów automatyzacji. Parser języka automatycznie spłaszczy wielowymiarową tablicę w tablicę jednowymiarową, w tym przypadku do [1, 2, 3, 4].

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

Podstawowe

Schemat skryptu automatyzacji obsługuje te typy podstawowych danych:

Wartość logiczna
  • true
  • false

Liczby

Liczba całkowita lub dziesiętna

Ciąg znaków

Zwykły tekst

Ciągi znaków nie muszą być cytowane, chyba że w konkretnych przypadkach.

Data

Miesiąc i dzień. Format to MM-DD lub MM/DD.

  • 09/01
  • 09-01

Godzina

Pora dnia. Może to być zegar lub czas słoneczny. Zegar może mieć format 24-godzinny lub 24-godzinny. Sekundy są opcjonalne. W przypadku czasu słonecznego sunrise i sunset to słowa kluczowe, po których może występować przesunięcie (w przypadku czasu trwania).

  • 12:30 am
  • 13:00:01
  • sunrise / sunset
  • sunset+30min / sunset-1hour

DateTime

Rok, miesiąc, dzień i pora dnia. Między polami daty i godziną wymagane są odstępy. Format daty to RRRR-MM-DD lub RRRR/MM/DD. Format godziny jest taki sam jak w polu [Godzina](#time). Strefa czasowa nie jest obsługiwana.

  • 2022/01/01 14:00
  • 2022-12-31 sunrise+30min

Dni powszednie

  • MONDAY (lub MON)
  • TUESDAY (lub TUE)
  • WEDNESDAY (lub WED)
  • THURSDAY (lub THU)
  • FRIDAY (lub FRI)
  • SATURDAY (lub SAT)
  • SUNDAY (lub SUN)

Czas działania

Okres.

  • 30min
  • 1hour
  • 20sec
  • 1hour10min20sec
ColorHex

Sześciocyfrowy kod szesnastkowy reprezentujący kolor.

Brak początkowego elementu #.

  • FFFFFF
  • B5D2A1
  • DFA100
Temperatura

Normalna temperatura. Zawsze dodawaj do wartości 'C' lub 'F', aby wskazywać pomiar temperatury.

  • 20.5C
  • 90F
ColorTemperature

Temperatura kolorów w kelwinach.

  • 5000K

Kolor

Kolory można określić na 3 sposoby: za pomocą typu podstawowego ColorHex lub ColorTemperature albo za pomocą typu złożonego SpectrumHSV.

SpectrumHSV

Typ SpectrumHSV określa kolor za pomocą 3 pól liczbowych:

  • Odcień odpowiada długości fali kolorów.
  • Nasycenie wskazuje intensywność koloru.
  • Wartość wskazuje względną jasność lub ciemność koloru.

Dynamiczna

Czasami typ danych klucza nie jest stały. Może to być jeden z typów podstawowych opartych na wartościach z innych pól.

Przykładem dynamicznego pola typu danych jest is. Rzeczywisty typ jest określany na podstawie wartości w polach type i 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

Element

Specjalny format ciągu znaków do jednoznacznego identyfikowania należących do użytkownika encji, takich jak urządzenie lub pomieszczenie.

Urządzenie jest najczęściej wykorzystywanym elementem w automatyzacji. Format ciągu znaków encji to 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

Specjalny format ciągu znaków używany do lokalizowania danych w ładunku danych. W tym przykładzie currentVolume to pole FieldPath dla pola state.

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

Inne ścieżki FieldPath mogą wymagać wielu poziomów, aby dotrzeć do wymaganego elementu, a format różni się w zależności od polecenia inicjującego i działania.

W przypadku poleceń inicjujących cała ścieżka znajduje się w tym samym polu. Służy to głównie do celów porównawczych w logice początkowej. Jeśli na przykład chcesz jako początek ustawić temperaturę kolorów, użyj wartości color.colorTemperature dla stanu:

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

Akcje korzystają jednak z pól zagnieżdżonych. Aby zmienić kolor żarówki na niebieski zamiast color.name i is: blue, musisz:

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