Podstawowe informacje o języku

Poznaj YAML

YAML to popularny język używany do określania konfiguracji oprogramowania. Umożliwia on jasne i zrozumiałe dla człowieka przedstawianie informacji strukturalnych. Zanim utworzysz pierwszą automatyzację skryptową, musisz poznać kilka podstawowych informacji o YAML. Więcej informacji o YAML znajdziesz w specyfikacji w wersji 1.1.

Pary klucz–wartość

Dokumenty YAML to w zasadzie zbiór par klucz-wartość. W tym przykładzie kluczem jest name, a wartością – TV on lights off. Klucz i wartość są rozdzielone dwukropkiem i spacją. Oba znaki są wymagane w przypadku prawidłowo sformatowanego pliku YAML.

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 znaków zaczyna się od jednego z tych znaków: [, {, ", ' lub #, albo jeśli ciąg zawiera : (dwukropek, po którym następują spacje), musi być ujęty w cudzysłów.

Akceptowane są zarówno pojedyncze, jak i podwójne cudzysłowy, 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 użycie cudzysłowu (niepasujące 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ą 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ścią klucza metadata jest 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 elementy name i description są wcięte (o 2 spacje), aby wskazać, że są elementami podrzędnymi klucza metadata.

Wcięcia w YAML są ściśle określone. Struktura podrzędna musi mieć większe 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 tym przykładzie są 2 listy:

1. Automatyzacja może mieć wiele 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 ignorowany przez silnik automatyzacji.

Wiersz rozpoczynający się od znaku # 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 nazywa się strukturą.

Struct

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

Przyjrzyj się automationstrukturze, która definiuje 4 pola:

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

Nazwy kluczy są unikalne w ramach danej struktury i rozróżniana jest w nich wielkość liter.

Możliwe typy wartości:

• Typ prosty: bool, number, string, time itp.
• Typ struktury: zbiór pól.
• Tablica typu danych. Tablica jest oznaczona symbolem []. Na przykład [string] to tablica ciągów tekstowych, a [Starter] to tablica struktur początkowych.
• Inne typy specjalne: Entity, FieldPath.

Opis każdego pola zawiera ważne informacje, w tym:

• Wymagane lub opcjonalne – wskazuje, czy pole jest obowiązkowe, czy można je pominąć.
• Zależność pola. Zależności mają tylko pola opcjonalne. Opisuje dodatkowe sprawdzenia podczas korzystania z tego pola, np. Używaj pola B tylko wtedy, gdy pole A jest ustawione lub Gdy używane jest pole A, nie ustawiaj pola B ani pola C.
• Możliwe wartości. Może to być np. ograniczony zbiór wartości pola wyliczeniowego typu ciąg znaków lub zakres liczb, które mogą być używane w polu typu liczba.

Dane uporządkowane z typem

Niektóre struktury mogą reprezentować startery oparte na harmonogramie czasowym lub zmianie 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 struktura z określonym typem, która jest rozszerzana przez inne struktury podrzędne w polu type, takie jak time.schedule lub device.state.OnOff, aby zapewnić różne funkcje. Struktury condition i action też są typowane.

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

Tablica

W YAML tablica wartości zaczyna się od znaku - (myślnik i spacja). Tablica może zawierać wiele wartości Struct lub wiele wartości 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

Primitive

Schemat skryptu automatyzacji obsługuje te podstawowe typy danych:

Kolor

Kolory można określić na 3 sposoby: za pomocą typów pierwotnych 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 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 prostych na podstawie wartości z innych pól.

Przykładem pola dynamicznego typu danych 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 służący do unikalnego identyfikowania należącego do użytkownika obiektu, takiego 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 przykładzie poniżej 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ę w zależności od tego, czy jest to ścieżka początkowa czy ścieżka działania.

W przypadku elementów początkowych stosuje się notację z kropką, a cała ścieżka znajduje się w tym samym polu. Jest to robione głównie na potrzeby porównań w logice polecenia inicjującego. Jeśli na przykład chcesz użyć temperatury barwowej jako punktu wyjścia, w przypadku stanu użyj color.colorTemperature:

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

Działania korzystają jednak z 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