Sprachgrundlagen

YAML verstehen

YAML ist eine beliebte Sprache, die zum Festlegen der Softwarekonfiguration verwendet wird. Es bietet eine klare, für Menschen lesbare Möglichkeit, strukturierte Informationen darzustellen. Bevor Sie Ihren ersten scriptbasierten automatischen Ablauf erstellen, sollten Sie sich mit den Grundlagen von YAML vertraut machen. Weitere Informationen zu YAML finden Sie in der Spezifikation 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 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 der String : (ein Doppelpunkt gefolgt von Leerzeichen) enthält, muss er in Anführungszeichen gesetzt werden.

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

Korrekte Quellenangabe:

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 zu mehrzeiligen Skalaren in der YAML-Spezifikation.

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 wird die Struktur durch Einzüge angegeben. Im vorherigen Beispiel sind name und description um zwei Leerzeichen eingerückt, um anzugeben, dass sie dem Schlüssel metadata untergeordnet sind.

Die Einrückung ist in YAML streng. 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. Der erste Auslöser beginnt daher 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

Jeder 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 Skriptinhalt stehen, aber # muss von einem Leerzeichen gefolgt werden.

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

Automatisierungsskript

Die Spezifikation für die Automatisierungsskriptsyntax wird als Schema bezeichnet.

Im Automatisierungsschema werden einige Datenstrukturen definiert:

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

Struct

In der Automatisierungs-Scriptsprache sind mehrere Standardblöcke oder Datenstrukturen definiert, die als Structs bezeichnet werden.

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

Im Abschnitt Referenz finden Sie 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:

• Ein einfacher Typ: bool, number, string, time usw.
• Ein Struct-Typ: eine Sammlung von Feldern.
• Ein Array des Datentyps. Das 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. Das kann beispielsweise der eingeschränkte Satz von Werten eines Enum-Felds vom Typ „string“ oder ein Bereich von Zahlen sein, die in einem Feld vom Typ „number“ verwendet werden können.

Typisierte Struktur

Einige Structs können Auslöser basierend auf einem Zeitplan oder einer Änderung des Gerätestatus darstellen. Für jeden Typ von starter muss ein anderer Satz 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

starter ist ein typisiertes Struct, das durch andere untergeordnete Structs im Feld type erweitert wird, z. B. time.schedule oder device.state.OnOff, um verschiedene Funktionen bereitzustellen. Die condition- und action-Structs sind ebenfalls typisiert.

Zusätzliche Felder im Struct müssen der Spezifikation des untergeordneten Struct (type) entsprechen. Wenn Sie beispielsweise device.state.OnOff als type verwenden, sind nur dieFelder, die für diesen Typ angegeben sind in diesem starter-Struct gültig.

Array

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

Wenn das Array nur ein 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 Automatisierungsskripts nicht unterstützt. Der Sprachparser fasst ein mehrdimensionales Array automatisch in einem eindimensionalen Array zusammen, in diesem Fall [1, 2, 3, 4].

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

Schlicht

Die folgenden primitiven Datentypen werden vom Automationsskriptschema 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:

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

Dynamisch

Manchmal ist der Datentyp eines Schlüssels nicht festgelegt. Er 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 String-Format zur eindeutigen Identifizierung einer Entität, die einem Nutzer gehört, z. B. ein Gerät oder ein Raum.

Geräte sind die am häufigsten verwendeten Einheiten in Automatisierungen. 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 String-Format, das verwendet wird, um Daten in einer Daten-Payload zu finden. 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 gewünschten Element zu gelangen. Das Format unterscheidet sich zwischen Starter und Aktion.

Starter verwenden eine Punktnotation, wobei der gesamte Pfad im selben Feld angegeben wird. Dies geschieht hauptsächlich zu Vergleichszwecken in der Starterlogik. Wenn Sie beispielsweise die Farbtemperatur als Ausgangspunkt verwenden möchten, verwenden Sie color.colorTemperature für den Status:

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

Bei Aktionen werden jedoch verschachtelte Felder verwendet. Wenn Sie die Farbe einer Glühbirne 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