DSL 概念

以下是自動化 DSL 的基本概念總覽。

自動化元件

自動化動作由下列基本元件組成，通常會依照以下順序進行評估：

1. 啟動條件：定義啟動自動化動作的初始條件，例如特徵變更。自動化動作必須有啟動條件。
2. 條件：啟用自動化動作後，系統會評估的其他限制。條件中的運算式必須評估為 true，自動化動作的動作才能繼續執行。
3. 動作：在符合所有條件時執行的指令或狀態更新。

舉例來說，假設你設定了自動化動作，在日落和日出之間，當房間中的電視開啟時，系統就會調暗房間的燈光。在這個例子中：

1. Starter：電視已開啟，這是電視特徵的狀態變更。
2. 條件：評估電視所在住家的目前時間。
3. 動作：與電視位於同一個房間的燈光會調暗。

當房間的電視開啟時，系統會啟用自動化動作，但只有在「時間介於日落和日出之間」的條件滿足時，系統才會執行自動化動作。

除了基本結構之外，Home API 中的自動化動作還包含中繼資料，例如名稱和說明，可供開發人員和使用者識別。

節點

在 Google Home API 中，自動化動作的邏輯結構由nodes組成。節點是可重複使用的抽象單位，用來代表實體行為或執行流程。每個節點都可以有輸入變數，以及其他節點可能會消耗的輸出變數。

行為節點

啟動條件和動作等節點屬於行為節點。Starter 會根據裝置屬性變更啟用自動化動作。動作會發出裝置指令或更新屬性。

行為節點通常會與裝置特徵和輸出特徵狀態綁定，以便做為其他節點的輸入內容。

執行流程節點

部分節點代表執行流程，例如順序和平行。每個節點都包含定義自動化動作的行為節點。

舉例來說，順序流程可能包含依序執行的節點。通常是啟動條件、限制條件和動作。

平行流程可能會同時執行多個動作節點，例如同時開啟多盞燈。並行流程的所有分支都完成後，才會執行並行流程的節點。

另一種執行流程是條件流程，可根據運算式的評估結果變更執行流程。

舉例來說，假設你有一個自動化動作，會根據是否為夜間執行動作。條件節點會檢查當天的時間，然後根據該評估結果，遵循適當的執行路徑。

如果您希望啟動自動化動作時，可以使用多個啟動條件，選取流程就很實用。如果在 select 流程中包含兩個以上的啟動條件，任何一個啟動條件都能啟用自動化動作。

舉例來說，如果溫度或亮度超過特定門檻，您可以編寫自動化動作，在日落時降低百葉窗。三個個別的啟動條件會處理上述每個情況，且三者都會包裝在 select 流程中。

巢狀流程

在複雜的自動化動作中，執行流程節點也可以巢狀。舉例來說，您可能會有執行平行流程的順序流程。

您可以根據下表所述的限制，以各種方式巢狀嵌套及結合 DSL 節點，以滿足特定需求。「Builder」欄連結至 Kotlin 型別安全建構工具說明文件，其中詳細說明可在各類型節點中使用的內容。

自動化 DSL

在 Google Home API 中，自動化動作會使用自動化動作 DSL (特定領域語言) 定義。自動化 DSL 會以 Kotlin DSL (網域專屬語言) 的形式實作，使用 Kotlin 型別安全建構工具，並專門用於定義自動化範本。

自動化功能編譯時，Kotlin 型別安全建構工具會產生 Kotlin 資料類別，然後將其序列化為用於呼叫 Google 自動化服務的通訊協定緩衝區 JSON。

Automation DSL 可簡化並精簡建構自動化動作的程序。它會原生使用 Device API 中 Matter 標準特徵和 smart home 特徵的相同資料模型。

自動化 DSL 也會根據抽象裝置類型定義自動化邏輯，而非使用者家中的特定裝置例項。這可讓開發人員提供輸入參數，以便在執行階段指定實際裝置例項，以及其他重要的參數值。

DSL 語法與 Kotlin 相似，同樣具有類型安全性，但使用 Automation DSL 編寫的自動化動作比使用純 Kotlin 編寫的相同自動化動作更簡單、更精簡。

範例

以下是使用自動化動作 DSL 編寫的自動化動作範例，可開啟裝置：

val automation = automation {
  name = "MyFirstAutomation"
  description = "If light1 is on, turn on light2."
  isActive = true
  sequential {
    val onOffTrait = starter<_>(device1, OnOffLightDevice, OnOff)
    condition() { expression = onOffTrait.onOff equals true }
    action(device2, OnOffLightDevice) { command(OnOff.on()) }
  }
}

這個自動化動作非常簡單：當 device1 (燈) 開啟 (onOff 屬性變更為 true) 時，系統會傳送 on() 指令來開啟 device2。

自動化動作會使用 sequential 節點，表示其節點會依序執行。

sequential 節點內含行為節點，例如 starter、condition 和 action。starter 節點的輸出內容會指派給變數，以便在 condition 節點中使用。