Sprachgrundlagen

YAML verstehen

YAML ist eine beliebte Sprache, die zur Festlegung der Softwarekonfiguration verwendet wird. Sie bietet eine klare, für Menschen lesbare Möglichkeit, strukturierte Informationen darzustellen. Im Folgenden finden Sie einige grundlegende Informationen zu YAML, bevor Sie Ihre erste scriptbasierte Automatisierung erstellen. Weitere Informationen zu YAML im Allgemeinen finden Sie in der Spezifikation von Version 1.1.

Schlüssel/Wert-Paare

YAML-Dokumente sind im Grunde eine Sammlung von Schlüssel/Wert-Paaren. Im folgenden Beispiel ist der Schlüssel name und der Wert TV on lights off. Schlüssel und Wert werden durch einen Doppelpunkt gefolgt von einem Leerzeichen voneinander getrennt. Für korrekt formatierte YAML-Dateien sind beide Zeichen erforderlich.

name: TV on lights off

Werte

Der einem Schlüssel zugeordnete Wert kann so einfach sein wie ein String, eine Zahl oder ein Datum oder so komplex wie eine andere Sammlung von Schlüssel/Wert-Paaren.

Strings

Wenn ein Stringwert mit einem der folgenden Zeichen beginnt: [, {, ", ' oder # oder der String : (einen Doppelpunkt gefolgt von Leerzeichen) enthält, muss er in Anführungszeichen gesetzt werden.

Sowohl einfache als auch doppelte Anführungszeichen sind zulässig, das schließende Anführungszeichen muss jedoch mit dem einleitenden Anführungszeichen übereinstimmen.

Richtige Zitation:

name: 'TV on lights off'

name: "TV on lights off"

Falsche Anführungszeichen (nicht übereinstimmende Anführungszeichen):

name: 'TV on lights off"

Anführungszeichen sind für alle anderen Zeichenfolgentypen optional.

Wenn Sie einen mehrzeiligen String benötigen, lesen Sie den Abschnitt zur YAML-Spezifikation zu mehrzeiligen Skalaren.

name: "[1] TV"
name: '{1} TV'
name: '#TV'
name: '"1" TV'
name: "'1' TV"
name: "\"1\" TV"
name: "TV: bedroom"

Verschachtelte Schlüssel/Wert-Paare

In diesem Fall ist der Wert des Schlüssels metadata eine Liste aus zwei Schlüssel/Wert-Paaren (name und description):

metadata:
  name: TV on lights off
  description: Turn off lights when TV turns on

Einzug

In YAML werden Einzüge verwendet, um Strukturen anzugeben. Im vorherigen Beispiel sind name und description um zwei Leerzeichen eingerückt, um anzuzeigen, dass dies die untergeordneten Elemente des Schlüssels metadata sind.

Die Einrückung ist in YAML strikt. Eine untergeordnete Struktur muss eine tiefere Einrückung als das übergeordnete Element haben und Schlüssel/Wert-Paare auf derselben Ebene müssen dieselbe Einrückung haben.

metadata:
  name:
    en: TV on lights off
  description:
    en: Turn off lights when TV turns on

Mehrere Werte

Wenn ein bestimmter Schlüssel mehrere Werte hat, wird jeder Wert in einer neuen Zeile aufgeführt und jede Zeile beginnt, gefolgt von einem Bindestrich und einem Leerzeichen. Im folgenden Beispiel gibt es zwei Listen:

  1. Eine Automatisierung kann mehrere starters haben. Daher beginnt der erste Auslöser mit einem Bindestrich und einem Leerzeichen.
  2. weekday kann mehrere Werte haben. Daher ist jeder Wert weiter eingerückt und beginnt mit einem Bindestrich und einem Leerzeichen.
starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

Kommentare

Text, der auf # folgt, wird als Kommentar betrachtet und von der Automatisierungs-Engine ignoriert.

Eine Zeile, die mit # beginnt, ist ein Kommentar.

Ein Kommentar kann in derselben Zeile wie der Skriptinhalt stehen, aber # muss ein Leerzeichen vorangestellt sein.

# This is a comment. It will be ignored.
name: chromecast #This is a TV.

Automatisierungsscript

Die Spezifikation für die Syntax des Automatisierungsskripts wird als Schema bezeichnet.

Im Automatisierungsschema werden einige Datenstrukturen definiert:

  • Ein einzelnes Schlüssel/Wert-Paar wird als Feld bezeichnet.
  • Eine Sammlung von durch das Schema definierten Feldern wird als Struct bezeichnet.

Struct

Die Automatisierungs-Scriptsprache definiert mehrere Standardblöcke oder Datenstrukturen, die als Strukturen bezeichnet werden.

Sehen Sie sich die Struktur automation an, die vier Felder definiert:

Key Typ Beschreibung

name

String

Optional.

Name der Automatisierung.

Dieser Name wird Nutzern nicht angezeigt und dient nur als Referenz für Entwickler.

starters

[Auslöser]

Erforderlich.

Eine Liste mit Auslösern.

condition

Bedingung

Optional.

Zustand.

actions

[Aktion]

Erforderlich.

Eine Liste mit Aktionen.

Der Abschnitt Referenz enthält Schemadefinitionen für alle verfügbaren Structs.

Schlüsselnamen sind innerhalb einer bestimmten Struktur eindeutig und es wird zwischen Groß- und Kleinschreibung unterschieden.

Mögliche Werttypen sind:

  • Ein Primitive-Typ: bool, Zahl, String, Zeit usw.
  • Strukturtyp: eine Sammlung von Feldern
  • Ein Array des Datentyps. Das Array wird durch [] angegeben. Beispielsweise ist [string] ein Array von Strings und [Starter] ein Array von Startstrukturen.
  • Andere spezielle Typen: Entity, FieldPath.

Die Beschreibung der einzelnen Felder enthält unter anderem folgende Informationen:

  • Erforderlich oder optional und gibt an, ob das Feld obligatorisch ist oder ob es übersprungen werden kann.
  • Feldabhängigkeit. Nur optionale Felder haben Abhängigkeiten. Dies beschreibt die zusätzlichen Prüfungen bei Verwendung dieses Feldes, z. B. Feld B nur verwenden, wenn Feld A festgelegt ist oder Bei Verwendung von Feld A Feld B oder Feld C nicht festlegen.
  • Mögliche Werte. Das kann z. B. der begrenzte Wertesatz eines Enum-Felds vom Typ „String“ oder ein Zahlenbereich sein, der in einem Feld vom Typ „Nummer“ verwendet werden kann.

Eingegebene Struktur

Einige Structs können Auslöser sein, die auf einem Zeitplan oder einer Gerätestatusänderung basieren. Für jeden starter-Typ muss eine eigene Gruppe von Feldern angegeben werden.

# 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

Ein starter ist eine typisierte Struktur, die durch andere untergeordnete Strukturen im Feld type erweitert wird, z. B. time.schedule oder device.state.OnOff, um verschiedene Funktionen bereitzustellen. Die Structs condition und action werden ebenfalls eingegeben.

Zusätzliche Felder in der Struktur müssen der Spezifikation der untergeordneten Struktur (type) entsprechen. Wenn Sie beispielsweise device.state.OnOff als type verwenden, sind nur die Felderfür diesen Typ angegeben wurden , in dieser starter-Struktur gültig.

Array

In YAML beginnt ein Wertearray mit - (ein Bindestrich gefolgt von einem Leerzeichen). Das Array kann mehrere Strukturwerte oder mehrere Primitive Werte enthalten. Die Werte im Array müssen jedoch denselben Typ haben.

Wenn das Array ein einzelnes Element enthält, können Sie den Bindestrich und das Leerzeichen weglassen:

# 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

Mehrdimensionale Arrays wie [[1, 2], [3, 4]] werden in Automatisierungsscripts nicht unterstützt. Der Sprachparser vereinfacht die Darstellung eines mehrdimensionalen Arrays automatisch in einem eindimensionalen Array, in diesem Fall [1, 2, 3, 4].

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

Primitiv

Die folgenden primitiven Datentypen werden vom Automatisierungsskriptschema unterstützt:

Boolescher Wert
  • true
  • false

Zahl

Ganzzahl oder Dezimalzahl

String

Nur-Text

Strings müssen außer in bestimmten Fällen nicht in Anführungszeichen gesetzt werden.

Datum

Monat und Tag. Das Format ist MM-TT oder MM/TT.

  • 09/01
  • 09-01

Uhrzeit

Tageszeit. Das kann die Uhrzeit oder die Solarzeit sein. Die Uhrzeit kann im AM/PM- oder 24-Stunden-Format angegeben werden. Sekunden sind optional. Für die Solarzeit sind sunrise und sunset Keywords, denen ein Offset (bei Bezug auf die Dauer) folgen kann.

  • 12:30 am
  • 13:00:01
  • sunrise / sunset
  • sunset+30min / sunset-1hour

DateTime

Jahr, Monat, Tag und Uhrzeit. Zwischen dem Teil „Datum“ und „Uhrzeit“ ist Leerzeichen erforderlich. Das Datumsformat ist JJJJ-MM-TT oder JJJJ/MM/TT. Das Zeitformat entspricht der [Zeit](#time). Zeitzone wird nicht unterstützt.

  • 2022/01/01 14:00
  • 2022-12-31 sunrise+30min

Wochentag

  • MONDAY oder MON
  • TUESDAY oder TUE
  • WEDNESDAY oder WED
  • THURSDAY oder THU
  • FRIDAY oder FRI
  • SATURDAY oder SAT
  • SUNDAY oder SUN

Dauer

Ein Zeitraum.

  • 30min
  • 1hour
  • 20sec
  • 1hour10min20sec
ColorHex

Ein sechsstelliger Hexadezimalcode, der eine Farbe darstellt.

Es gibt keinen führenden #.

  • FFFFFF
  • B5D2A1
  • DFA100
Temperatur

Normale Temperaturdaten. Addiere immer 'C' oder 'F' zum Wert, um eine Temperaturmessung zu kennzeichnen.

  • 20.5C
  • 90F
ColorTemperature

Farbtemperatur in Kelvin.

  • 5000K

Farbe

Farben können auf drei Arten angegeben werden – entweder mit den Primitiven ColorHex oder ColorTemperature oder mit dem Verbindungstyp SpectrumHSV.

SpectrumHSV

Der SpectrumHSV-Typ gibt eine Farbe mithilfe von drei numerischen Feldern an:

  • Farbton entspricht der Wellenlänge der Farbe.
  • Sättigung gibt die Intensität der Farbe an.
  • Wert gibt die relative Helligkeit der Farbe an.

Dynamisch

Manchmal ist der Datentyp eines Schlüssels nicht festgelegt. Es kann sich um einen der primitiven Typen handeln, basierend auf den Werten aus anderen Feldern.

Ein Beispiel für ein dynamisches Datentypfeld ist is. Der tatsächliche Typ wird durch die Werte der Felder type und state bestimmt.

# 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

Entität

Ein spezielles String-Format, um eine Entität, die dem Nutzer gehört, wie ein Gerät oder einen Raum eindeutig zu identifizieren.

„Gerät“ ist die am häufigsten in Automatisierungen verwendete Entität. Das String-Format für Entitäten ist 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

Ein spezielles String-Format, das zum Suchen eines Datenelements in einer Datennutzlast verwendet wird. Im folgenden Beispiel ist currentVolume der FieldPath für das Feld state.

# The state field accepts a FieldPath type.
starters:
  type: device.state.Volume
  device: My TV - Living Room
  state: currentVolume
  is: 5

Für andere FieldPaths sind möglicherweise mehrere Ebenen erforderlich, um zum erforderlichen Element zu gelangen. Das Format unterscheidet sich je nach Auslöser und Aktion.

Auslöser verwenden eine Punktnotation, wobei sich der gesamte Pfad im selben Feld befindet. Dies dient hauptsächlich zu Vergleichszwecken in der Auslöserlogik. Wenn Sie beispielsweise die Farbtemperatur als Auslöser verwenden möchten, verwenden Sie color.colorTemperature für den Bundesstaat:

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

Für Aktionen werden hingegen verschachtelte Felder verwendet. So ändern Sie die Farbe einer Lampe anstelle von color.name und is: blue in Blau:

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