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 phần mềm . Mã này cung cấp cách thức rõ ràng, dễ đọc để con người có thể thể hiện 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 rõ YAML trước khi tạo quy trình tự động hoá theo tập lệnh đầu tiên. Để tìm hiểu thêm về YAML nói chung, hãy xem 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 phần sau ví dụ: khoá là name và giá trị là TV on lights off. Khoá và giá trị được phân cách bằng dấu hai chấm và theo sau là dấu cách. Cả hai ký tự đều bắt buộc đối với YAML được định dạng tốt.

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ư 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 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ì chuỗi này phải là trích dẫn.

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 nhau câu mở đầu.

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 thêm 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ề là nghiêm ngặt trong YAML. Cấu trúc con phải có thụt lề sâu hơn so với cấp độ gốc và các cặp khoá-giá trị cùng cấp phải có cùng khoả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ị, 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 có thể có nhiều starters, do đó điều kiện khởi động đầ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ị nên mỗi giá trị sẽ lớn hơn thụt lề và bắt đầu bằng 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 đứng sau # đều được xem là một nhận xét và bị bỏ qua nhờ công cụ tự động hoá.

Một 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 một dòng với nội dung tập lệnh, nhưng # phải là đứng sau 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 của tính năng 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.
• 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" tiêu chuẩn hoặc dữ liệu cấu trúc, được gọi là Cấu trúc.

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

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

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

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

• Loại nguyên gốc: bool, số, chuỗi, thời gian, v.v.
• Loại Cấu trúc: một tập hợp các trường.
• Một Mảng (array) của kiểu 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 gồm các Cấu trúc khởi đầu.
• Các loại đặc biệt khác: Thực thể, TrườngPath.

Nội dung mô tả của từng Trường chứa những thông tin quan trọng, bao gồm:

• Bắt buộc và Không bắt buộc, cho biết đây là trường bắt buộc hay có thể bỏ qua.
• Phần phụ thuộc trường. Chỉ những trường không bắt buộc mới có phần phụ thuộc. Điều này mô tả các bước kiểm tra bổ sung khi sử dụng trường này, như Chỉ sử dụng Trường B khi Trường A là set hoặc Khi sử dụng Trường A, đừ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 Enum Trường kiểu chuỗi hoặc một dải số có thể dùng trong một Trường số loại.

Cấu trúc đã nhập

Một số Cấu trúc có thể đại diện cho các 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 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 Cấu trúc được phân loại, đượ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 chức năng 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 theo sau Struct con (type) đặc điểm kỹ thuật. Ví dụ: khi sử dụng device.state.OnOff làm type, chỉ thời gian trường được chỉ định cho trường đó loại có hiệu lực tại 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). Chiến lược phát hành đĩa đơn mảng có thể chứa nhiều giá trị Cấu trúc hoặc nhiều giá trị 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, bạn có thể bỏ 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 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

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

Màu

Màu có thể được chỉ định theo một trong ba cách - sử dụng Các 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àu bằng cách sử dụng ba trường số:

• Hue 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 một khoá là không cố định. Đó có thể là một trong những dữ liệu gốc dựa trên giá trị từ các trường khác.

Ví dụ về trường loại 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 để nhận dạng duy nhất một thực thể do người dùng sở hữu, chẳng hạn như hoặc phòng.

Thiết bị là thực thể phổ biến nhất được dùng trong tính năng Tự động hoá. Định dạng chuỗi của 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 được dùng để xác định vị trí một phần dữ liệu trong tải trọng dữ liệu. Trong trong ví dụ sau, currentVolume là Đường dẫn trường 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. Đây là 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 khi 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, hành động sẽ 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 thực hiện:

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