Ngôn ngữ cơ bản

Tìm hiểu về YAML

YAML là một ngôn ngữ phổ biến được 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 để biểu thị 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á dựa trên tập lệnh đầu tiên. Để 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, sau đó là một dấu cách. Cả hai ký tự này đều bắt buộc đối với YAML có cấu trúc hợp lệ.

name: TV on lights off

Giá trị

Giá trị được 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 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ì bạn phải đặt chuỗi 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ề 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 2 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 tắc thụt lề nghiêm ngặt. Cấu trúc con phải 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ê trên một dòng mới và mỗi dòng bắt đầu bằng dấu gạch ngang và dấu cách. Trong ví dụ sau, có 2 danh sách:

1. Một quy trình tự động hoá có thể có nhiều starters và 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ị và 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 sau ký hiệu # đều được coi là chú thích và sẽ bị công cụ tự động hoá bỏ qua.

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

Mộ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 ở 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á

Quy cách về 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à Trường.
• Một tập hợp các trường do giản đồ xác định được gọi là Struct.

Struct

Ngôn ngữ kịch bản 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 Struct automation. Struct này xác định 4 trường:

Phần Reference (Tham chiếu) cung cấp các định nghĩa về lược đồ cho tất cả các Struct có sẵn.

Tên khoá là 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ể 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 thuộc 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 liệu trường này là bắt buộc hay có thể bỏ qua.
• Phụ thuộc vào trường. Chỉ các Trường không bắt buộc mới có 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ể có. Ví dụ: tập hợp giá trị giới hạn của một EnumField thuộc loại chuỗi hoặc một dải số có thể được dùng trong một Field thuộc loại số.

Cấu trúc đã nhập

Một số Struct có thể đại diện cho các điều kiện 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 riêng biệt gồm các Trường.

# 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 các chức năng khác nhau. Các 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ác trường được chỉ định cho loại đó mới hợp lệ trong Struct 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 có thể chứa nhiều giá trị Struct hoặc nhiều giá trị Primitive. Nhưng các giá trị trong mảng phải thuộc cùng một loại.

Khi mảng chỉ chứa một mục, bạn có thể bỏ qua dấu gạch ngang và khoảng trắng:

# 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ỷ

Sau đây là các loại dữ liệu nguyên thuỷ được lược đồ tập lệnh Tự động hoá hỗ trợ:

Màu

Bạn có thể chỉ định màu theo một trong ba cách: sử dụng các kiểu nguyên thuỷ ColorHex hoặc ColorTemperature, hoặc kiểu phức hợp SpectrumHSV.

SpectrumHSV

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

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

is là một ví dụ về trường kiểu dữ liệu động. 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ể 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 tính năng 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 để 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 để đến được mục bắt buộc và định dạng khác nhau giữa trình khởi chạy và hành động.

Các giá trị 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ểm bắt đầu, bạn 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 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