Informazioni su YAML
YAML è un linguaggio molto 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 essenzialmente 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 obbligatori per un file 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'altra 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
racchiusa tra virgolette.
Sono accettate sia le virgolette semplici che quelle doppie, ma la virgoletta di chiusura deve corrispondere alla virgoletta di apertura.
Utilizzo corretto delle virgolette:
name: 'TV on lights off'
name: "TV on lights off"
Virgolette errate (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 della specifica 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
Qui 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 si tratta di chiavi secondarie
della chiave metadata.
Il rientro è rigoroso in YAML. Una struttura secondaria deve avere un rientro più marcato 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 è elencato in una nuova riga e ogni riga inizia con un trattino e uno spazio. Nell'esempio seguente sono presenti due elenchi:
- Un'automazione può avere più
starters, pertanto il primo comando iniziale inizia con un trattino e uno spazio. weekdaypuò avere più valori, pertanto ogni valore è rientrato ulteriormente 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 dei contenuti dello script, ma # deve essere precededo 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 di automazione è chiamata schema.
Lo schema Automations definisce un paio di strutture di dati:
- Una singola coppia chiave-valore è chiamata campo.
- Una raccolta di campi definiti dallo schema è chiamata Struct.
Struct
Il linguaggio di scripting dell'automazione definisce diversi "blocchi" o strutture di dati standard, chiamate Structs.
Dai un'occhiata alla struttura automation, che definisce quattro campi:
| Chiave | Tipo | Descrizione |
|---|---|---|
|
|
Facoltativo. Nome dell'automazione. Questo valore non viene mostrato agli utenti, ma è solo per riferimento degli sviluppatori. |
|
|
|
[Starter] |
Obbligatorio. Un elenco di comandi iniziali. |
|
|
Facoltativo. Condizione. |
|
|
|
[Azione] |
Obbligatorio. Un elenco di azioni. |
La sezione Reference fornisce le definizioni dello schema per tutti gli Structs disponibili.
I nomi delle chiavi sono univoci all'interno di una determinata struttura e sono sensibili alle maiuscole.
I tipi di valore possibili sono:
- Un tipo primitivo: bool, number, string, time e così via.
- Un tipo Struct: una raccolta di campi.
- Un array del tipo di dati. La matrice è indicata da
[]. Ad esempio,[string]è un array di stringhe e[Starter]è un array di strutture iniziali. - Altri tipi speciali: Entity, FieldPath.
La descrizione di ogni campo contiene informazioni importanti, tra cui:
- Obbligatorio o Facoltativo, che indica se il campo è obbligatorio o se può essere saltato.
- Dipendenza dei campi. Solo i campi facoltativi hanno dipendenze. Descrive i controlli aggiuntivi quando si utilizza questo campo, ad esempio Utilizza il campo B solo se è impostato il campo A o Quando viene utilizzato il campo A, non impostare il campo B o il campo C.
- Valori possibili. Ad esempio, l'insieme di valori limitati di un campo Enum di tipo stringa o un intervallo di numeri che può essere utilizzato in un campo di tipo numerico.
Struct con tipi
Alcuni Structs possono rappresentare comandi iniziali in base a una pianificazione o a un cambiamento 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 con tipi, estesa da altre strutture secondarie nel campo type, come time.schedule o device.state.OnOff, per fornire funzioni diverse. Anche le strutture condition e action sono tipizzate.
I campi aggiuntivi nello struct devono rispettare la specifica dello struct secondario (type). Ad esempio, quando utilizzi device.state.OnOff come type, solo
i
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. Tuttavia, 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 nello scripting di automazione. Il
parser del linguaggio appiattisce automaticamente un array multidimensionale in un
array a una dimensione, in questo caso [1, 2, 3, 4].
# INVALID: multi-dimensional array
- - 1
- 2
- - 3
- 4
originario
Lo schema dello script di automazione supporta i seguenti tipi di dati primitivi:
|
Bool |
|
|
Numero |
Numero intero o decimale |
|
Stringa |
Testo normale Le stringhe non devono essere racchiuse tra virgolette, tranne in casi specifici. |
|
Data |
Mese e giorno. Il formato è MM-GG o MM/GG.
|
|
Ora |
Ora del giorno. Può essere l'ora del quadrante o quella solare.
Per l'ora dell'orologio, puoi utilizzare il formato AM/PM o 24 ore. I secondi
sono facoltativi.
Per l'ora solare,
|
|
DateTime |
Anno, mese, giorno e ora del giorno. È necessario uno spazio tra la parte della data e la parte dell'ora. Il formato della data è AAAA-MM-GG o AAAA/MM/GG. Il formato dell'ora è uguale a [Ora](#time). Il fuso orario non è supportato.
|
|
Giorno feriale |
|
|
Durata |
Un periodo di tempo.
|
| ColorHex |
Un codice esadecimale a sei cifre che rappresenta un colore. Non è presente il carattere
|
| Temperatura | Dati sulla temperatura normale. Aggiungi sempre
|
| ColorTemperature |
Temperatura colore in Kelvin.
|
Colore
I colori possono essere specificati in tre modi: utilizzando i tipi primitivi ColorHex o ColorTemperature o il tipo composto SpectrumHSV.
SpectrumHSV
Il tipo SpectrumHSV specifica un colore utilizzando tre campi numerici:
- La tinta corrisponde alla lunghezza d'onda del colore.
- Saturazione indica l'intensità del colore.
- Valore indica la luminosità o la scurità relativa del colore.
Dinamico
A volte, il tipo di dati di una chiave non è fisso. Può essere uno dei tipi di base, 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.
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 di stringa speciale utilizzato per individuare un dato in un payload di dati. Nel
seguente esempio, currentVolume è il percorso del campo 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 è diverso tra comandi iniziali e azioni.
I comandi iniziali utilizzano una notazione con punti, con l'intero percorso nello stesso campo. Questo viene principalmente eseguito a scopo di confronto nella logica di comando iniziale. Ad esempio, per utilizzare la temperatura di colore come comando iniziale, devi usare color.colorTemperature per lo stato:
starters:
- type: device.state.ColorSetting
device: My Device - Room Name
state: color.colorTemperature
is: 2000K
Le azioni, invece, utilizzano campi nidificati. Per cambiare il colore di una lampadina in blu, instead of color.name and is: blue, devi:
actions:
- type: device.command.ColorAbsolute
devices: My Device - Room Name
color:
name: blue