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 açık ve okunabilir bir şekilde temsil etmenizi sağlar. İlk komut dosyası oluşturma otomasyonunuzu oluşturmadan önce YAML hakkında anlamanız gereken birkaç temel nokta aşağıda verilmiştir. YAML hakkında daha fazla bilgi edinmek için 1.1 sürümü spesifikasyonuna bakın.

Anahtar/değer çiftleri

YAML belgeleri temel olarak anahtar/değer çiftleri koleksiyonudur. Aşağıdaki örnekte anahtar name, değer ise TV on lights off'dir. Anahtar ve değer, iki nokta üst üste 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 kadar basit ya da başka bir anahtar/değer çifti koleksiyonu kadar karmaşık olabilir.

Yaylı çalgılar

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

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

Doğru alıntı:

name: 'TV on lights off'

name: "TV on lights off"

Yanlış alıntı (eşleşmeyen alıntılar):

name: 'TV on lights off"

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

Çok satırlı bir dizeye ihtiyacınız varsa çok satırlı skalerlerle ilgili YAML spesifikasyon 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 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 girintilemeyi kullanır. Önceki örnekte, name ve description, metadata anahtarının alt öğeleri olduğunu belirtmek için girintilidir (iki boşluk).

YAML'de girintileme katıdır. Alt yapı, üst yapısından daha fazla girintiye sahip olmalıdır 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ın başında tire ile boşluk bulunur. 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 da girintili hale getirilir ve tire ile boşlukla başlar.

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

Yorumlar

# işaretinden sonraki tüm metinler yorum olarak kabul edilir ve otomasyon motoru tarafından yoksayılır.

# ile başlayan satırlar yorumdur.

Yorumlar, senaryo içeriğiyle aynı satırda görünebilir ancak # karakterinden önce 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 diziminin spesifikasyonuna şema adı verilir.

Otomasyonlar şeması, birkaç veri yapısı tanımlar:

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

Struct

Otomasyon komut dosyası dili, Structs olarak adlandırılan çeşitli standart "bloklar" veya veri yapıları 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, number, string, time vb.
• Yapı türü: alan koleksiyonu.
• Veri türünün dizisi. Dizi, [] ile gösterilir. Örneğin, [string] bir dize dizisidir ve [Starter] bir başlangıç yapısı dizisidir.
• Diğer özel türler: Entity, FieldPath.

Her alanın açıklaması aşağıdaki gibi önemli bilgiler içerir:

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

Yazılmış Yapı

Bazı Struct'lar, zaman çizelgesine veya cihaz durumundaki değişikliğe göre başlangıç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 yapısal öğeler (ör. time.schedule veya device.state.OnOff) tarafından genişletilen bir Türlü Yapı'dır. condition ve action yapıları da türlenmiştir.

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

Dizi

YAML'de 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

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

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

Primitive

Otomasyon komut dosyası şeması aşağıdaki temel veri türlerini destekler:

Renk

Renkler üç şekilde belirtilebilir: ColorHex veya ColorTemperature temel türleri ya da SpectrumHSV bileşik türü kullanılarak.

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öreli açıklığını veya koyuluğunu gösterir.

Dinamik

Bazen bir anahtarın veri türü sabit değildir. 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ğerleriyle 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 öğeyi (ö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 dizesi biçimi 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

Bir veri yükündeki 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ıç noktaları, aynı alanda tüm yolla birlikte nokta notasyonu kullanır. Bu işlem, öncelikle başlatıcı mantığında karşılaştırma amacıyla yapılır. Örneğin, başlangıç olarak renk sıcaklığını kullanmak için durum için color.colorTemperature simgesini 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 çevirmek 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