Podstawowe informacje o języku

Omówienie YAML

YAML to popularny język używany do określania konfiguracji oprogramowania. Zapewnia przejrzysty, zrozumiały dla człowieka sposób przedstawiania uporządkowanych informacji. Zanim utworzysz pierwszą automatyzację zapisaną w skrypcie, musisz poznać kilka podstawowych informacji o języku YAML. Więcej informacji o YAML znajdziesz w specyfikacji wersji 1.1.

Pary klucz–wartość

Dokumenty YAML to zasadniczo zbiór par klucz-wartość. W poniższym przykładzie klucz to name, a wartość to TV on lights off. Klucz i wartość są rozdzielone dwukropkiem, po którym następuje spacja. Oba znaki są wymagane, aby plik YAML był prawidłowo sformatowany.

name: TV on lights off

Wartości

Wartość powiązana z kluczem może być tak prosta jak ciąg znaków, liczba lub data albo tak złożona jak inna kolekcja par klucz-wartość.

Strings

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

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

Prawidłowe cytowanie:

name: 'TV on lights off'

name: "TV on lights off"

Nieprawidłowe cudzysłowy (niedopasowane cudzysłowy):

name: 'TV on lights off"

W przypadku wszystkich innych typów ciągów znaków cudzysłowy są opcjonalne.

Jeśli potrzebujesz ciągu wielowierszowego, zapoznaj się z sekcją specyfikacji YAML dotyczącą wielowierszowych wartości skalarnych.

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ść

W tym przypadku wartość klucza metadata to lista 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ęć do oznaczania struktury. W poprzednim przykładzie name i description są wcięte (o 2 spacje), aby wskazać, że są elementami podrzędnymi klucza metadata.

W YAML wcięcia są rygorystyczne. Struktura podrzędna musi mieć głębsze wcięcie niż struktura nadrzędna, a pary klucz-wartość na tym samym poziomie 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żdy wiersz zaczyna się od myślnika i spacji. W poniższym przykładzie są 2 listy:

1. Automatyzacja może mieć wiele elementów starters, dlatego pierwszy element uruchamiający zaczyna się od myślnika i spacji.
2. weekday może mieć wiele wartości, dlatego każda z nich jest dodatkowo wcięta i zaczyna się od myślnika i spacji.

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

Komentarze

Każdy tekst po znaku # jest traktowany jako komentarz i jest ignorowany przez mechanizm automatyzacji.

Wiersz zaczynający się od # jest komentarzem.

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 kilka struktur danych:

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

Struct

Język skryptowy automatyzacji definiuje kilka standardowych „bloków” lub struktur danych, które są nazywane strukturami.

Przyjrzyj się strukturze automation, która definiuje 4 pola:

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

Nazwy kluczy są unikalne w obrębie danej struktury i wielkość liter ma znaczenie.

Możliwe typy wartości:

• Typ podstawowy: bool, number, string, time itd.
• Typ Struct: kolekcja pól.
• Tablica typu danych. Tablica jest oznaczona symbolem []. Na przykład [string] to tablica ciągów tekstowych, a [Starter] to tablica struktur poleceń inicjujących.
• Inne typy specjalne: Entity, FieldPath.

Opis każdego pola zawiera ważne informacje, takie jak:

• Wymagane lub opcjonalne, co wskazuje, czy pole jest obowiązkowe, czy można je pominąć.
• Zależność pól. Zależności mają tylko pola opcjonalne. Opisuje dodatkowe kontrole podczas korzystania z tego pola, np. Używaj pola B tylko wtedy, gdy pole A jest ustawione lub Gdy pole A jest używane, nie ustawiaj pola B ani pola C.
• Możliwe wartości. Na przykład ograniczony zestaw wartości pola typu Enum, które jest ciągiem znaków, lub zakres liczb, które mogą być używane w polu typu Number.

Typed Struct

Niektóre struktury mogą reprezentować elementy inicjujące na podstawie harmonogramu lub zmiany stanu urządzenia. Każdy typ starter musi zawierać odrębny 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

starter to Typed Struct, który jest rozszerzany przez inne podrzędne struktury w polu type, takie jak time.schedule lub device.state.OnOff, aby zapewnić różne funkcje. Struktury condition i action również są typowane.

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

Tablica

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

Jeśli tablica zawiera tylko 1 element, możesz pominąć myślnik 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 skryptach automatyzacji. Parser języka automatycznie spłaszczy tablicę wielowymiarową do tablicy jednowymiarowej, w tym przypadku [1, 2, 3, 4].

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

Prymitywny

Schemat skryptu automatyzacji obsługuje te podstawowe typy danych:

Kolor

Kolory można określić na 1 z 3 sposobów – za pomocą typów podstawowych ColorHex lub ColorTemperature albo typu złożonego SpectrumHSV.

SpectrumHSV

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

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

Dynamiczne

Czasami typ danych klucza nie jest stały. Może to być jeden z typów podstawowych, w zależności od wartości z innych pól.

Przykładem pola typu danych dynamicznych jest is. Rzeczywisty typ jest określany przez wartości pól 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

Jednostka

Specjalny format ciągu znaków, który jednoznacznie identyfikuje element należący do użytkownika, taki jak urządzenie lub pomieszczenie.

Urządzenie to najczęściej używany element w automatyzacjach. Format ciągu znaków elementu 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 fragmentu danych w ładunku danych. W poniższym przykładzie currentVolume to FieldPath 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ę między warunkiem inicjującym a działaniem.

W przypadku elementów inicjujących używana jest notacja kropkowa, a cała ścieżka znajduje się w tym samym polu. Służy to głównie do porównywania w logice polecenia inicjującego. Jeśli na przykład chcesz użyć temperatury kolorów jako elementu inicjującego, użyj color.colorTemperature dla stanu:

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

Działania używają jednak pól zagnieżdżonych. Aby zmienić kolor żarówki na niebieski, zamiast color.name i is: blue musisz wykonać te czynności:

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