Interpretowanie pliku YAML
YAML to popularny język używany do określania konfiguracji oprogramowania. Zapewnia on przejrzysty i zrozumiały sposób przedstawiania informacji ustrukturyzowanych. Zanim utworzysz pierwszą automatyzację z wykorzystaniem skryptu, zapoznaj się z kilkoma podstawowymi informacjami o YAML. Więcej informacji o YAML znajdziesz w specyfikacji wersji 1.1.
Pary klucz-wartość
Dokumenty YAML to w podstawie zbiór par klucz-wartość. W tym przykładzie klucz to name, a wartość to TV on lights off. Klucz i wartość są rozdzielane dwukropkiem i spacją. Aby format YAML był poprawny, oba znaki są wymagane.
name: TV on lights off
Wartości
Wartość powiązana z kluczem może być tak podstawowa 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ę jednym z tych znaków: [, {, ", ' lub #, albo zawiera znak : (dwukropka z następującymi spacjami), musi być ujęta w cudne znaki.
Dopuszczalne są cudzysłowe proste i podwójne, ale cudzysłowie zamykające musi być zgodne z cudzysłowem otwierającym.
Prawidłowe cytowanie:
name: 'TV on lights off'
name: "TV on lights off"
Nieprawidłowe cudzysłowe (niepasujące cudzysłowy):
name: 'TV on lights off"
Cudzysłowe jest opcjonalne w przypadku wszystkich innych typów ciągów znaków.
Jeśli potrzebujesz ciągu wielowierszowego, zapoznaj się z sekcją specyfikacji YAML na temat 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ść
Tutaj 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,
Plik 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.
W formacie YAML wcięcia są rygorystyczne. Struktura podrzędna musi mieć większą 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 podana w nowym wierszu, a poprzedza ją myślnik i spacja. W tym przykładzie są 2 listy:
- Automatyzacja może mieć wiele elementów
starters, dlatego pierwszy element uruchamiający zaczyna się od myślnika i spacji. weekdaymoże mieć wiele wartości, dlatego każda z nich jest wcięciem 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 uważany za komentarz i ignorowany przez mechanizm automatyzacji.
Wiersz rozpoczynający się od # to komentarz.
Komentarz może pojawić się na tym samym wierszu co zawartość skryptu, ale # musi być poprzedzony spacjami.
# This is a comment. It will be ignored.
name: chromecast #This is a TV.
Skrypt automatyzacji
Specyfikacja składni skryptu automatyzacji to schemat.
Schemat automatyzacji definiuje kilka struktur danych:
- Pojedyncza para klucz-wartość jest nazywana polem.
- Zbiór pól zdefiniowanych przez schemat to struktura.
Struct
Język skryptów automatyzacji definiuje kilka standardowych „bloków” lub struktur danych, zwanych strukturami.
Zwróć uwagę na strukturę automation, która definiuje 4 pola:
| Klucz | Typ | Opis |
|---|---|---|
|
|
Opcjonalnie: Nazwa automatyzacji. Ta nazwa nie jest widoczna dla użytkowników. Jest przeznaczona tylko dla deweloperów. |
|
|
|
[Starter] |
Wymagane. Lista starterów. |
|
|
Opcjonalnie: Warunek. |
|
|
|
Wymagane. Lista działań. |
Informacje sekcja zawiera definicje schematów wszystkich dostępnych struktur.
Nazwy kluczy są unikalne w danym typie struktury i uwzględniają wielkość liter.
Możliwe typy wartości:
- Typ prymitywny: bool, liczba, ciąg znaków, czas itp.
- Typ struktury: zbiór pól.
- Tablica typu danych. Tablica jest oznaczona symbolem
[]. Na przykład[string]jest tablicą ciągów tekstowych, a[Starter]jest tablicą struktur startowych. - Inne typy specjalne: Entity, FieldPath.
Opis każdego pola zawiera ważne informacje, w tym:
- Wymagane lub Opcjonalne, co wskazuje, czy pole jest wymagane, czy można je pominąć.
- Zależność pola. zależności mają tylko pola opcjonalne. Opisuje on dodatkowe kontrole podczas używania tego pola, takie jak Użyj pola B tylko wtedy, gdy pole A jest ustawione lub Jeśli używane jest pole A, nie ustawiaj pól B ani C.
- Możliwe wartości Na przykład ograniczony zbiór wartości pola Enum typu string lub zakres liczb, które mogą być używane w polu typu number.
Typowany struct
Niektóre struktury mogą reprezentować elementy początkowe 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 typowany element strukturalny, który jest rozszerzany przez inne podrzędne elementy strukturalne w polu type, takie jak time.schedule lub device.state.OnOff, aby zapewniać różne funkcje. Struktury condition i action są też typowane.
Dodatkowe pola w typie struct muszą być zgodne ze specyfikacją podrzędnego typu struct (type). Jeśli na przykład użyjesz typu device.state.OnOff jako type, w strukturze starter będą prawidłowe tylko polaokreślone dla tego typu
.
Tablica
W formacie YAML tablica wartości zaczyna się od - (kreska, a potem spacja). Tablica może zawierać wiele wartości typu Struct lub wiele wartości typu Primitive. Wartości w tablicy muszą być jednak tego samego typu.
Gdy 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. Parsujący język parser automatycznie spłaszczy macierz wielowymiarową do macierzy jednowymiarowej, w tym przypadku [1, 2, 3, 4].
# INVALID: multi-dimensional array
- - 1
- 2
- - 3
- 4
Primitive
Schemat skryptu automatyzacji obsługuje te proste typy danych:
|
Wartość logiczna |
|
|
Liczba |
Liczba całkowita lub dziesiętna |
|
Ciąg znaków |
Zwykły tekst Ciągów nie trzeba otaczać cudzysłowami, chyba że w określonych przypadkach. |
|
Data |
Miesiąc i dzień. Format to DD-MM lub DD/MM.
|
|
Godzina |
Pora dnia. Może to być czas zegarowy lub słoneczny.
Czas może być podany w formacie AM/PM lub 24-godzinnym. Sekundy są opcjonalne.
W przypadku czasu słonecznego
|
|
DateTime |
Rok, miesiąc, dzień i porę dnia. Pomiędzy częścią dotyczącą daty a częścią dotyczącą czasu musi być spacja. Format daty to RRRR-MM-DD lub RRRR/MM/DD. Format czasu jest taki sam jak w przypadku atrybutu [Time](#time). Strefa czasowa nie jest obsługiwana.
|
|
Dzień tygodnia |
|
|
Czas trwania |
Okres czasu.
|
| ColorHex |
Sześciocyfrowy kod szesnastkowy reprezentujący kolor. Brak
|
| Temperatura | Dane o normalnej temperaturze. Zawsze dodawaj
|
| ColorTemperature |
Temperatura barwowa w kelwinach.
|
Kolor
Kolory można określić na 3 sposoby: za pomocą typu prymitywnego ColorHex lub ColorTemperature albo typu złożonego SpectrumHSV.
SpectrumHSV
Typ SpectrumHSV określa kolor za pomocą 3 polów liczbowych:
- Odcień odpowiada długości fali koloru.
- Nasycenie określa 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 pierwotnych typów danych, 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 jednoznacznego identyfikowania elementów należących do użytkownika, takich jak urządzenie lub sala.
Urządzenie to najczęściej używany typ 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 służący do znajdowania danych w danych ładunku. W tym przykładzie currentVolume to ścieżka do 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 pól mogą wymagać kilku poziomów, aby dotrzeć do wymaganego elementu, a format różni się w zależności od tego, czy jest to działanie czy element startowy.
W przypadku starterów jest używana notacja kropkowa, a cała ścieżka znajduje się w tym samym polu. Robi się tak głównie w celu porównywania w ramach logiki podstawowej. Aby na przykład użyć temperatury barwowej jako wartości początkowej, użyj wartości 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, wykonaj te czynności:
actions:
- type: device.command.ColorAbsolute
devices: My Device - Room Name
color:
name: blue