語言基本概念

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

自動化指令碼

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

「自動化動作」結構定義會定義幾種資料結構：

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

結構

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

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

「 部分提供所有可用結構體的結構定義。

鍵名在特定結構體中不得重複，且區分大小寫。

可能的值類型包括：

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

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

• 「必要」與「選填」：指出欄位是否為必填，或是否可以略過。
• 欄位相依性。只有選填欄位有相依性。這說明使用此欄位時的額外檢查，例如「只有在設定欄位 A 時才使用欄位 B」，或「使用欄位 A 時，請勿設定欄位 B 或欄位 C」。
• 可能的值。舉例來說，字串型別的 Enum 欄位值集有限，或是數字型別的欄位可使用的數字範圍。

具類型的結構

部分結構體可根據時間表或裝置狀態變化代表啟動條件。每種 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 是型別結構體，由「Field」(欄位) 中的其他子結構體 (例如 time.schedule 或 device.state.OnOff) 擴充，以提供不同功能。typecondition 和 action 結構體也是型別。

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

陣列

在 YAML 中，值陣列會以 - (破折號後方加上空格) 開頭。陣列可以保存多個 Struct 值或多個 Primitive 值。但陣列中的值必須是相同類型。

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

# 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