Dasar-Dasar Bahasa

Memahami YAML

YAML adalah bahasa populer yang digunakan untuk menentukan konfigurasi software. Dokumentasi memberikan cara yang jelas dan dapat dibaca manusia untuk merepresentasikan informasi terstruktur. Berikut adalah beberapa hal dasar yang perlu Anda pahami tentang YAML sebelum membuat otomatisasi dengan skrip pertama Anda. Untuk mempelajari YAML secara umum lebih lanjut, lihat spesifikasi Versi 1.1.

Key-value pair

Dokumen YAML pada dasarnya merupakan kumpulan pasangan nilai kunci. Dalam contoh berikut, kuncinya adalah name dan nilainya adalah TV on lights off. Kunci dan nilai dipisahkan dengan titik dua, diikuti spasi. Kedua karakter tersebut diperlukan untuk YAML yang tersusun dengan baik.

name: TV on lights off

Nilai

Nilai yang terkait dengan kunci dapat sedasar seperti string, angka, atau tanggal, atau serumit kumpulan pasangan nilai kunci lainnya.

String

Jika nilai string dimulai dengan salah satu karakter berikut: [, {, ", ', atau #, atau string berisi : (titik dua diikuti spasi), nilai tersebut harus dikutip.

Tanda kutip tunggal dan ganda diterima, tetapi tanda kutip penutup harus cocok dengan tanda kutip pembuka.

Kutipan yang benar:

name: 'TV on lights off'

name: "TV on lights off"

Kutipan salah (kutipan yang tidak cocok):

name: 'TV on lights off"

Kutipan bersifat opsional untuk semua jenis string lainnya.

Jika Anda memerlukan string multibaris, lihat bagian spesifikasi YAML tentang skalar multibaris.

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

Pasangan nilai kunci bertingkat

Berikut nilai kunci metadata adalah daftar dua pasangan nilai kunci (name dan description):

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

Indentasi

YAML menggunakan indentasi untuk menunjukkan struktur. Pada contoh sebelumnya, name dan description diindentasi (oleh dua spasi) untuk menunjukkan bahwa kedua spasi tersebut adalah turunan dari kunci metadata.

Indentasi bersifat ketat dalam YAML. Struktur turunan harus memiliki indentasi yang lebih dalam daripada induknya, dan key-value pair level yang sama harus memiliki indentasi yang sama.

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

Banyak nilai

Jika kunci tertentu memiliki beberapa nilai, setiap nilai akan dicantumkan dalam baris baru, dan setiap baris diawali dengan tanda hubung dan spasi. Dalam contoh berikut, ada dua daftar:

  1. Otomatisasi dapat memiliki beberapa starters sehingga pemicu pertama dimulai dengan tanda hubung dan spasi.
  2. weekday dapat memiliki beberapa nilai, sehingga setiap nilai diindentasi lebih lanjut dan dimulai dengan tanda hubung dan spasi.
starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

Komentar

Setiap teks setelah # dianggap sebagai komentar dan diabaikan oleh mesin otomatisasi.

Baris yang dimulai dengan # adalah komentar.

Komentar dapat muncul di baris yang sama dengan konten skrip, tetapi # harus diawali dengan spasi.

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

Skrip otomatisasi

Spesifikasi untuk sintaksis skrip Otomatisasi disebut skema.

Skema Otomatisasi menentukan beberapa struktur data:

  • Satu pasangan nilai kunci disebut Kolom.
  • Kumpulan kolom yang ditentukan oleh skema disebut Struct.

Struct

Bahasa skrip otomatisasi menentukan beberapa 'blok' atau struktur data standar, yang disebut sebagai Structs.

Lihat Struct automation, yang menentukan empat kolom:

Key Type Deskripsi

name

String

Opsional.

Nama otomatisasi.

Nama ini tidak ditampilkan kepada pengguna, hanya untuk referensi developer.

starters

[Pemicu]

Wajib.

Daftar pemicu.

condition

Kondisi

Opsional.

{i>Condition<i}.

actions

[Tindakan]

Wajib.

Daftar tindakan.

Bagian Reference memberikan definisi skema untuk semua Struct yang tersedia.

Nama kunci bersifat unik dalam Struct tertentu dan peka huruf besar/kecil.

Jenis nilai yang memungkinkan adalah:

  • Jenis primitif: bool, angka, string, waktu, dan sebagainya.
  • Jenis Struct: kumpulan kolom.
  • Array jenis data. Array dilambangkan dengan []. Misalnya, [string] adalah array string, dan [Starter] adalah array Struct Pemula.
  • Jenis khusus lainnya: Entity, FieldPath.

Deskripsi setiap Kolom berisi informasi penting, termasuk:

  • Wajib versus Opsional, yang menunjukkan apakah kolom bersifat wajib atau dapat dilewati.
  • Dependensi Kolom. Hanya Kolom Opsional yang memiliki Dependensi. Kolom ini menjelaskan pemeriksaan tambahan saat menggunakan kolom ini, seperti Gunakan Kolom B hanya jika Kolom A ditetapkan, atau Saat Kolom A digunakan, jangan tetapkan Kolom B atau Kolom C.
  • Kemungkinan Nilai. Misalnya, kumpulan nilai terbatas untuk Kolom Enum dari jenis string, atau rentang angka yang dapat digunakan di Kolom jenis angka.

Struct Berjenis

Beberapa Struct dapat merepresentasikan pemicu berdasarkan jadwal waktu atau perubahan status perangkat. Setiap jenis starter harus menyediakan kumpulan Kolom yang berbeda.

# 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 adalah Struct Berjenis, yang diperluas oleh Struct turunan lainnya di Kolom type, seperti time.schedule atau device.state.OnOff, untuk menyediakan fungsi yang berbeda. Struct condition dan action juga Berjenis.

Kolom tambahan di Struct harus mengikuti spesifikasi Struct turunan (type). Misalnya, saat menggunakan device.state.OnOff sebagai type, hanya kolom kolom yang ditentukan untuk jenis tersebut yang valid di Strruct starter tersebut.

Array

Dalam YAML, array nilai dimulai dengan - (tanda hubung diikuti dengan spasi). Array dapat berisi beberapa nilai Struct, atau beberapa nilai Primitif. Namun, nilai dalam array harus memiliki jenis yang sama.

Jika array berisi satu item, Anda dapat menghilangkan tanda hubung dan spasi:

# 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

Array multidimensi, seperti [[1, 2], [3, 4]], tidak didukung dalam pembuatan skrip otomatisasi. Parser bahasa akan otomatis meratakan array multidimensi menjadi array satu dimensi, dalam hal ini [1, 2, 3, 4].

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

Primitif

Jenis data primitif berikut didukung oleh skema skrip Otomatisasi:

Bool
  • true
  • false

Angka

Bilangan bulat atau desimal

String

Teks biasa

String tidak perlu diberi tanda kutip, kecuali dalam kasus tertentu.

Tanggal

Bulan dan Hari. Formatnya adalah BB-HH atau BB/HH.

  • 09/01
  • 09-01

Waktu

Waktu. Waktu ini bisa berupa waktu jam atau waktu matahari. Untuk waktu jam, fungsi ini dapat menggunakan format AM/PM atau format 24 jam. Detik bersifat opsional. Untuk waktu matahari, sunrise dan sunset adalah kata kunci, dan dapat diikuti oleh offset (dalam istilah Durasi).

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

DateTime

Tahun, Bulan, Hari, dan Waktu. Spasi kosong diperlukan antara bagian Tanggal dan bagian Waktu. Format tanggalnya adalah TTTT-BB-HH atau TTTT/BB/HH. Format waktu sama dengan [Time](#time). Zona waktu tidak didukung.

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

Hari Kerja

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

Durasi

Periode waktu.

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

Kode heksadesimal enam digit yang merepresentasikan warna.

Tidak ada # awal.

  • FFFFFF
  • B5D2A1
  • DFA100
Temperature (suhu)

Data suhu normal. Selalu tambahkan 'C' atau 'F' ke nilai untuk menunjukkan pengukuran suhu.

  • 20.5C
  • 90F
ColorTemperature

Suhu warna dalam Kelvin.

  • 5000K

Warna

Warna dapat ditentukan dengan salah satu dari tiga cara - menggunakan jenis primitif ColorHex atau ColorTemperature, atau jenis senyawa SpectrumHSV.

SpectrumHSV

Jenis SpectrumHSV menentukan warna menggunakan tiga kolom numerik:

  • Hue sesuai dengan panjang gelombang warna.
  • Saturasi menunjukkan intensitas warna.
  • Nilai menunjukkan terang atau gelapnya warna relatif.

Dinamis

Terkadang, jenis data kunci tidak tetap. Jenis data ini dapat berupa salah satu jenis primitif, berdasarkan nilai dari kolom lain.

Contoh kolom jenis data dinamis adalah is. Jenis sebenarnya ditentukan oleh nilai kolom type dan 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

Entity

Format String khusus untuk mengidentifikasi entity milik pengguna secara unik, seperti perangkat atau ruangan.

Perangkat adalah entitas yang paling umum digunakan dalam Otomatisasi. Format String entity adalah 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

Sebuah format {i>String<i} khusus yang digunakan untuk menemukan bagian data dalam {i>payload<i} data. Dalam contoh berikut, currentVolume adalah FieldPath untuk kolom state.

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

FieldPath lain mungkin memerlukan beberapa level untuk mencapai item yang diperlukan, dan formatnya berbeda antara pemicu dan tindakan.

Pemicu menggunakan notasi titik, dengan seluruh jalur berada dalam kolom yang sama. Hal ini terutama dilakukan untuk tujuan perbandingan dalam logika awal. Misalnya, untuk menggunakan suhu warna sebagai pemicu, Anda akan menggunakan color.colorTemperature untuk status:

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

Namun, tindakan menggunakan kolom bertingkat. Untuk mengubah warna bohlam menjadi biru, bukan color.name dan is: blue, Anda harus melakukan:

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