Dasar-Dasar Bahasa

Memahami YAML

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

Key-value pair

Dokumen YAML pada dasarnya adalah 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 dengan spasi. Kedua karakter diperlukan untuk YAML yang terbentuk dengan baik.

name: TV on lights off

Nilai

Nilai yang terkait dengan kunci dapat sesederhana 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 disertai tanda kutip.

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 tidak cocok):

name: 'TV on lights off"

Tanda kutip 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

Di sini, 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 (dengan dua spasi) untuk menunjukkan bahwa keduanya adalah turunan kunci metadata.

Indentasi ketat di YAML. Struktur turunan harus memiliki indentasi yang lebih dalam dari induknya, dan pasangan nilai kunci tingkat 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 di baris baru dan setiap baris dimulai 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 akan lebih jauh diindentasi dan diawali dengan tanda hubung dan spasi.
starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

Komentar

Teks apa pun setelah # dianggap sebagai komentar dan diabaikan oleh mesin otomatisasi.

Baris yang diawali dengan # adalah komentar.

Komentar dapat muncul di baris yang sama dengan konten skrip, tetapi # harus diikuti 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' standar atau struktur data, yang disebut sebagai Structs.

Lihat Struct automation, yang menentukan empat kolom:

Key Jenis Deskripsi

name

String

Opsional.

Nama otomatisasi.

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

starters

[Starter]

Wajib.

Daftar pemicu.

condition

Kondisi

Opsional.

Kondisi.

actions

[Action]

Wajib.

Daftar tindakan.

Bagian Referensi memberikan definisi skema untuk semua Structs yang tersedia.

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

Jenis nilai yang mungkin adalah:

  • Jenis Primitive: 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 Starter Structs.
  • 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. 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.
  • Nilai yang Mungkin Muncul. Misalnya, kumpulan nilai terbatas dari Kolom Enum berjenis string, atau rentang angka yang dapat digunakan dalam Kolom berjenis angka.

Struct Berjenis

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

Kolom tambahan dalam 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 dalam Struct starter tersebut.

Array

Dalam YAML, array nilai dimulai dengan - (tanda hubung diikuti dengan spasi). Array ini dapat menyimpan beberapa nilai Struct, atau beberapa nilai Primitive. 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 diapit tanda petik kecuali dalam kasus tertentu.

Tanggal

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

  • 09/01
  • 09-01

Waktu

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

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

Tanggal dan Waktu

Tahun, Bulan, Hari, dan Waktu. Spasi kosong diperlukan di antara bagian Tanggal dan bagian Waktu. Format tanggalnya adalah YYYY-MM-DD atau YYYY/MM/DD. Format waktu sama dengan [Waktu](#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 # di awal.

  • FFFFFF
  • B5D2A1
  • DFA100
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 gabungan SpectrumHSV.

SpectrumHSV

Jenis SpectrumHSV menentukan warna menggunakan tiga kolom numerik:

  • Hue sesuai dengan panjang gelombang warna.
  • Saturasi menunjukkan intensitas warna.
  • Nilai menunjukkan kecerahan atau kegelapan warna secara relatif.

Dinamis

Terkadang, jenis data kunci tidak tetap. 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

Entitas

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

Perangkat adalah entitas paling umum yang 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

Format String khusus yang digunakan untuk menemukan bagian data dalam payload 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

FieldPaths lainnya mungkin memerlukan beberapa tingkat untuk membuka item yang diperlukan, dan formatnya berbeda antara pemicu dan tindakan.

Pemicu menggunakan notasi titik, dengan seluruh jalur di kolom yang sama. Hal ini utamanya 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