Dille İlgili Temel Bilgiler

YAML'yi anlama

YAML, yazılım yapılandırmasını belirtmek için kullanılan popüler bir dildir. Yapılandırılmış bilgileri net ve okunabilir bir şekilde sunar. İlk komut dosyası otomasyonunuzu oluşturmadan önce YAML hakkında bilmeniz gereken birkaç temel nokta vardır. Genel olarak YAML hakkında daha fazla bilgi edinmek için Sürüm 1.1 spesifikasyonuna bakın.

Anahtar/değer çiftleri

YAML dokümanları temel olarak anahtar/değer çiftlerinden oluşan bir koleksiyondur. Aşağıdaki örnekte anahtar name, değer ise TV on lights off şeklindedir. Anahtar ve değer, iki nokta ve ardından bir boşlukla ayrılır. İyi biçimlendirilmiş YAML için her iki karakter de gereklidir.

name: TV on lights off

Değerler

Bir anahtarla ilişkili değer; dize, sayı veya tarih gibi basit bir değer ya da başka bir anahtar/değer çifti koleksiyonu gibi karmaşık bir değer olabilir.

Dize

Bir dize değeri şu karakterlerden biriyle başlıyorsa: [, {, ", ' veya # ya da dize : (iki nokta üst üste ve ardından boşluklar) içeriyorsa tırnak içine alınmalıdır.

Hem tek hem de çift tırnak kabul edilir ancak kapatma tırnağı açma tırnağıyla eşleşmelidir.

Doğru alıntı yapma:

name: 'TV on lights off'

name: "TV on lights off"

Yanlış tırnak işareti kullanımı (eşleşmeyen tırnak işaretleri):

name: 'TV on lights off"

Diğer tüm dize türleri için tırnak işaretleri isteğe bağlıdır.

Çok satırlı bir dizeye ihtiyacınız varsa çok satırlı skalerlerle ilgili YAML spesifikasyonu bölümüne bakın.

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

İç içe yerleştirilmiş anahtar/değer çiftleri

Burada, metadata anahtarının değeri iki anahtar/değer çiftinden (name ve description) oluşan bir listedir:

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

Girinti

YAML, yapıyı belirtmek için girinti kullanır. Önceki örnekte, name ve description, metadata anahtarının alt öğeleri olduklarını belirtmek için girintili (iki boşluk) olarak gösterilmiştir.

YAML'de girinti kullanımı katı kurallara bağlıdır. Alt yapının girintisi üst yapının girintisinden daha derin olmalı ve aynı düzeydeki anahtar/değer çiftleri aynı girintiye sahip olmalıdır.

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

Birden çok değer

Belirli bir anahtarın birden fazla değeri varsa her değer yeni bir satırda listelenir ve her satır bir tire ve boşlukla başlar. Aşağıdaki örnekte iki liste vardır:

1. Bir otomasyonda birden fazla starters olabilir. Bu nedenle, ilk başlatıcı tire ve boşlukla başlar.
2. weekday birden fazla değere sahip olabilir. Bu nedenle, her değer daha fazla girintilidir ve bir tire ve boşlukla başlar.

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

Yorumlar

# işaretinden sonra gelen metinler yorum olarak kabul edilir ve otomasyon motoru tarafından yoksayılır.

# ile başlayan satırlar yorumdur.

Yorum, komut dosyası içeriğiyle aynı satırda görünebilir ancak # öncesinde bir boşluk olmalıdır.

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

Otomasyon komut dosyası

Otomasyon komut dosyası söz dizimi spesifikasyonuna şema denir.

Otomasyon şeması birkaç veri yapısı tanımlar:

• Tek bir anahtar/değer çiftine Alan adı verilir.
• Şema tarafından tanımlanan alan koleksiyonuna Struct adı verilir.

Struct

Otomasyon kodlama dili, Structs olarak adlandırılan birkaç standart "blok" veya veri yapısı tanımlar.

Dört alan tanımlayan automation Struct'a göz atın:

Referans bölümünde, mevcut tüm Struct'lar için şema tanımları sağlanır.

Anahtar adları, belirli bir Struct içinde benzersizdir ve büyük/küçük harfe duyarlıdır.

Olası değer türleri şunlardır:

• Temel tür: bool, sayı, dize, zaman vb.
• Struct türü: Alan koleksiyonu.
• Veri türünün dizisi. Dizi, [] ile gösterilir. Örneğin, [string] bir dize dizisidir ve [Starter], Starter Structs dizisidir.
• Diğer özel türler: Entity, FieldPath.

Her alanın açıklamasında aşağıdakiler gibi önemli bilgiler yer alır:

• Zorunlu veya İsteğe Bağlı: Alanın zorunlu olup olmadığını veya atlanıp atlanamayacağını gösterir.
• Alan Bağımlılığı. Yalnızca Seçenekler alanında bağımlılıklar vardır. Bu, bu alanı kullanırken yapılan ek kontrolleri açıklar. Örneğin, Yalnızca A Alanı ayarlanmışsa B Alanı'nı kullanın veya A Alanı kullanıldığında B Alanı'nı veya C Alanı'nı ayarlamayın.
• Olası değerler. Örneğin, dize türündeki bir Enum alanının sınırlı değer kümesi veya sayı türündeki bir alanda kullanılabilecek sayı aralığı.

Yazılan Struct

Bazı Struct'lar, zaman çizelgesine veya cihaz durumundaki değişikliğe göre başlatıcıları temsil edebilir. Her starter türü, farklı bir alan grubu sağlamalıdır.

# 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

starter, farklı işlevler sağlamak için type alanındaki diğer alt Struct'lar (ör. time.schedule veya device.state.OnOff) tarafından genişletilen bir Typed Struct'tır. condition ve action Struct'ları da türlendirilmiştir.

Yapı'daki ek alanlar, alt Yapı (type) spesifikasyonuna uygun olmalıdır. Örneğin, type olarak device.state.OnOff kullanıldığında yalnızcabu tür için belirtilen alanlar bu starter Struct'ta geçerlidir.

Dizi

YAML'de bir değer dizisi - (tire ve ardından boşluk) ile başlar. Dizi, birden fazla Struct değeri veya birden fazla Primitive değeri içerebilir. Ancak dizideki değerler aynı türde olmalıdır.

Dizi tek bir öğe içerdiğinde tire ve boşluğu atlayabilirsiniz:

# 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

[[1, 2], [3, 4]] gibi çok boyutlu diziler, otomasyon komut dosyalarında desteklenmez. Dil ayrıştırıcı, çok boyutlu bir diziyi otomatik olarak tek boyutlu bir diziye (bu örnekte [1, 2, 3, 4]) dönüştürür.

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

İlkel

Aşağıdaki temel veri türleri, otomasyon komut dosyası şeması tarafından desteklenir:

Renk

Renkler üç şekilde belirtilebilir: ColorHex veya ColorTemperature temel türlerini ya da bileşik tür SpectrumHSV'yi kullanarak.

SpectrumHSV

SpectrumHSV türü, üç sayısal alan kullanarak bir renk belirtir:

• Ton, renk dalga boyuna karşılık gelir.
• Doygunluk, rengin yoğunluğunu gösterir.
• Değer, rengin göreceli açıklığını veya koyuluğunu gösterir.

Dinamik

Bazen bir anahtarın veri türü sabit olmayabilir. Diğer alanlardaki değerlere bağlı olarak temel türlerden biri olabilir.

Dinamik veri türü alanına örnek olarak is verilebilir. Gerçek tür, hem type hem de state alanlarının değerlerine göre belirlenir.

# 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

Varlık

Kullanıcıya ait bir varlığı (ör. cihaz veya oda) benzersiz şekilde tanımlamak için kullanılan özel bir dize biçimi.

Cihaz, otomasyonlarda en sık kullanılan öğedir. Öğe dize biçimi device name - room name şeklindedir.

# The device field accepts a Device Entity type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1

FieldPath

Veri yükündeki bir veri parçasını bulmak için kullanılan özel bir dize biçimi. Aşağıdaki örnekte currentVolume, state alanının FieldPath'idir.

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

Diğer FieldPath'ler, gerekli öğeye ulaşmak için birden fazla seviye gerektirebilir ve biçim, başlatıcı ile işlem arasında farklılık gösterir.

Başlangıçlar, tüm yolun aynı alanda olduğu bir nokta gösterimi kullanır. Bu, öncelikle başlangıç mantığında karşılaştırma amacıyla yapılır. Örneğin, başlatıcı olarak renk sıcaklığını kullanmak için durum için color.colorTemperature değerini kullanırsınız:

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

Ancak işlemler, iç içe yerleştirilmiş alanlar kullanır. Bir ampulün rengini maviye değiştirmek için color.name ve is: blue yerine şunları yapmanız gerekir:

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