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 temsil etmenizi sağlar. İlk komut dosyası otomasyonunuzu oluşturmadan önce YAML hakkında bilmeniz gereken bazı temel bilgiler aşağıda verilmiştir. YAML hakkında genel olarak 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'tır. Anahtar ve değer, iki nokta ve ardından boşluk ile ayrılır. Düzgün biçimlendirilmiş YAML için her iki karakter de gereklidir.

name: TV on lights off

Değerler

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

Dize

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

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

Doğru alıntılama:

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.

Birden çok satırlık bir dize gerekiyorsa çoklu satırlık 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 çiftinin (name ve description) listesidir:

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 girintilendirilmiştir (iki boşluk).

YAML'de girinti katı kurallara tabidir. Alt yapının girintisi, üst yapınınkinden daha derin olmalıdır ve aynı düzeydeki anahtar/değer çiftlerinin girintisi aynı 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 kısa çizgi 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ı kısa çizgi ve boşlukla başlar.
  2. weekday birden fazla değere sahip olabilir. Bu nedenle, her değer daha fazla girinti alır ve kısa çizgi ve boşluk ile başlar.
starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

Yorumlar

#'den sonra gelen tüm 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 # önce bir boşluk olmalıdır.

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

Otomasyon komut dosyası

Otomasyonlar komut dosyası söz dizimine ilişkin spesifikasyona şema denir.

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

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

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'e göz atın:

Anahtar Tür Açıklama

name

Dize

İsteğe bağlı.

Otomasyonun adı.

Bu, yalnızca geliştirici referansı içindir ve kullanıcılara gösterilmez.

starters

[Starter]

Zorunlu.

Başlatıcıların listesi.

condition

Durum

İsteğe bağlı.

Durum.

actions

[İşlem]

Zorunlu.

İşlemlerin listesi.

Referans bölümü, mevcut tüm Yapılar için şema tanımları sağlar.

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

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

  • Basit tür: boole, sayı, dize, zaman vb.
  • Struct türü: bir alan koleksiyonu.
  • Veri türünün bir dizisi. Dizi [] ile gösterilir. Örneğin, [string] bir dize dizisi, [Starter] ise Başlatıcı Yapı dizisidir.
  • Diğer özel türler: Entity, FieldPath.

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

  • Zorunlu veya İsteğe bağlı: Alanın zorunlu olup olmadığını ya da atlanıp atlanamayacağını belirtir.
  • Alan Bağımlılığı. Yalnızca isteğe bağlı alanların bağımlılıkları vardır. Bu alanda, B alanını yalnızca A alanı ayarlandığında kullan veya A alanı kullanıldığında B veya C alanını ayarlamayın gibi bu alan kullanılırken yapılan ek kontroller açıklanır.
  • Olası değerler. Örneğin, dize türüne sahip bir Enum alanının sınırlı değer kümesi veya sayı türüne sahip bir alanda kullanılabilecek bir sayı aralığı.

Yazılı Yapı

Bazı yapılandırmalar, zaman planlamasına veya cihaz durumu değişikliğine dayalı 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 yapıların (ör. time.schedule veya device.state.OnOff) genişlettiği bir Typed Struct'tir. condition ve action yapıları da türü belirtilmiş olmalıdır.

Yapıdaki ek alanlar, alt yapı (type) spesifikasyonuna uymalıdır. Örneğin, type olarak device.state.OnOff kullanıldığında, söz konusu starter Yapı'da yalnızcabu tür için belirtilen alanlar geçerli olur.

Dizi

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

Dizi tek bir öğe içeriyorsa kısa çizgiyi 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 durumda [1, 2, 3, 4]) düzleştirir.

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

Primitive

Otomasyonlar komut dosyası şeması aşağıdaki ilkel veri türlerini destekler:

Bool
  • true
  • false

Sayı

Tam sayı veya ondalık sayı

Dize

Düz metin

Belirli durumlar dışında dizelerin tırnak içine alınmasına gerek yoktur.

Tarih

Ay ve gün. Biçim AA-GG veya AA/GG şeklindedir.

  • 09/01
  • 09-01

Saat

Günün saati. Saat veya güneş zamanı olabilir. Saat için AM/PM biçimi veya 24 saatlik biçim kullanılabilir. Saniyeler isteğe bağlıdır. Güneş zamanı için sunrise ve sunset anahtar kelimelerdir ve bunların ardından bir ofset (Süre terimlerinde) gelebilir.

  • 12:30 am
  • 13:00:01
  • sunrise/sunset
  • sunset+30min/sunset-1hour

Tarih ve saat

Yıl, ay, gün ve günün saati. Tarih bölümü ile saat bölümü arasında boşluk olmalıdır. Tarih biçimi YYYY-AA-GG veya YYYY/AA/GG şeklindedir. Saat biçimi, [Saat](#time) ile aynıdır. Saat dilimi desteklenmez.

  • 2022/01/01 14:00
  • 2022-12-31 sunrise+30min

Hafta içi

  • MONDAY (veya MON)
  • TUESDAY (veya TUE)
  • WEDNESDAY (veya WED)
  • THURSDAY (veya THU)
  • FRIDAY (veya FRI)
  • SATURDAY (veya SAT)
  • SUNDAY (veya SUN)

Süre

Bir zaman aralığı.

  • 30min
  • 1hour
  • 20sec
  • 1hour10min20sec
ColorHex

Bir rengi temsil eden altı haneli on altılık kod.

Başında # yok.

  • FFFFFF
  • B5D2A1
  • DFA100
Sıcaklık

Normal sıcaklık verileri. Sıcaklık ölçümünü belirtmek için değere her zaman 'C' veya 'F' ekleyin.

  • 20.5C
  • 90F
ColorTemperature

Kelvin cinsinden renk sıcaklığı.

  • 5000K

Renk

Renkler, ColorHex veya ColorTemperature ilkel türleri ya da SpectrumHSV birleşik türü kullanılarak üç şekilde belirtilebilir.

SpectrumHSV

SpectrumHSV türü, üç sayısal alan kullanarak bir rengi 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 değildir. Diğer alanlardaki değerlere bağlı olarak ilkel 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 öğ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 dize biçimi device name - room name'tür.

# 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 değeridir.

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

Diğer FieldPaths'lerin, gerekli öğeye ulaşmak için birden fazla düzeye ihtiyacı olabilir ve başlatıcı ile işlem arasında biçim farklıdır.

Başlatıcılar, yolun tamamının aynı alanda olduğu bir nokta notasyonu kullanır. Bu, öncelikle başlatıcı 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 mavi yapmak 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