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. Định dạng này cung cấp một cách rõ ràng, con người có thể đọc được để trình bày thông tin có cấu trúc. Sau đâ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 bằng tập lệnh. Để 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ị

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à dấu cách. Cả hai ký tự đều bắt buộc để có YAML đúng định dạng.

name: TV on lights off

Giá trị

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

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ì chuỗi đó 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 đóng phải khớp với dấu ngoặc 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"

Dấu ngoặc kép là không bắt buộc đối với 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 quy cách YAML về 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.

YAML có quy định nghiêm ngặt về việc thụt lề. Cấu trúc con phải có mức 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 mức 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 đó, đ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ị sẽ đượ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 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.

Nhận xét 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 đứng trước.

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

Kịch bản tự động hoá

Quy cách 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ị duy nhất được gọi là một Trường.
• Tập hợp các trường do giản đồ xác định được gọi là 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 chuẩn, được gọi là Cấu trúc.

Hãy xem Struct automation, trong đó xác định 4 trường:

Phần Tài liệu tham khảo cung cấp định nghĩa giản đồ cho tất cả các Struct 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ể có là:

• Kiểu dữ liệu 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 chuỗi và [Starter] là một mảng Starter Structs.
• Các loại đặc biệt khác: Entity, FieldPath.

Nội dung 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 của trường. Chỉ các trường tuỳ chọn 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 sử dụng Trường A, khô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 loại chuỗi hoặc một dải số có thể được dùng trong một Trường thuộc loại số.

Cấu trúc đã nhập

Một số Struct có thể đại diện cho điều kiện khởi động dựa trên lịch biểu hoặc thay đổi trạng thái thiết bị. Mỗi loại starter phải cung cấp một nhóm 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 Struct có kiểu dữ liệu, được các Struct con khác mở rộng 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 Struct phải tuân theo quy cách của Struct 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 starter Struct đó.

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 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 một loại.

Khi mảng chứa một mục, 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 hoá. 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 thuỷ

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

Màu

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

SpectrumHSV

Loại SpectrumHSV chỉ định màu bằng ba trường số:

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

Đị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 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 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 sẽ khác nhau giữa điều kiện khởi động và hành động.

Người mới bắt đầu 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 khởi động. 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, các hành động sử dụng trường lồng nhau. Để đổ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