Sprachgrundlagen

YAML

YAML ist eine gängige Sprache, mit der die Softwarekonfiguration angegeben wird. Es bietet eine klare, für Menschen lesbare Möglichkeit, strukturierte Informationen darzustellen. Hier sind einige grundlegende Dinge, die Sie über YAML wissen müssen, bevor Sie Ihren ersten scriptbasierten Ablauf erstellen. Weitere Informationen zu YAML 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 name der Schlüssel und TV on lights off der Wert. Schlüssel und Wert werden durch einen Doppelpunkt gefolgt von einem Leerzeichen voneinander getrennt. Beide Zeichen sind für korrekt formatierte YAML-Dateien 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 Zitate:

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 zur YAML-Spezifikation für mehrzeilige Skalare.

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 dargestellt. 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 stärker 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 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 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 Script-Inhalt erscheinen, aber vor # muss ein Leerzeichen stehen.

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

Automatisierungsskript

Die Spezifikation für die Scriptsyntax von automatisierten Abläufen wird als Schema bezeichnet.

Das Schema „Automations“ definiert einige Datenstrukturen:

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

Struct

Die Scriptsprache für Automatisierungen definiert mehrere Standardblöcke oder Datenstrukturen, die als Structs bezeichnet werden.

Sehen wir uns das automation-Objekt an, das vier Felder definiert:

Im Abschnitt Referenz finden Sie Schemadefinitionen für alle verfügbaren Strukturen.

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

Mögliche Werttypen sind:

• Ein primitiver Typ: boolescher Wert, Zahl, String, Zeit usw.
• Ein Strukturtyp: eine Sammlung von Feldern.
• Ein Array des Datentyps. Das Array wird durch [] dargestellt. Beispiel: [string] ist ein Array von Strings und [Starter] ein Array von Starter-Structs.
• Andere spezielle Typen: „Entity“ und „FieldPath“.

Die Beschreibung jedes Felds 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 bei der Verwendung dieses Felds beschrieben, 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 Beispielsweise der eingeschränkte Wertesatz eines Enum-Felds vom Typ „String“ oder ein Zahlenbereich, der in einem Feld vom Typ „Zahl“ verwendet werden kann.

Typisierte Struktur

Einige Structs können Auslöser basierend auf einem Zeitplan oder einer Gerätestatusänderung darstellen. Für jeden starter-Typ müssen unterschiedliche Felder 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 ein typisierter Datentyp, der durch andere untergeordnete Datentypen im Feld type, z. B. time.schedule oder device.state.OnOff, erweitert wird, um verschiedene Funktionen bereitzustellen. Die Structs condition und action sind ebenfalls typisiert.

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

Array

In YAML beginnt ein Array mit Werten 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 nur ein Element enthält, können Sie den Bindestrich und den Leerraum 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 flacht ein mehrdimensionales Array automatisch in ein eindimensionales Array ab, in diesem Fall [1, 2, 3, 4].

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

Schlicht

Die folgenden primitiven Datentypen werden vom Script-Schema für Automatisierungen 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

Beim Typ „SpectrumHSV“ wird eine Farbe mit drei numerischen Feldern angegeben:

• Der Farbton entspricht der Farbwellenlänge.
• Die 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, der auf den Werten anderer Felder basiert.

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, mit dem eine vom Nutzer besessene Entität wie ein Gerät oder ein Raum eindeutig identifiziert werden kann.

„Gerät“ ist die am häufigsten in Automatisierungen verwendete Entität. 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 sich ein Datenelement in einer Datennutzlast finden lässt. 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 Punktschreibweise, bei der sich der gesamte Pfad im selben Feld befindet. Dies geschieht 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 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 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