語言基本概念

瞭解 YAML

YAML 是一種常見的語言，用於指定軟體設定。可透過清楚且人類可讀的方式呈現結構化資訊。在建立第一個自動化動作指令碼之前，請先瞭解 YAML 的幾個基本概念。如要進一步瞭解一般 YAML，請參閱 第 1.1 版規格。

鍵/值組合

YAML 文件基本上是一組鍵/值組合。在以下範例中，鍵為 name，值為 TV on lights off。鍵和值以半形冒號分隔，後面加上空格。這兩個字元都是正確格式的 YAML 必要條件。

name: TV on lights off

值

與鍵相關聯的值可以是簡單的字串、數字或日期，也可以是另一個複雜的鍵/值組合集合。

字串

如果字串值開頭為下列任一字元：[、{、"、' 或 #，或是字串包含 : (半形冒號後接空格)，則必須加上引號。

系統接受單引號和雙引號，但結尾引號必須與開頭引號一致。

正確引用：

name: 'TV on lights off'

name: "TV on lights off"

不正確的引號使用方式 (不相符的引號)：

name: 'TV on lights off"

對於所有其他類型的字串，引號為選用項目。

如果您需要多行字串，請參閱 YAML 規格中的多行標量部分。

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

巢狀鍵/值組合

在此，鍵 metadata 的值是兩個鍵/值組合 (name 和 description) 的清單：

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

縮排

YAML 使用縮排表示結構。在上述範例中，name 和 description 會以兩個空格縮排，表示這兩者是鍵 metadata 的子項。

YAML 中的縮排必須嚴格遵守規則。子項結構體的縮排必須比父項更深，而相同層級的鍵/值組則必須使用相同的縮排。

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

多個值

如果指定的鍵有多個值，每個值都會列在新的一行中，且每行開頭都會加上破折號和空格。在以下範例中，有兩個清單：

  1. 自動化動作可以有多個 starters，因此第一個啟動條件會以連字號和空格開頭。
  2. weekday 可包含多個值，因此每個值都會進一步縮排，並以連字號和空格開頭。
starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

留言

自動化引擎會將 # 後面的任何文字視為註解，並予以忽略。

以 # 開頭的行是註解。

註解可以與指令碼內容顯示在同一行，但 # 前面必須有空格。

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

自動化動作指令碼

自動化動作指令碼語法規格稱為結構定義。

自動化動作結構定義了幾個資料結構：

  • 單一鍵/值組合稱為欄位。
  • 由架構定義的欄位集合稱為「結構體」。

結構

自動化動作指令碼語言會定義多個標準「模塊」或資料結構，稱為「Structs」。

請查看 automation 結構體，其中定義了四個欄位：

鍵 類型 說明

name

字串

選填。

自動化動作的名稱。

這項資訊不會對使用者顯示，僅供開發人員參考。

starters

[Starter]

必填。

啟動條件清單。

condition

條件

選填。

條件。

actions

[Action]

必填。

動作清單。

參考資料 部分提供所有可用結構體的結構定義。

鍵名稱在特定結構體中是唯一的，且區分大小寫。

可能的值類型包括：

  • 原始類型：布林值、數字、字串、時間等等。
  • 結構體類型：欄位集合。
  • 資料類型的陣列。陣列會以 [] 表示。舉例來說，[string] 是字串陣列，而 [Starter] 則是 Starter 結構體陣列。
  • 其他特殊類型：實體、FieldPath。

每個欄位的說明都包含重要資訊，包括：

  • 必要與選用，指出欄位是否為必填欄位，或可供略過。
  • 欄位相依性。只有選填欄位有依附元件。這會說明使用此欄位時的額外檢查項目，例如「僅在設定了欄位 A 時使用欄位 B」或「使用欄位 A 時，請勿設定欄位 B 或欄位 C」。
  • 可能的值。例如，字串類型列舉欄位的有限值集，或是數字類型欄位中可使用的數字範圍。

具類型結構

部分結構體可根據時間表或裝置狀態變更，代表啟動條件。每個 starter 類型都必須提供一組不同的欄位。

# 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 是一種型別化的結構體，可由 type 欄位中的其他子結構體 (例如 time.schedule 或 device.state.OnOff) 擴充，以提供不同的函式。condition 和 action 結構體也具有類型。

結構體中的其他欄位必須遵循子結構體 (type) 規格。舉例來說，如果使用 device.state.OnOff 做為 type，則只有為該類型指定的欄位 才會在該 starter 結構體中有效。

陣列

在 YAML 中，值陣列的開頭為 - (破折號後面加上空格)。陣列可容納多個結構體值或多個基本值。但陣列中的值必須屬於相同類型。

如果陣列只包含一個項目，您可以省略連字號和空格：

# 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

自動化動作指令碼不支援 [[1, 2], [3, 4]] 等多維陣列。語言剖析器會自動將多維陣列扁平化為單維陣列，在本例中為 [1, 2, 3, 4]。

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

樸實

自動化指令碼結構定義支援下列基本資料類型：

布林值
  • true
  • false

數字

整數或小數

字串

純文字

除了特定情況，字串不需要加上引號。

日期

月份和日期。格式為 MM-DD 或 MM/DD。

  • 09/01
  • 09-01

時間

時段。可以是時鐘時間或太陽時間。時鐘時間可以使用 12 或 24 小時制，秒數為選用項目。對於太陽時間，sunrise 和 sunset 是關鍵字，後面可能會加上偏移值 (以時間長度表示)。

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

DateTime

年、月、日和一天中的時間。日期部分和時間部分之間必須有空格。日期格式為 YYYY-MM-DD 或 YYYY/MM/DD。時間格式與 [時間](#time) 相同。 不支援時區。

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

平日

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

時間長度

一段時間。

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

代表顏色的六位數十六進制代碼。

開頭不用加上 #。

  • FFFFFF
  • B5D2A1
  • DFA100
溫度

正常溫度資料。請務必在值中加上 'C' 或 'F'，表示溫度測量值。

  • 20.5C
  • 90F
ColorTemperature

色溫 (克耳文)。

  • 5000K

顏色

您可以使用以下三種方式指定顏色：使用 ColorHex 或 ColorTemperature 原始類型，或是複合類型 SpectrumHSV。

SpectrumHSV

SpectrumHSV 類型會使用三個數值欄位指定顏色：

  • Hue 對應到顏色波長。
  • 「飽和度」代表色彩濃度。
  • 「值」：表示顏色的相對明亮或深色。

動態

有時鍵的資料類型並未固定。這可以是原始類型之一，取決於其他欄位的值。

動態資料類型欄位的範例為 is。實際類型是由 type 和 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

實體

特殊的字串格式，用於明確識別使用者擁有的實體，例如裝置或房間。

裝置是自動化動作中最常使用的實體。實體字串格式為 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

一種特殊的字串格式，用於在資料酬載中找出某個資料。在以下範例中，currentVolume 是 state 欄位的 FieldPath。

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

其他 FieldPath 可能需要多個層級才能取得必要項目，且啟動條件和動作的格式不同。

Starters 使用點標記法，整個路徑都位於同一個欄位中。這主要是為了在啟動條件邏輯中進行比較。舉例來說，如要使用色溫做為啟動條件，您可以使用 color.colorTemperature 做為狀態：

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

不過，動作會使用巢狀欄位。如要將燈泡的顏色變更為藍色，而非 color.name 和 is: blue，請執行以下操作：

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