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:
- Automatyzacja może mieć wiele elementów
starters
, dlatego pierwszy początek zaczyna się od łącznika i spacji. 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 |
---|---|---|
|
Opcjonalnie. Nazwa automatyzacji. Ta informacja nie jest widoczna dla użytkowników, tylko dla programistów. |
|
|
[Starter] |
Wymagane. Lista poleceń inicjujących. |
|
Opcjonalnie. Warunek. |
|
|
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 |
|
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.
|
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
|
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.
|
Dni powszednie |
|
Czas działania |
Okres.
|
ColorHex |
Sześciocyfrowy kod szesnastkowy reprezentujący kolor. Brak początkowego elementu
|
Temperatura | Normalna temperatura. Zawsze dodawaj do wartości
|
ColorTemperature |
Temperatura kolorów w kelwinach.
|
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