Podstawowe informacje o języku

Informacje o 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łowego formatu 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 cudzysłowy (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 name i description zostały wcięte (dwiema spacjami), aby wskazać, że są to elementy podrzędne 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 przykładzie poniżej znajdują się 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ę automation strukturze, 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ć elementy startowe 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 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 są prawidłowe 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 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 o dynamicznym typie 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 jest najczęściej używanym elementem automatyzacji. Format ciągu 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 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 FieldPaths mogą wymagać wielu poziomów, aby dotrzeć do wymaganego elementu, a format różni się w zależności od tego, czy jest to pole początkowe, czy działanie.

W przypadku początkujących używana jest notacja kropkowa, a cała ścieżka znajduje się w tym samym polu. Robi się to głównie w celach porównawczych w logice startowej. Jeśli na przykład chcesz użyć temperatury barwowej jako wartości początkowej, użyj color.colorTemperature w przypadku stanu:

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

Natomiast akcje korzystają z pól zagnieżdżonych. Aby zmienić kolor żarówki na niebieski, zamiast color.name i is: blue, należy wykonać następujące czynności:

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