Dasar-Dasar Bahasa

Memahami YAML

YAML adalah bahasa populer yang digunakan untuk menentukan konfigurasi software. Cara ini memberikan cara yang jelas dan mudah dibaca untuk merepresentasikan informasi terstruktur. Berikut beberapa hal dasar yang perlu Anda pahami tentang YAML sebelum membuat otomatisasi dengan skrip pertama Anda. Untuk mempelajari YAML secara umum, 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 dibatasi oleh titik dua yang 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), string tersebut harus diapit 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 (tanda kutip tidak cocok):

name: 'TV on lights off"

Tanda petik bersifat opsional untuk semua jenis string lainnya.

Jika Anda memerlukan string multi-baris, lihat bagian spesifikasi YAML tentang skalar multi-baris.

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 key-value pair (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 (dua spasi) untuk menunjukkan bahwa keduanya adalah turunan dari kunci metadata.

Indentasi sangat ketat di YAML. Struktur turunan harus memiliki indentasi yang lebih dalam daripada 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 dicantumkan di 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 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 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 Struct.

Lihat Struct automation, yang menentukan empat kolom:

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 mungkin 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 Starter Struct.
• Jenis khusus lainnya: Entity, FieldPath.

Deskripsi setiap Kolom berisi informasi penting, termasuk:

• Wajib versus Opsional, menunjukkan apakah kolom wajib diisi atau dapat dilewati.
• Dependensi Kolom. Hanya Kolom Opsional yang memiliki Dependensi. Bagian ini menjelaskan pemeriksaan tambahan saat menggunakan kolom ini, seperti Gunakan Kolom B hanya jika Kolom A ditetapkan, atau Jika Kolom A digunakan, jangan tetapkan Kolom B atau Kolom C.
• Nilai yang Mungkin Muncul. Misalnya, kumpulan nilai terbatas dari Enum Field berjenis string, atau rentang angka yang dapat digunakan dalam Field berjenis angka.

Struct yang memiliki jenis

Beberapa Struct dapat merepresentasikan pemicu berdasarkan jadwal waktu atau perubahan status perangkat. Setiap jenis starter harus menyediakan serangkaian 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 yang Diketik, 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 diketik.

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

Di YAML, array nilai dimulai dengan - (tanda hubung diikuti dengan spasi). Array dapat menyimpan 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 berdimensi tunggal, 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:

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 terang atau gelapnya warna secara relatif.

Dinamis

Terkadang, jenis data kunci tidak tetap. Nilai 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 secara unik entitas milik pengguna 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

FieldPath lainnya mungkin memerlukan beberapa tingkat untuk mendapatkan item yang diperlukan, dan formatnya berbeda antara starter dan tindakan.

Starter menggunakan notasi titik, dengan seluruh jalur dalam kolom yang sama. Hal ini terutama dilakukan untuk tujuan perbandingan dalam logika awal. Misalnya, untuk menggunakan suhu warna sebagai permulaan, 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, alih-alih color.name dan is: blue, Anda harus melakukan:

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