複雜自動化動作的 Android DSL 指南

自動化 DSL 可用於建立比Android 上的基本自動化動作更複雜的自動化動作。

依序執行多項動作

自動化動作可以執行多項操作。舉例來說，您可以有多個 action 節點，而非單一 action 節點，這些節點會依序執行：

automation {
  sequential {
    starter<_>(...)
    condition {...}
    action {...}
    action {...}
    action {...}
    }
}

循序執行多項平行動作

如果在 parallel 節點中放置多個 action 節點，系統會同時執行動作。

automation {
  sequential {
    starter<_>(...)
    condition {...}
    parallel {
      action {...}
      action {...}
      action {...}
    }
  }
}

如果 sequential 節點中有 action 節點位於 parallel 節點之後，則這些節點會等待，直到 parallel 節點中的所有節點都執行完畢，才會開始執行。

延遲入帳

您可以使用 delayFor 關鍵字在自動化程序中加入暫停，這個關鍵字會採用 java.time.Duration 引數，代表暫停多久後繼續執行。暫停時間最短為 5 秒，最長為 24 小時。

舉例來說，如要切換燈光四次，每次切換間隔五秒，請執行下列操作：

sequential {
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
  delayFor(Duration.ofSeconds(5))
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
  delayFor(Duration.ofSeconds(5))
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
  delayFor(Duration.ofSeconds(5))
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
}

觸發條件抑制

觸發條件抑制功能可讓自動化動作在初始觸發事件發生後，於指定時間內忽略 starter。舉例來說，如果自動化動作的 starter 是由動作偵測觸發，且你指定五分鐘的觸發抑制時間，那麼 starter 觸發後，接下來五分鐘內不會再次觸發。這樣可避免自動化功能快速重複觸發。

如要對自動化動作套用觸發條件抑制功能，請使用 suppressFor 關鍵字，並搭配 java.time.Duration 引數，代表在回應後續觸發條件前要等待的時間長度。封鎖時間最短為 5 秒，最長為 24 小時。

automation {
  sequential {
    val starterNode = starter<_>(device, OccupancySensor, MotionDetection)
    suppressFor(Duration.ofMinutes(30))
    action(light, OnOffLightDevice) { command(OnOff.toggle()) }
}

請注意，觸發條件抑制功能會影響自動化動作中所有位於 suppressFor 前的 starters。

限制執行次數

您可以限制自動化動作的執行次數。

舉例來說，你可能想設定一次性自動化動作，在白天外出時執行吸塵器。

如要執行這項操作，請設定自動化功能的 maxExecutionCount 中繼資料欄位。以下範例是只能執行一次的自動化動作：

automation {
  // The automation can only be executed once.
  maxExecutionCount = 1
  // When the door lock state changes
  sequential {
    val doorLockEvent = starter<_>(doorLock, DoorLockDevice, LockOperationEvent)
    // if the door is unlocked
    condition() {
      expression = (doorLockEvent.lockOperationType equals LockOperationTypeEnum.Unlock)
    }
    // turn the light on
    action(light, DimmableLightDevice) { command(OnOff.on()) }
  }
}

自動化動作最後一次執行完畢並達到 maxExecutionCount 次後，就會立即刪除。自動化動作的記錄項目仍會保留在「活動」Google Home app (GHA)分頁中，包括 automation_id。

在動作中設定特徵屬性

如要設定特徵屬性的值，請按照下列步驟操作：

1. 在 action 節點中建立 update 節點，並將相關特徵做為 update 節點的引數：

   action(deviceReference, deviceType) {
     update(trait) {
   
     }
   }

2. 在 update 節點中，針對要修改的每個屬性， 使用變異函式，並傳遞新值。 如要建立變動器函式的名稱：
   1. 將屬性名稱設為大寫
   2. 在開頭加上「set」一詞。
   舉例來說，如要更新名為 defaultMoveRate 的屬性， 請使用名為 setDefaultMoveRate 的變動函式。

請注意，update 節點可以有多個變異函式。以下範例顯示如何更新兩個屬性：

action(device, Fan) {
  update(FanControl) {
    setPercentSetting(50u)
    setRockSetting(FanControlCluster.RockBitmap.rockUpDown)
  }
}