Sprachgrundlagen

YAML verstehen

YAML ist eine gängige Sprache, die zur Angabe von Softwarekonfigurationen verwendet wird. Es bietet eine klare, menschenlesbare Möglichkeit, strukturierte Informationen darzustellen. Hier sind einige grundlegende Dinge, die du über YAML wissen solltest, bevor du deinen ersten scriptbasierten automatisierten Ablauf erstellst. Weitere Informationen zu YAML im Allgemeinen finden Sie in der Spezifikation für 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 getrennt. Beide Zeichen sind für ein wohlgeformtes YAML erforderlich.

name: TV on lights off

Werte

Der mit einem Schlüssel verknüpfte Wert kann einfach ein String, eine Zahl oder ein Datum sein oder aber eine komplexe Sammlung von Schlüssel/Wert-Paaren.

Strings

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

Sowohl einfache als auch doppelte Anführungszeichen werden akzeptiert, aber das schließende Anführungszeichen muss mit dem öffnenden Anführungszeichen übereinstimmen.

Korrekte Anführungszeichen:

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 Arten von Strings optional.

Wenn Sie einen mehrzeiligen String benötigen, lesen Sie den Abschnitt der 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

Hier ist der Wert des Schlüssels metadata eine Liste mit 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 die Struktur anzugeben. Im vorherigen Beispiel sind name und description um zwei Leerzeichen eingerückt, um anzugeben, dass sie dem Schlüssel metadata untergeordnet sind.

In YAML ist die Einrückung strikt. Eine untergeordnete Struktur muss tiefer eingerückt sein als die übergeordnete Struktur. 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. Jede Zeile beginnt mit 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 wird 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

Der gesamte Text nach einem # 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 Scriptinhalt stehen, aber vor dem # muss ein Leerzeichen stehen.

# 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.

Das Automatisierungsschema definiert einige Datenstrukturen:

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

Struct

In der Scriptsprache für automatisierte Abläufe werden mehrere Standardblöcke oder Datenstrukturen definiert, die als Strukturen bezeichnet werden.

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

Im Abschnitt Referenz findest du Schemadefinitionen für alle verfügbaren Structs.

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

Folgende Werttypen sind möglich:

• Ein primitiver Typ: bool, number, string, time usw.
• Ein Struct-Typ: eine Sammlung von Feldern.
• Ein Array des Datentyps. Ein Array wird durch [] gekennzeichnet. [string] ist beispielsweise ein Array von Strings und [Starter] ein Array von Starter-Structs.
• Andere spezielle Typen: Entity, FieldPath.

Die Beschreibung der einzelnen Felder enthält wichtige Informationen, darunter:

• „Erforderlich“ oder „Optional“: Gibt an, ob das Feld obligatorisch ist oder übersprungen werden kann.
• Feldabhängigkeit. Nur optionale Felder haben Abhängigkeiten. Hier werden die zusätzlichen Prüfungen beschrieben, die bei Verwendung dieses Felds durchgeführt werden, z. B. Feld B nur verwenden, wenn Feld A festgelegt ist oder Wenn Feld A verwendet wird, Feld B oder Feld C nicht festlegen.
• Mögliche Werte. Beispiele sind der begrenzte Wertesatz eines Enum-Felds vom Typ „String“ oder ein Zahlenbereich, der in einem Feld vom Typ „Zahl“ verwendet werden kann.

Typisierte Struct

Einige Structs können Auslöser darstellen, die auf einem Zeitplan oder einer Änderung des Gerätestatus basieren. Jeder Typ von starter muss einen eigenen Satz von Feldern bereitstellen.

# 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 ein Typed Struct, das durch andere untergeordnete Structs im Feld type erweitert wird, z. B. time.schedule oder device.state.OnOff, um verschiedene Funktionen bereitzustellen. Die Structs condition und action sind ebenfalls typisiert.

Zusätzliche Felder im Struct müssen der Spezifikation für untergeordnete Structs (type) entsprechen. Wenn Sie beispielsweise device.state.OnOff als type verwenden, sind nur diefür diesen Typ angegebenen Felder in dieser starter-Struktur gültig.

Array

In YAML beginnt ein Array von Werten mit - (ein Bindestrich gefolgt von einem Leerzeichen). Das Array kann mehrere Struct-Werte oder mehrere Primitive-Werte enthalten. Die Werte im Array müssen jedoch vom selben Typ sein.

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 ein mehrdimensionales Array automatisch in ein eindimensionales Array, in diesem Fall [1, 2, 3, 4].

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

Schlicht

Die folgenden primitiven Datentypen werden vom Automatisierungsscriptschema unterstützt:

Farbe

Farben können auf drei Arten angegeben werden: entweder mit den primitiven Typen ColorHex oder ColorTemperature oder mit dem zusammengesetzten Typ SpectrumHSV.

SpectrumHSV

Der Typ „SpectrumHSV“ gibt eine Farbe mit drei numerischen Feldern an:

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

Dynamisch

Manchmal ist der Datentyp eines Schlüssels nicht festgelegt. Es kann einer der primitiven Typen sein, basierend auf den Werten aus anderen Feldern.

Ein Beispiel für ein Feld mit dynamischem Datentyp 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 Stringformat zur eindeutigen Identifizierung einer nutzereigenen Entität, z. B. eines Geräts oder Raums.

Geräte sind die am häufigsten verwendeten Entitäten in automatisierten Abläufen. Das Stringformat der Entität 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 Stringformat, mit dem ein Datenelement in einer Datennutzlast gefunden 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

Bei anderen FieldPaths sind möglicherweise mehrere Ebenen erforderlich, um zum gewünschten Element zu gelangen. Das Format unterscheidet sich zwischen Auslöser und Aktion.

Auslöser verwenden eine Punktnotation, wobei der gesamte Pfad im selben Feld steht. Dies geschieht hauptsächlich zu Vergleichszwecken in der Starterlogik. Wenn du beispielsweise die Farbtemperatur als Auslöser verwenden möchtest, verwende color.colorTemperature für den Status:

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

Aktionen verwenden jedoch verschachtelte Felder. Wenn Sie die Farbe einer Lampe in Blau ändern möchten, müssen Sie anstelle von color.name und is: blue Folgendes tun:

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