語言基本概念

瞭解 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.

自動化指令碼

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

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

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

結構

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

請查看 automation Struct，其中定義了四個欄位：

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

鍵名稱在特定 Struct 中不得重複，且區分大小寫。

可能的值類型如下：

• 原始類型：bool、number、string、time 等。
• Struct 類型：一組欄位。
• 資料類型的陣列。陣列以 [] 表示。例如，[string] 是字串陣列，[Starter] 則是 Starter Struct 陣列。
• 其他特殊類型：Entity、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 是 Typed Struct，由 type 欄位中的其他子 Struct (例如 time.schedule 或 device.state.OnOff) 擴充，以提供不同函式。condition 和 action 結構體也已輸入。

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

陣列

在 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

樸實

自動化動作指令碼結構定義支援下列原始資料類型：

顏色

指定顏色的方式有三種：使用 ColorHex 或 ColorTemperature 原始類型，或複合類型 SpectrumHSV。

SpectrumHSV

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

• 色相對應顏色波長。
• 飽和度代表色彩強度。
• 明度代表顏色的相對明暗度。

動態

有時，鍵的資料類型不固定。可以是其中一種原始類型，具體取決於其他欄位的值。

動態資料類型欄位的範例為 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 可能需要多個層級才能取得所需項目，且格式會因啟動條件和動作而異。

啟動條件使用點標記法，整個路徑都在同一個欄位中。這主要是為了在入門邏輯中進行比較。舉例來說，如要使用色溫做為啟動條件，請將狀態設為 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