Sprachgrundlagen

YAML

YAML ist eine beliebte Sprache zum Angeben von Software. Konfiguration. Sie bietet eine klare, visuell lesbare Möglichkeit, Strukturierte Informationen. Hier sind ein paar grundlegende Dinge, die Sie über bevor Sie Ihre erste scriptbasierte Automatisierung 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: Der Schlüssel ist name und der Wert ist TV on lights off. Schlüssel und Wert werden durch einen Doppelpunkt gefolgt von einem Leerzeichen getrennt. Beide Zeichen sind erforderlich für korrekt formatierten YAML-Code schreiben.

name: TV on lights off

Werte

Der mit einem Schlüssel verknüpfte Wert kann so einfach wie ein String, eine Zahl oder ein oder so komplex wie eine weitere Sammlung von Schlüssel/Wert-Paaren.

Strings

Beginnt ein Stringwert mit einem der folgenden Zeichen: [, {, ", ' oder # enthält, oder der String : (ein Doppelpunkt gefolgt von Leerzeichen) enthält, muss dies zitiert werden.

Sowohl einfache als auch doppelte Anführungszeichen werden akzeptiert, das schließende Anführungszeichen muss jedoch übereinstimmen. das Eröffnungs-Anführungszeichen.

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 Stringtypen optional.

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

In diesem Fall ist der Wert des Schlüssels metadata eine Liste von 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 werden um zwei Leerzeichen eingerückt, um anzuzeigen, dass dies die untergeordneten Elemente des Schlüssels metadata.

In YAML ist die Einrückung 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

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

1. Eine Automatisierung kann mehrere starters und daher den ersten Auslöser haben. beginnt 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 Skriptinhalt stehen, das # muss jedoch ein vorangestelltes Leerzeichen.

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

Automatisierungsskript

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

Das Automatisierungsschema definiert eine Reihe von 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

Mit der Automatisierungs-Scriptsprache werden mehrere Standardblöcke definiert. oder Daten Strukturen, die als Strukturen bezeichnet werden.

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

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

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

Mögliche Werttypen sind:

• Ein einfacher Typ: boolescher Wert, Zahl, Zeichenfolge, Zeit usw.
• Ein Strukturtyp: eine Sammlung von Feldern.
• Ein Array des Datentyps. Das Array ist durch [] gekennzeichnet. Beispiel: [string] ist ein Array von Strings und [Starter] ist ein Array von Start-Structs.
• Weitere Sondertypen: 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 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 auf der Grundlage eines Zeitplans oder Gerätestatus darstellen ändern können. 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

Eine starter ist eine Typed Struktur, die durch andere untergeordnete Structs im type-Feld, z. B. time.schedule oder device.state.OnOff, für die Bereitstellung für verschiedene Funktionen. Die Structs condition und action sind ebenfalls typisiert.

Zusätzliche Felder in der Struktur müssen der untergeordneten Struktur (type) folgen Spezifikation zu ändern. Wenn Sie beispielsweise device.state.OnOff als type verwenden, die dazu angegebene Felder Typ sind gültig in dieser starter-Struktur.

Array

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

Wenn das Array ein einzelnes Element enthält, können Sie Bindestriche und 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. Die Der Sprachparser vereinfacht ein mehrdimensionales Array automatisch zu einem Array mit einer einzelnen Dimension, 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

Sie haben drei Möglichkeiten, Farben anzugeben: Sie können entweder die die primitiven Typen ColorHex oder ColorTemperature haben, oder den Mischtyp SpectrumHSV.

SpectrumHSV

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

• Farbton entspricht der Farbwellenlänge.
• 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. Dies kann eine der Primitiv- basierend auf den Werten aus anderen Feldern.

Ein Beispiel für ein dynamisches Datentypfeld ist is. Der tatsächliche Typ ist 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 nutzereigenen Entität wie Gerät oder Raum.

Das Gerät ist die am häufigsten in Automatisierungen verwendete Entität. Format des Entitätsstrings 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 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. unterscheidet sich das Format von Auslöser und Aktion.

Für Auslöser wird eine Punktnotation verwendet, wobei sich der gesamte Pfad im selben Feld befindet. Dies ist in erster Linie zu Vergleichszwecken in der Startlogik dienen. Um beispielsweise als Auslöser verwenden, würden Sie color.colorTemperature für die Bundesland:

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

Für Aktionen werden jedoch verschachtelte Felder verwendet. Um die Farbe einer Glühbirne in Blau zu ändern, statt color.name und is: blue müssen Sie Folgendes tun:

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