語言基本概念

瞭解 YAML

YAML 是一種熱門語言，用於指定軟體 此外還會從 0 自動調整資源配置 您完全不必調整資源調度設定採用清楚易懂且人類可讀的方式 結構化資訊以下列舉幾項請務必瞭解的 建立第一個自動化動作指令碼前的 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 內的鍵名稱不得重複，且區分大小寫。

可能的值類型如下：

• 基本型別：布林值、數字、字串、時間等。
• 結構體類型：欄位集合。
• 資料類型的陣列。陣列會以 [] 表示。例如：[string] 是字串陣列，而 [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 中，值陣列以 - 開頭 (破折號後接空格)。 陣列可包含多個 Struct 值，或多個原始值。不過 陣列中的值必須為相同類型。

當陣列包含一個項目時，您可以省略破折號和空格：

# 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 類型會使用三個數字欄位指定色彩：

• 「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 可能需要多個層級才能取得所需項目，且 啟動條件和動作的格式各有不同

啟動條件採用點標記法，且完整路徑位於相同欄位中。這是 主要用於比較入門邏輯中的比較舉例來說，如要使用色溫做為啟動條件，您可以使用 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