Noções básicas de idiomas

Entender o YAML

YAML é uma linguagem popular usada para especificar a configuração de software. Ele oferece uma maneira clara e legível de representar informações estruturadas. Confira alguns conceitos básicos sobre YAML antes de criar sua primeira automação usando scripts. 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 por um espaço. Os dois caracteres são obrigatórios para um 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 por espaços), ela precisará ser colocada entre aspas.

Aspas simples e duplas são aceitas, mas as aspas de fechamento precisam corresponder às de 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 da especificação 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 indicar a estrutura. No exemplo anterior, name e description são recuados (em dois espaços) para indicar que são filhos da chave metadata.

O recuo é estrito em YAML. Uma estrutura filha precisa ter um recuo maior que o da mãe, e pares de 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 um deles será listado em uma nova linha, e cada linha começará com um traço e um espaço. No exemplo a seguir, há duas listas:

1. Uma automação pode ter vários starters, e por isso a primeira ativação começa com um traço e um espaço.
2. weekday pode ter vários valores. Por isso, cada valor é mais indentado 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 de script das automações é chamada de esquema.

O esquema de automações define algumas estruturas de dados:

• Um único par chave-valor é chamado de campo.
• Uma coleção de campos definidos pelo esquema é chamada de struct.

Struct

A linguagem de programação de automação define vários "blocos" ou estruturas de dados padrão, chamados de estruturas.

Confira a estrutura automation, que define quatro campos:

A seção Referência fornece definições de esquema para todas as structs disponíveis.

Os nomes das chaves são exclusivos em uma determinada estrutura e diferenciam maiúsculas de minúsculas.

Os tipos de valores possíveis são:

• Um tipo primitivo: bool, número, string, tempo e assim por diante.
• Um tipo de estrutura: 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 de inicialização.
• Outros tipos especiais: Entity, 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 campos opcionais têm dependências. Isso descreve as verificações adicionais ao usar esse campo, como Use o campo B somente se o campo A estiver definido ou Quando o campo A for usado, não defina o campo B ou o campo C.
• Valores possíveis. Por exemplo, o conjunto de valores limitados de um campo de enumeração do tipo string ou um intervalo de números que podem ser usados em um campo do tipo número.

Struct com tipo especificado

Algumas 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 é uma estrutura tipada, que é estendida por outras estruturas filhas no campo type, como time.schedule ou device.state.OnOff, para fornecer funções diferentes. As structs condition e action também são tipadas.

Outros campos na estrutura precisam seguir a especificação da estrutura secundária (type). Por exemplo, ao usar device.state.OnOff como type, apenas os camposespecificados 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. mas 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 scripts de automação. O analisador de linguagem vai achatar automaticamente uma matriz multidimensional em uma matriz unidimensional, nesse 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 de automações:

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:

• Matiz corresponde ao comprimento de onda da cor.
• Saturação indica a intensidade da cor.
• Valor indica a claridade 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 de forma exclusiva uma entidade de propriedade do usuário, como um dispositivo ou uma sala.

Dispositivo é a entidade mais comum usada em automações. O formato da string da 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 uma carga útil de dados. No exemplo a seguir, 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 difere entre o inicializador e a ação.

Os iniciadores usam uma notação de ponto, com todo o caminho no mesmo campo. Isso é feito principalmente para fins de comparação na lógica inicial. 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