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 merepresentasikan informasi terstruktur. Berikut beberapa hal dasar yang perlu Anda pahami tentang YAML sebelum membuat otomatisasi dengan skrip pertama Anda. Untuk mempelajari lebih lanjut YAML secara umum, lihat Spesifikasi Versi 1.1.

Key-value pair

Dokumen YAML pada dasarnya adalah kumpulan key-value pair. 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 diawali dengan salah satu karakter berikut: [, {, ", ', atau #, atau string berisi : (titik dua diikuti dengan spasi), nilai tersebut harus diberi tanda kutip.

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

Pengutipan yang benar:

name: 'TV on lights off'

name: "TV on lights off"

Tanda kutip 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 (dengan dua spasi) untuk menunjukkan bahwa keduanya adalah turunan dari kunci metadata.

Indentasi bersifat ketat di YAML. Struktur turunan harus memiliki indentasi yang lebih dalam daripada induknya, dan pasangan nilai kunci dengan 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 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 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 didahului 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 Automations menentukan beberapa struktur data:

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

Struct

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

Lihat Struct automation, yang menentukan empat kolom:

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

Deskripsi setiap Kolom berisi informasi penting, termasuk:

• Wajib versus Opsional, yang menunjukkan apakah kolom tersebut wajib diisi atau dapat dilewati.
• Dependensi Kolom. Hanya Bidang Options 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 yang Memiliki Jenis

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 Typed Struct, 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 yang ditentukan untuk jenis tersebut yang valid dalam Struct starter tersebut.

Array

Dalam 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 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:

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.
• Value menunjukkan kecerahan atau kegelapan relatif warna.

Dinamis

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

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 lain mungkin memerlukan beberapa level untuk mendapatkan item yang diperlukan, dan formatnya berbeda antara pemicu dan tindakan.

Pemula menggunakan notasi titik, dengan seluruh jalur di 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