Nozioni di base sulle lingue

Comprendere YAML

YAML è un linguaggio popolare utilizzato per specificare la configurazione del software. Fornisce un modo chiaro e leggibile per rappresentare informazioni strutturate. Ecco alcune nozioni di base su YAML che devi conoscere prima di creare la tua prima automazione basata su script. Per scoprire di più su YAML in generale, consulta la specifica della versione 1.1.

Coppie chiave-valore

I documenti YAML sono fondamentalmente una raccolta di coppie chiave-valore. Nell'esempio seguente, la chiave è name e il valore è TV on lights off. La chiave e il valore sono delimitati da due punti seguiti da uno spazio. Entrambi i caratteri sono necessari per YAML ben formato.

name: TV on lights off

Valori

Il valore associato a una chiave può essere semplice come una stringa, un numero o una data oppure complesso come un'ulteriore raccolta di coppie chiave/valore.

Stringa

Se un valore stringa inizia con uno dei seguenti caratteri: [, {, ", ' o # oppure se la stringa contiene : (due punti seguiti da spazi), deve essere racchiuso tra virgolette.

Sono accettate sia le virgolette singole che doppie, ma la virgoletta di chiusura deve corrispondere a quella di apertura.

Citazione corretta:

name: 'TV on lights off'

name: "TV on lights off"

Citazione errata (virgolette non corrispondenti):

name: 'TV on lights off"

Le virgolette sono facoltative per tutti gli altri tipi di stringhe.

Se hai bisogno di una stringa su più righe, consulta la sezione delle specifiche YAML sugli scalari su più righe.

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

Coppie chiave-valore nidificate

In questo caso, il valore della chiave metadata è un elenco di due coppie chiave-valore (name e description):

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

Rientro

YAML utilizza il rientro per indicare la struttura. Nell'esempio precedente, name e description sono rientrati (di due spazi) per indicare che sono i figli della chiave metadata.

Il rientro è rigoroso in YAML. Una struttura secondaria deve avere un rientro più profondo rispetto alla struttura principale e le coppie chiave-valore dello stesso livello devono avere lo stesso rientro.

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

Più valori

Se una determinata chiave ha più valori, ogni valore viene elencato su una nuova riga e ogni riga inizia con un trattino e uno spazio. Nel seguente esempio, sono presenti due elenchi:

1. Un'automazione può avere più starters, quindi il primo comando iniziale inizia con un trattino e uno spazio.
2. weekday può avere più valori e quindi ogni valore è ulteriormente rientrato e inizia con un trattino e uno spazio.

starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

Commenti

Qualsiasi testo che segue un # è considerato un commento e viene ignorato dal motore di automazione.

Una riga che inizia con # è un commento.

Un commento può essere visualizzato sulla stessa riga del contenuto del copione, ma il # deve essere preceduto da uno spazio.

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

Script di automazione

La specifica per la sintassi dello script Automazioni è chiamata schema.

Lo schema Automazioni definisce due strutture di dati:

• Una singola coppia chiave-valore è chiamata Campo.
• Una raccolta di campi definiti dallo schema è chiamata Struct.

Struct

Il linguaggio di scripting di automazione definisce diversi "blocchi" o strutture di dati standard, denominati Struct.

Dai un'occhiata alla automation Struct, che definisce quattro campi:

La sezione Riferimento fornisce le definizioni dello schema per tutte le strutture disponibili.

I nomi delle chiavi sono univoci all'interno di una determinata struttura e sono sensibili alle maiuscole.

I tipi di valori possibili sono:

• Un tipo primitivo: booleano, numero, stringa, ora e così via.
• Un tipo Struct: una raccolta di campi.
• Un array del tipo di dati. L'array è indicato da []. Ad esempio, [string] è un array di stringhe e [Starter] è un array di Starter Struct.
• Altri tipi speciali: Entity, FieldPath.

La descrizione di ogni campo contiene informazioni importanti, tra cui:

• Obbligatorio o facoltativo, indica se il campo è obbligatorio o se può essere ignorato.
• Dipendenza dei campi. Solo i campi facoltativi hanno dipendenze. Vengono descritte le verifiche aggiuntive quando si utilizza questo campo, ad esempio Utilizza il campo B solo se il campo A è impostato o Quando viene utilizzato il campo A, non impostare il campo B o il campo C.
• Valori possibili. Ad esempio, il set di valori limitato di un campo Enum di tipo stringa o un intervallo di numeri che possono essere utilizzati in un campo di tipo numerico.

Struct digitato

Alcuni Struct possono rappresentare comandi iniziali in base a una pianificazione oraria o a una modifica dello stato del dispositivo. Ogni tipo di starter deve fornire un insieme distinto di campi.

# 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

Un starter è una struttura tipizzata, estesa da altre strutture secondarie nel campo type, come time.schedule o device.state.OnOff, per fornire funzioni diverse. Anche gli struct condition e action sono tipizzati.

I campi aggiuntivi nello struct devono seguire la specifica dello struct secondario (type). Ad esempio, quando utilizzi device.state.OnOff come type, solo i campii campi specificati per quel tipo sono validi in quella struttura starter.

Array

In YAML, un array di valori inizia con - (un trattino seguito da uno spazio). L'array può contenere più valori Struct o più valori primitivi. ma i valori nell'array devono essere dello stesso tipo.

Quando l'array contiene un solo elemento, puoi omettere il trattino e lo spazio:

# 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

Gli array multidimensionali, come [[1, 2], [3, 4]], non sono supportati negli script di automazione. Il parser del linguaggio appiattirà automaticamente un array multidimensionale in un array monodimensionale, in questo caso [1, 2, 3, 4].

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

originario

I seguenti tipi di dati primitivi sono supportati dallo schema dello script Automazioni:

Colore

I colori possono essere specificati in tre modi: utilizzando i tipi primitivi ColorHex o ColorTemperature oppure il tipo composto SpectrumHSV.

SpectrumHSV

Il tipo SpectrumHSV specifica un colore utilizzando tre campi numerici:

• Tonalità corrisponde alla lunghezza d'onda del colore.
• Saturazione indica l'intensità del colore.
• Valore indica la luminosità o l'oscurità relativa del colore.

Dinamico

A volte, il tipo di dati di una chiave non è fisso. Può essere uno dei tipi primitivi, in base ai valori di altri campi.

Un esempio di campo di tipo di dati dinamico è is. Il tipo effettivo è determinato dai valori dei campi type e state.

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

Un formato di stringa speciale per identificare in modo univoco un'entità di proprietà dell'utente, ad esempio un dispositivo o una stanza.

Il dispositivo è l'entità più comune utilizzata nelle automazioni. Il formato della stringa dell'entità è 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

Un formato stringa speciale utilizzato per individuare un elemento di dati in un payload di dati. Nell'esempio seguente, currentVolume è il FieldPath per il campo state.

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

Altri FieldPath potrebbero richiedere più livelli per raggiungere l'elemento richiesto e il formato varia tra l'intent iniziale e l'azione.

Gli starter utilizzano una notazione con punti, con l'intero percorso nello stesso campo. Questa operazione viene eseguita principalmente a scopo di confronto nella logica di avvio. Ad esempio, per utilizzare la temperatura del colore come punto di partenza, utilizzeresti color.colorTemperature per lo stato:

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

Le azioni, tuttavia, utilizzano campi nidificati. Per cambiare il colore di una lampadina in blu, invece di color.name e is: blue, devi:

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