Ngôn ngữ cơ bản

Tìm hiểu về YAML

YAML là một ngôn ngữ phổ biến dùng để chỉ định cấu hình phần mềm. JSON cung cấp một cách rõ ràng, dễ đọc để thể hiện thông tin có cấu trúc. Dưới đây là một số điều cơ bản bạn cần hiểu về YAML trước khi tạo quy trình tự động hoá đầu tiên theo tập lệnh. Để tìm hiểu thêm về YAML nói chung, hãy xem quy cách Phiên bản 1.1.

Cặp khóa-giá trị

Về cơ bản, tài liệu YAML là một tập hợp các cặp khoá-giá trị. Trong ví dụ sau, khoá là name và giá trị là TV on lights off. Khoá và giá trị được phân tách bằng dấu hai chấm, theo sau là một dấu cách. Cả hai ký tự này đều bắt buộc đối với tệp YAML được định dạng đúng cách.

name: TV on lights off

Giá trị

Giá trị liên kết với một khoá có thể ở dạng cơ bản như chuỗi, số hoặc ngày, hoặc phức tạp như một tập hợp khác gồm các cặp khoá-giá trị.

Chuỗi

Nếu giá trị chuỗi bắt đầu bằng một trong các ký tự sau: [, {, ", ' hoặc #, hoặc chuỗi chứa : (dấu hai chấm theo sau là dấu cách), thì giá trị đó phải được đặt trong dấu ngoặc kép.

Bạn có thể sử dụng cả dấu ngoặc đơn và dấu ngoặc kép, nhưng dấu ngoặc kép đóng phải khớp với dấu ngoặc kép mở.

Cách trích dẫn chính xác:

name: 'TV on lights off'

name: "TV on lights off"

Dấu ngoặc kép không chính xác (dấu ngoặc kép không khớp):

name: 'TV on lights off"

Bạn không bắt buộc phải sử dụng dấu ngoặc kép cho tất cả các loại chuỗi khác.

Nếu bạn cần một chuỗi nhiều dòng, hãy xem mục quy cách YAML về các đại lượng vô hướng nhiều dòng.

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

Cặp khoá-giá trị lồng nhau

Ở đây, giá trị của khoá metadata là danh sách gồm hai cặp khoá-giá trị (name và description):

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

Thụt lề

YAML sử dụng thụt lề để biểu thị cấu trúc. Trong ví dụ trước, name và description được thụt lề (bằng hai dấu cách) để biểu thị rằng đây là các phần tử con của khoá metadata.

Thụt lề phải nghiêm ngặt trong YAML. Cấu trúc con phải có dấu thụt lề sâu hơn cấu trúc mẹ và các cặp khoá-giá trị ở cùng cấp phải có cùng dấu thụt lề.

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

Nhiều giá trị

Nếu một khoá nhất định có nhiều giá trị, thì mỗi giá trị sẽ được liệt kê trong một dòng mới và mỗi dòng bắt đầu bằng một dấu gạch ngang và một dấu cách. Trong ví dụ sau, có hai danh sách:

  1. Một quy trình tự động hoá có thể có nhiều starters, do đó, trình chạy đầu tiên bắt đầu bằng một dấu gạch ngang và một dấu cách.
  2. weekday có thể có nhiều giá trị, do đó, mỗi giá trị được thụt lề thêm và bắt đầu bằng một dấu gạch ngang và một dấu cách.
starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

Bình luận

Mọi văn bản theo sau # đều được coi là chú thích và bị công cụ tự động hoá bỏ qua.

Dòng bắt đầu bằng # là một nhận xét.

Chú thích có thể xuất hiện trên cùng dòng với nội dung tập lệnh, nhưng # phải có dấu cách ở phía trước.

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

Tập lệnh tự động hoá

Thông số kỹ thuật cho cú pháp tập lệnh của tính năng Tự động hoá được gọi là giản đồ.

Giản đồ Automations (Tự động hoá) xác định một số cấu trúc dữ liệu:

  • Một cặp khoá-giá trị được gọi là Trường.
  • Tập hợp các trường do giản đồ xác định được gọi là Cấu trúc (Struct).

Cấu trúc

Ngôn ngữ tập lệnh tự động hoá xác định một số "khối" hoặc cấu trúc dữ liệu tiêu chuẩn, được gọi là Structs.

Hãy xem Cấu trúc automation, cấu trúc này xác định 4 trường:

Khóa Loại Nội dung mô tả

name

String

Không bắt buộc.

Tên của quy trình tự động.

Thông tin này chỉ dành cho nhà phát triển tham khảo và không hiển thị cho người dùng.

starters

[Starter]

Bắt buộc.

Danh sách các món khai vị.

condition

Điều kiện

Không bắt buộc.

Tình trạng.

actions

[Thao tác]

Bắt buộc.

Danh sách thao tác.

Phần Tham chiếu cung cấp các định nghĩa giản đồ cho tất cả Cấu trúc có sẵn.

Tên khoá phải duy nhất trong một Cấu trúc nhất định và có phân biệt chữ hoa chữ thường.

Các loại giá trị có thể có là:

  • Loại gốc: bool, số, chuỗi, thời gian, v.v.
  • Loại Struct: một tập hợp các trường.
  • Một Mảng của loại dữ liệu. Mảng được biểu thị bằng []. Ví dụ: [string] là một mảng các chuỗi và [Starter] là một mảng các Cấu trúc khởi động.
  • Các loại đặc biệt khác: Thực thể, FieldPath.

Phần mô tả của mỗi Trường chứa thông tin quan trọng, bao gồm:

  • Bắt buộc so với Không bắt buộc, cho biết trường này là bắt buộc hay có thể bỏ qua.
  • Phần phụ thuộc trường. Chỉ các Trường không bắt buộc mới có Phần phụ thuộc. Phần này mô tả các bước kiểm tra bổ sung khi sử dụng trường này, chẳng hạn như Chỉ sử dụng Trường B nếu bạn đặt Trường A hoặc Khi sử dụng Trường A, đừng đặt Trường B hoặc Trường C.
  • Giá trị có thể dùng. Ví dụ: tập hợp giá trị giới hạn của Trường Enum thuộc loại chuỗi hoặc một dải số có thể được sử dụng trong Trường thuộc loại số.

Cấu trúc đã nhập

Một số Cấu trúc có thể đại diện cho trình khởi động dựa trên lịch biểu thời gian hoặc thay đổi trạng thái thiết bị. Mỗi loại starter phải cung cấp một tập hợp Trường riêng biệt.

# 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 là một Cấu trúc được nhập, được mở rộng bởi các Cấu trúc con khác trong trường type, chẳng hạn như time.schedule hoặc device.state.OnOff, để cung cấp nhiều hàm. Cấu trúc condition và action cũng được nhập.

Các trường bổ sung trong Cấu trúc phải tuân theo quy cách của Cấu trúc con (type). Ví dụ: khi sử dụng device.state.OnOff làm type, chỉ có các trườngđược chỉ định cho loại đó là hợp lệ trong Cấu trúc starter đó.

Mảng

Trong YAML, một mảng giá trị bắt đầu bằng - (dấu gạch ngang, theo sau là dấu cách). Mảng này có thể chứa nhiều giá trị Cấu trúc hoặc nhiều giá trị Nguyên hàm. Tuy nhiên, các giá trị trong mảng phải thuộc cùng một loại.

Khi mảng chứa một phần tử, bạn có thể bỏ qua dấu gạch ngang và dấu cách:

# 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

Mảng nhiều chiều, chẳng hạn như [[1, 2], [3, 4]], không được hỗ trợ trong tập lệnh tự động hoá. Trình phân tích cú pháp ngôn ngữ sẽ tự động làm phẳng một mảng nhiều chiều thành một mảng một chiều, trong trường hợp này là [1, 2, 3, 4].

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

Nguyên hàm

Các loại dữ liệu gốc sau đây được hỗ trợ trong giản đồ tập lệnh Automations:

Bool
  • true
  • false

Số

Số nguyên hoặc số thập phân

Chuỗi

Văn bản thuần túy

Bạn không cần phải đặt dấu ngoặc kép cho chuỗi, ngoại trừ trong các trường hợp cụ thể.

Ngày

Tháng và ngày. Định dạng là MM-DD hoặc MM/DD.

  • 09/01
  • 09-01

Thời gian

Thời gian trong ngày. Đó có thể là thời gian theo đồng hồ hoặc thời gian theo mặt trời. Đối với thời gian trên đồng hồ, bạn có thể sử dụng định dạng SA/CH hoặc định dạng 24H. Bạn không bắt buộc phải nhập giây. Đối với giờ mặt trời, sunrise và sunset là từ khoá và có thể theo sau là một độ lệch (theo các điều khoản về Thời lượng).

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

DateTime

Năm, Tháng, Ngày và Giờ trong ngày. Bạn phải có khoảng trắng giữa phần Ngày và phần Giờ. Định dạng ngày là YYYY-MM-DD hoặc YYYY/MM/DD. Định dạng thời gian giống với [Thời gian](#time). Không hỗ trợ múi giờ.

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

Ngày trong tuần

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

Thời lượng

Một khoảng thời gian.

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

Mã thập lục phân gồm 6 chữ số đại diện cho một màu.

Không có # dẫn đầu.

  • FFFFFF
  • B5D2A1
  • DFA100
Nhiệt độ

Dữ liệu nhiệt độ bình thường. Luôn thêm 'C' hoặc 'F' vào giá trị để biểu thị một phép đo nhiệt độ.

  • 20.5C
  • 90F
ColorTemperature

Nhiệt độ màu tính theo độ K.

  • 5000K

Màu

Bạn có thể chỉ định màu theo một trong ba cách – sử dụng loại gốc ColorHex hoặc ColorTemperature hoặc loại phức hợp SpectrumHSV.

SpectrumHSV

Loại SpectrumHSV chỉ định một màu bằng cách sử dụng ba trường số:

  • Hue (Tông màu) tương ứng với bước sóng màu.
  • Độ bão hoà cho biết độ đậm nhạt của màu.
  • Giá trị cho biết độ sáng hoặc độ tối tương đối của màu.

Động

Đôi khi, loại dữ liệu của khoá không cố định. Đây có thể là một trong các loại nguyên gốc, dựa trên các giá trị từ các trường khác.

Ví dụ về trường kiểu dữ liệu động là is. Loại thực tế được xác định bằng giá trị của cả trường type và 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

Thực thể

Một định dạng Chuỗi đặc biệt để nhận dạng duy nhất một thực thể thuộc sở hữu của người dùng, chẳng hạn như thiết bị hoặc phòng.

Thiết bị là thực thể phổ biến nhất được dùng trong quy trình Tự động hoá. Định dạng Chuỗi thực thể là 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

Định dạng Chuỗi đặc biệt dùng để xác định vị trí của một phần dữ liệu trong tải trọng dữ liệu. Trong ví dụ sau, currentVolume là FieldPath cho trường state.

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

Các FieldPath khác có thể yêu cầu nhiều cấp để truy cập vào mục bắt buộc và định dạng khác nhau giữa trình khởi động và thao tác.

Các trình khởi động sử dụng ký hiệu dấu chấm, với toàn bộ đường dẫn trong cùng một trường. Việc này chủ yếu được thực hiện cho mục đích so sánh trong logic trình khởi động. Ví dụ: để sử dụng nhiệt độ màu làm giá trị khởi động, bạn sẽ sử dụng color.colorTemperature cho trạng thái:

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

Tuy nhiên, các hành động sử dụng các trường lồng nhau. Để thay đổi màu của bóng đèn thành màu xanh dương, thay vì color.name và is: blue, bạn phải làm như sau:

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