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. Công cụ này đưa ra một cách rõ ràng, dễ đọc để trình bày 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 theo tập lệnh đầu tiên. Để tìm hiểu thêm về YAML nói chung, hãy xem Thông số kỹ thuật của Phiên bản 1.1.

Cặp khóa-giá trị

Tài liệu YAML về cơ bản 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à dấu cách. Bạn phải có cả hai ký tự này để sử dụng 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ể ở mức cơ bản ở dạng chuỗi, số hoặc ngày tháng hoặc phức tạp như một tập hợp cặp khoá-giá trị khác.

Chuỗi

Nếu một 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 : (một 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.

Cả dấu ngoặc đơn và dấu ngoặc kép đều được chấp nhận, nhưng dấu ngoặc kép đóng phải khớp với dấu ngoặc kép mở.

Trích dẫn chính xác:

name: 'TV on lights off'

name: "TV on lights off"

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

name: 'TV on lights off"

Không bắt buộc phải có 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 phần thông số kỹ thuật 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 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 tính năng thụt đầu dòng để biểu thị cấu trúc. Trong ví dụ trước, name và description được thụt đầu dòng (bằng 2 dấu cách) để biểu thị rằng đây là các phần tử con của khoá metadata.

Thụt lề nghiêm ngặt trong YAML. Cấu trúc con phải có khoảng thụt lề sâu hơn cấu trúc gốc và các cặp khoá-giá trị cùng cấp phải có cùng 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ị, mỗi giá trị sẽ được liệt kê trong một dòng mới và mỗi dòng bắt đầu, theo sau là dấu gạch ngang và dấu cách. Trong ví dụ sau, có 2 danh sách:

  1. Một quá trình tự động hoá có thể có nhiều starters, do đó điều kiện khởi động đầu tiên bắt đầu bằng dấu gạch ngang và dấu cách.
  2. weekday có thể có nhiều giá trị, do đó, mỗi giá trị đều được thụt lề thêm và bắt đầu bằng dấu gạch ngang và 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 đứng sau # đều được xem là nhận xét và sẽ bị công cụ tự động hoá bỏ qua.

Dòng bắt đầu bằng # là một ghi chú.

Nhận xét có thể xuất hiện trên cùng một dòng với nội dung tập lệnh, nhưng # phải được đứng trước một dấu cách.

# 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 Tự động hoá được gọi là giản đồ.

Giản đồ 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.
  • Một tập hợp các trường do giản đồ này xác định được gọi là Cấu trúc.

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 chuẩn, được gọi là Cấu trúc.

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

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

name

Chuỗi

Không bắt buộc.

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

Người dùng không thấy được tên này mà chỉ nhà phát triển tham khảo.

starters

[Người khởi đầu]

Bắt buộc.

Danh sách điều kiện khởi động.

condition

Tình trạng

Không bắt buộc.

Điều kiện.

actions

[Hành động]

Bắt buộc.

Danh sách các hành động.

Phần Tài liệu tham khảo cung cấp định nghĩa giản đồ cho tất cả các Cấu trúc có sẵn.

Tên khoá là duy nhất trong một Struct nhất định và có phân biệt chữ hoa chữ thường.

Các loại giá trị có thể sử dụng là:

  • Kiểu nguyên gốc: bool, số, chuỗi, thời gian, v.v.
  • Một loại Cấu trúc: một tập hợp các trường.
  • Một mảng thuộc loại dữ liệu. Mảng được biểu thị bằng []. Ví dụ: [string] là một mảng chuỗi và [Starter] là một mảng Cấu trúc khởi đầu.
  • Các loại đặc biệt khác: Entity, fieldPath.

Nội dung mô tả của từng Trường chứa các 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 liệu trường là bắt buộc hoặc có thể bỏ qua hay không.
  • Phần phụ thuộc của 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 Trường A được đặt hoặc Khi Trường A được sử dụng, đừng đặt Trường B hoặc Trường C.
  • Giá trị có thể sử dụng. Ví dụ: tập hợp giá trị giới hạn của một Trường Enum thuộc chuỗi hoặc một dải số có thể dùng trong Trường số loại.

Cấu trúc đã nhập

Một số Cấu trúc có thể biểu thị điều kiện khởi động dựa trên lịch biểu thời gian hoặc sự 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 (typed Structure) đượ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 các hàm khác nhau. 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ấu trúc con (type). Ví dụ: khi sử dụng device.state.OnOff làm type, chỉcác trường được chỉ định cho loại đó mới 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ị Struct hoặc nhiều giá trị Nguyên gốc. Tuy nhiên, các giá trị trong mảng phải thuộc cùng loại.

Khi mảng chứa một mục duy nhấ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 đa chiều, chẳng hạn như [[1, 2], [3, 4]], không được hỗ trợ trong tập lệnh tự động. Trình phân tích cú pháp ngôn ngữ sẽ tự động làm phẳng một mảng đa 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 bản

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

Bool
  • true
  • false

Số

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

Chuỗi

Chữ thường

Bạn không cần phải trích dẫn 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 điểm trong ngày. Đó có thể là giờ đồng hồ hoặc giờ mặt trời. Đối với giờ theo đồng hồ, có thể sử dụng định dạng AM/PM hoặc định dạng 24H. Bạn không bắt buộc phải sử dụng giây. Đối với thời gian mặt trời, sunrise và sunset là các từ khoá và có thể theo sau là một giá trị bù trừ (trong điều khoản 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 Thời gian. Định dạng ngày là YYYY-MM-DD hoặc YYYY/MM/DD. Định dạng thời gian giống với [Time](#time). Múi giờ không được hỗ trợ.

  • 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ố biểu thị một màu.

Không có # nào ở đầu.

  • FFFFFF
  • B5D2A1
  • DFA100
Nhiệt độ

Dữ liệu về nhiệt độ bình thường. Luôn thêm 'C' hoặc 'F' vào giá trị để biểu thị 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 3 cách – sử dụng loại nguyên gốc ColorHex hoặc ColorTemperature hoặc loại hợp chất SpectrumHSV.

SpectrumHSV

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

  • Hue tương ứng với bước sóng màu.
  • Độ bão hoà cho biết cường độ 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 cố định. Đây có thể là một trong những loại nguyên thuỷ, dựa trên giá trị từ các trường khác.

Một ví dụ về trường loại dữ liệu động là is. Loại thực tế được xác định bởi 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ể

Định dạng Chuỗi đặc biệt để xác định duy nhất một thực thể do người dùng sở hữu, 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 các thao tác 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

Một định dạng Chuỗi đặc biệt dùng để định vị một phần dữ liệu trong tải trọng dữ liệu. Trong ví dụ sau, currentVolume là Trường Đường dẫn 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 trường bắt buộc khác có thể yêu cầu nhiều cấp để chuyển đến mục bắt buộc, đồng thời có định dạng khác nhau giữa điều kiện khởi động và hành động.

Bắt đầu sử dụng ký hiệu dấu chấm, với toàn bộ đường dẫn nằm 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 khởi đầu. Ví dụ: để sử dụng nhiệt độ màu làm điều kiện 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, thao tác 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