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 temsil etmek için net ve okunabilir bir yol sağlar. İlk senaryolu otomasyonunuzu oluşturmadan önce YAML hakkında bilmeniz gereken birkaç temel bilgiyi burada bulabilirsiniz. YAML hakkında genel olarak daha fazla bilgi edinmek için Sürüm 1.1 spesifikasyonuna bakın.

Anahtar/değer çiftleri

YAML belgeleri temelde anahtar/değer çiftlerinin bir koleksiyonudur. Aşağıdaki örnekte anahtar name, değer ise TV on lights off'dir. 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şkilendirilen değer dize, sayı veya tarih kadar temel ya da başka bir anahtar/değer çifti koleksiyonu kadar karmaşık olabilir.

Dize

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

Hem tek hem de çift tırnak işareti kabul edilir ancak kapanış tırnak işareti açılış teklifiyle eşleşmelidir.

Doğru alıntı:

name: 'TV on lights off'

name: "TV on lights off"

Yanlış alıntı (yanlış alıntılar):

name: 'TV on lights off"

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

Çok satırlı bir dizeye ihtiyacınız varsa çok satırlı skalerler ile ilgili YAML spesifikasyonu bölümünü inceleyin.

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 çiftinin (name ve description) bir listesidir:

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

Girinti

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

YAML'de girinti katıdır. Bir alt yapı, üst yapısına göre daha derin girintiye sahip 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, kısa çizgi ve boşlukla başlar. Aşağıdaki örnekte iki liste vardır:

  1. Otomasyonda birden fazla starters olabilir. Bu nedenle ilk başlatıcı bir kısa çizgi ve boşlukla başlar.
  2. weekday birden fazla değere sahip olabilir. Bu nedenle, her değerin girintisi daha fazladır ve tire ve boşlukla başlar.
starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

Yorum sayısı

# ifadesinden sonra gelen tüm metinler yorum olarak kabul edilir ve otomasyon motoru tarafından yoksayılır.

# ile başlayan satır bir yorumdur.

Yorum, komut dosyası içeriğiyle aynı satırda görünebilir ancak # öğesinin önünde 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 diziminin spesifikasyonuna şema adı verilir.

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

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

Struct

Otomasyon komut dosyası dili, Structs olarak adlandırılan çeşitli standart "bloklar" veya veri yapısı tanımlar.

Dört alanı tanımlayan automation yapısına göz atın:

Anahtar Tür Açıklama

name

Dize

İsteğe bağlı.

Otomasyonun adı.

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

starters

[Başlangıç]

Zorunlu.

Başlatıcı listesi.

condition

Durum

İsteğe bağlı.

Koşul.

actions

[İşlem]

Zorunlu.

İşlemlerin listesi.

Referans bölümünde mevcut tüm yapılar için şema tanımları yer alır.

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:

  • Temel bir tür: bool, sayı, dize, zaman vb.
  • Yapı türü: Alan koleksiyonu.
  • Veri türü dizisi. Dizi, [] ile gösterilir. Örneğin, [string] bir dize dizisi, [Starter] ise Başlangıç Yapıları dizisidir.
  • Diğer özel türler: Varlık, Alan Yolu.

Her Alanın açıklaması, aşağıdakileri de içeren önemli bilgiler içerir:

  • Zorunlu ve İsteğe Bağlı. Bu seçim, alanın zorunlu olup olmadığını veya atlanıp atılamayacağını belirtir.
  • Alan Bağımlılığı. Yalnızca İsteğe Bağlı Alanlarda Bağımlılıklar bulunur. Bu, bu alan kullanılırken Yalnızca A Alanı ayarlıysa B Alanını kullan veya A Alanı kullanılıyorsa B Alanı veya C Alanını ayarlamayın gibi ek kontroller açıklanmaktadır.
  • Olası Değerler. Örneğin, bir Enum Alanı türündeki dizenin sınırlı değer kümesi veya bir tür numarası alanında kullanılabilecek bir sayı aralığı.

Yazılı Yapı

Bazı Yapılar, başlatıcıları bir zaman çizelgesine veya cihaz durumu değişikliğine göre temsil edebilir. Her starter türü, ayrı 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 sunmak için type alanındaki time.schedule veya device.state.OnOff gibi diğer alt yapılar tarafından genişletilen bir tür yapıdır. condition ve action Yapıları da Yazılır.

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

Dizi

YAML'de bir değer dizisi, - (kısa çizgi ve ardından bir boşluk) ile başlar. Dizide birden fazla Struct değeri veya birden fazla Temel değer bulunabilir. Ancak dizideki değerler aynı türde olmalıdır.

Dizi tek bir öğe içerdiğinde tireyi ve boşluğu çıkarabilirsiniz:

# 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 dosyası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

Otomasyon komut dosyası şeması, aşağıdaki temel 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 saati veya güneş saati olabilir. Saat saati için, ÖÖ/ÖS biçimini veya 24H biçimini kullanabilirsiniz. Saniyeler isteğe bağlıdır. Güneş zamanı için sunrise ve sunset anahtar kelimelerdir ve ardından bir ofset gelebilir (Süre terimleriyle).

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

DateTime

Günün Yıl, Ay, Gün ve Saati. Tarih kısmı ile Saat bölümü arasında boşluk olması gerekir. Tarih biçimi YYYY-AA-GG veya YYYY/AA/GG şeklindedir. Saat biçimi, [Saat](#time) ile aynıdır. Saat dilimi desteklenmiyor.

  • 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 süre.

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

Bir rengi temsil eden altı basamaklı onaltılık kod.

Başta # yok.

  • FFFFFF
  • B5D2A1
  • DFA100
Sıcaklık

Normal sıcaklık verisi. 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 şu üç yoldan biriyle belirtilebilir: ColorHex veya ColorTemperature temel türü veya SpectrumHSV bileşik türü.

SpectrumHSV

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

  • Ton, rengin 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 alanlardan gelen değerlere dayalı olarak temel türlerden biri olabilir.

Dinamik veri türü alanına örnek olarak is verilebilir. Gerçek tür, type ve 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 Dize biçimi.

Cihaz, otomasyonlarda en sık kullanılan varlıktır. Varlık Dizesi 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ı için FieldPath'dir.

# 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 çok düzey gerektirebilir ve biçim, başlatıcı ile işlem arasında farklılık gösterir.

Başlatıcılar, yolun tamamı aynı alanda olacak şekilde nokta gösterimi kullanır. Bu işlem öncelikle başlangıç mantığında karşılaştırma amacıyla yapılır. Örneğin, renk sıcaklığını başlatıcı olarak 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 geçmiş alanları kullanır. Bir ampulün rengini color.name ve is: blue yerine mavi yapmak için şunları yapmanız gerekir:

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