Entender o YAML
YAML é uma linguagem conhecida usada para especificar a configuração do software. Ele oferece uma maneira clara e legível para representar informações estruturadas. Confira algumas informações básicas sobre o YAML antes de criar sua primeira automação com script. Para saber mais sobre o YAML em geral, consulte a especificação da versão 1.1.
Pares de chave-valor
Os documentos YAML são basicamente uma coleção de pares de chave-valor. No exemplo a seguir, a chave é name e o valor é TV on lights off. A chave e o valor
são delimitados por dois-pontos seguidos de um espaço. Ambos os caracteres são necessários para
YAML bem formado.
name: TV on lights off
Valores
O valor associado a uma chave pode ser tão básico quanto uma string, um número ou uma data, ou tão complexo quanto outra coleção de pares de chave-valor.
Strings
Se um valor de string começar com um dos seguintes caracteres: [, {, ",
' ou #, ou se a string contiver : (dois-pontos seguidos de espaços), ela precisará ser
colocada entre aspas.
Aspas simples e duplas são aceitas, mas a citação de fechamento precisa corresponder à abertura.
Citação correta:
name: 'TV on lights off'
name: "TV on lights off"
Citação incorreta (aspas incompatíveis):
name: 'TV on lights off"
As aspas são opcionais para todos os outros tipos de strings.
Se você precisar de uma string de várias linhas, consulte a seção de especificação do YAML sobre escalares de várias linhas.
name: "[1] TV"
name: '{1} TV'
name: '#TV'
name: '"1" TV'
name: "'1' TV"
name: "\"1\" TV"
name: "TV: bedroom"
Pares de chave-valor aninhados
Aqui, o valor da chave metadata é uma lista de dois pares de chave-valor (name e description):
metadata:
name: TV on lights off
description: Turn off lights when TV turns on
Recuo
O YAML usa recuo para denotar a estrutura. No exemplo anterior, name e
description têm recuo (dois espaços) para indicar que são filhos
da chave metadata.
O recuo é rigoroso no YAML. Uma estrutura filha precisa ter recuo mais profundo do que a estrutura pai, e os pares chave-valor do mesmo nível precisam ter o mesmo recuo.
metadata:
name:
en: TV on lights off
description:
en: Turn off lights when TV turns on
Diversos valores
Se uma determinada chave tiver vários valores, cada valor será listado em uma nova linha, e cada linha será iniciada por um traço e um espaço. No exemplo abaixo, há duas listas:
- Uma automação pode ter vários
starters, e, portanto, o primeiro ativador começa com um traço e um espaço. weekdaypode ter vários valores. Portanto, cada valor é recuado e começa com um traço e um espaço.
starters:
- type: time.schedule
at: SUNSET
weekday:
- MONDAY
- THURSDAY
state: on
Comentários
Qualquer texto após um # é considerado um comentário e é ignorado
pelo mecanismo de automação.
Uma linha que começa com # é um comentário.
Um comentário pode aparecer na mesma linha do conteúdo do script, mas o # precisa
ser precedido por um espaço.
# This is a comment. It will be ignored.
name: chromecast #This is a TV.
Script de automação
A especificação da sintaxe do script de automação é chamada de esquema.
O esquema de automações define algumas estruturas de dados:
- Um único par de chave-valor é chamado de campo.
- Uma coleção de campos definidos pelo esquema é chamada de Struct.
Struct
A linguagem de script de automação define vários "blocos" ou estruturas de dados padrão, chamados de Structs.
Confira a estrutura automation, que define quatro campos:
| Key | Tipo | Descrição |
|---|---|---|
|
|
Opcional. Nome da automação. Isso não é mostrado aos usuários, é apenas para referência do desenvolvedor. |
|
|
|
[Starter] |
Obrigatório. Uma lista de iniciantes. |
|
|
Opcional. Condição. |
|
|
|
[Ação] |
Obrigatório. Uma lista de ações. |
A seção Referência fornece definições de esquema para todos os Structs disponíveis.
Os nomes das chaves são exclusivos em um determinado Struct e diferenciam maiúsculas de minúsculas.
Os tipos de valor possíveis são:
- Um tipo primitivo: booleano, número, string, tempo e assim por diante.
- Um tipo de struct: uma coleção de campos.
- Uma matriz do tipo de dados. A matriz é indicada por
[]. Por exemplo,[string]é uma matriz de strings, e[Starter]é uma matriz de estruturas Starter. - Outros tipos especiais: entidade, FieldPath.
A descrição de cada campo contém informações importantes, incluindo:
- Obrigatório ou opcional, indicando se o campo é obrigatório ou se pode ser ignorado.
- Dependência de campo. Somente os campos opcionais têm dependências. Isso descreve as verificações adicionais ao usar esse campo, como Usar o campo B somente se o campo A estiver definido ou Quando o campo A for usado, não defina o campo B ou C.
- Valores possíveis. Por exemplo, o conjunto de valores limitado de um campo enum de tipo string ou um intervalo de números que pode ser usado em um campo de tipo número.
Struct com tipo especificado
Alguns Structs podem representar ativações com base em uma programação ou em uma mudança de estado
do dispositivo. Cada tipo de starter precisa fornecer um conjunto distinto de campos.
# 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
Um starter é um struct tipificado, que é estendido por outros structs filhos no
campo type, como time.schedule ou device.state.OnOff, para fornecer
funções diferentes. Os structs condition e action também são tipados.
Campos adicionais na estrutura precisam seguir a especificação da estrutura filha (type). Por exemplo, ao usar device.state.OnOff como type, apenas
os
campos especificados para esse
tipo
são válidos nessa
estrutura starter.
Matriz
Em YAML, uma matriz de valores começa com - (um traço seguido por um espaço). A
matriz pode conter vários valores de Struct ou vários valores primitivos. No entanto, os
valores na matriz precisam ser do mesmo tipo.
Quando a matriz contém um único item, é possível omitir o traço e o espaço:
# 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
Matrizes multidimensionais, como
[[1, 2], [3, 4]], não são compatíveis com o script de automação. O
analisador de linguagem vai achatar automaticamente uma matriz multidimensional em uma
matriz de uma única dimensão, neste caso, [1, 2, 3, 4].
# INVALID: multi-dimensional array
- - 1
- 2
- - 3
- 4
Primário
Os seguintes tipos de dados primitivos são compatíveis com o esquema de script Automations:
|
Booleano |
|
|
Número |
Número inteiro ou decimal |
|
String |
Texto simples As strings não precisam ser citadas, exceto em casos específicos. |
|
Data |
Mês e dia. O formato é MM-DD ou MM/DD.
|
|
Tempo |
Hora do dia. Pode ser o horário do relógio ou solar.
Para o horário, é possível usar o formato AM/PM ou 24H. Os segundos
são opcionais.
Para o horário solar,
|
|
DateTime |
É o ano, o mês, o dia e a hora. É necessário um espaço em branco entre a parte de data e a parte de hora. O formato da data é AAAA-MM-DD ou AAAA/MM/DD. O formato de hora é o mesmo que [Hora](#time). Não há suporte para fusos horários.
|
|
Dia da semana |
|
|
Duração |
Um período de tempo.
|
| ColorHex |
Um código hexadecimal de seis dígitos que representa uma cor. Não há
|
| Temperatura | Dados de temperatura normal. Sempre adicione
|
| ColorTemperature |
Temperatura da cor em Kelvin.
|
Cor
As cores podem ser especificadas de três maneiras: usando os tipos primitivos ColorHex ou ColorTemperature, ou o tipo composto SpectrumHSV.
SpectrumHSV
O tipo SpectrumHSV especifica uma cor usando três campos numéricos:
- Hue corresponde à frequência de cor.
- A saturação indica a intensidade da cor.
- Valor indica a luminosidade ou escuridão relativa da cor.
Dinâmico
Às vezes, o tipo de dados de uma chave não é fixo. Ele pode ser um dos tipos primitivos, com base nos valores de outros campos.
Um exemplo de campo de tipo de dados dinâmico é is. O tipo real é
determinado pelos valores dos campos 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
Entidade
Um formato de string especial para identificar exclusivamente uma entidade pertencente ao usuário, como um dispositivo ou sala.
O dispositivo é a entidade mais comum usada nas automações. O formato de string de entidade
é 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
Um formato de string especial usado para localizar um dado em um payload de dados. No
exemplo abaixo, currentVolume é o FieldPath do campo state.
# The state field accepts a FieldPath type.
starters:
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 5
Outros FieldPaths podem exigir vários níveis para chegar ao item necessário, e o formato varia entre o starter e a ação.
Os iniciantes usam uma notação de ponto, com o caminho inteiro no mesmo campo. Isso é
feito principalmente para fins de comparação na lógica de inicialização. Por exemplo, para usar
a temperatura da cor como ponto de partida, use color.colorTemperature para o
estado:
starters:
- type: device.state.ColorSetting
device: My Device - Room Name
state: color.colorTemperature
is: 2000K
No entanto, as ações usam campos aninhados. Para mudar a cor de uma lâmpada para azul,
em vez de color.name e is: blue, faça o seguinte:
actions:
- type: device.command.ColorAbsolute
devices: My Device - Room Name
color:
name: blue