Android 上的 Automation API 總覽

自動化動作可自動執行住家中的工作和裝置設定。 Google Home 生態系統中的自動化動作，在 Google Home app (GHA) 中稱為日常安排，在 Google Home for web 中則可透過 automation script editor 執行。

現在，您可以透過 Home API for Android，在 Google Home 生態系統中使用自動化動作。這些動作與 GHA 日常安排和 script editor 採用相同的基本概念，但具備只有 Home API 才能提供的強化功能，包括：

  • 存取裝置的所有 Matter 標準和 smart home 特性，如 Home API 所示。
  • 支援依序、平行和選取執行流程。

自動化動作是以自動化 DSL 編寫，這是一種網域專屬語言，專為在 Kotlin 中建構自動化動作而設計。

如要在應用程式中搭配使用 Device & Structure API 或 Automation API，則必須在初始化時註冊任何特徵和類型。請參閱「在 Android 上初始化住家」。

使用者撤銷完整權限時的指引

如果使用者撤銷完整權限，所有現有自動化動作都會停止運作。此外，如果使用者撤銷特定裝置的存取權，與這些裝置相關聯的啟動條件、限制條件和動作就會停止運作。

每次應用程式啟動時，請務必檢查權限是否仍有效。如果權限已撤銷，請務必移除所有先前的資料，包括應用程式中快取的任何資料。

當住家結構體存取權遭到撤銷時，系統會將 StructureAccessRevokedEvent 傳送至雲端後端。如要瞭解端對端合作夥伴雲端和行動應用程式撤銷工作流程，請參閱「住家結構體授權」。

開發人員旅程

Automation API 只是開發過程中的一環。整合 Structure 和 Device API 後，請務必確保使用者能順利使用自動化動作。

  1. 開發人員規劃自動化動作，並使用自動化動作 DSL 定義。
  2. 開發人員將自動化動作定義嵌入 Kotlin Android 應用程式。
  3. 應用程式會根據使用者的裝置資訊 (包括特徵、屬性、指令和事件)，向使用者顯示自動化動作。這些資訊是透過 Discovery API 或 Device API 收集。
    1. 透過 Discovery API，應用程式可以根據使用者住家結構中的裝置類型和特徵，產生自訂的自動化動作草稿，無論使用者是否輸入內容皆可。
    2. Device API 可提供與 Discovery API 大致相同的資訊，但並未針對自動化用途進行最佳化。詳情請參閱「比較 Device API 和 Discovery API」。
  4. 應用程式會建立實際的自動化動作，並與所選住家結構建立關聯。
  5. 自動化動作現在可在使用者的結構中使用，並可透過 Structure API 方法執行或刪除。

使用者可以隨時建立新的自動化動作例項，並選取不同的住家結構，或根據應用程式邏輯，選取不同的裝置組合。每次執行時，應用程式都會產生新的自動化動作例項。

在最基本的情況下，您可以向使用者建議預先定義的自動化動作，執行相對基本的任務。或者，您也可以提供自動化動作的基本架構，讓使用者根據需求自訂。或者，您也可以編寫開放式自動化動作編輯器，讓使用者運用 Automation API 中所有可用的建構模塊，建構複雜的自動化動作。

自動化動作建議

   在 Android 範例應用程式中導入   

Home API 可根據空間中的裝置類型等因素，為 Structure 建議自動化動作。

自動化動作建議由 AutomationSuggestion 類別表示。

Structure 介面包含 HasSuggestions 介面，後者提供 suggestions() 函式，可傳回自動化建議集合。

likeSuggestion() 和 dislikeSuggestion() 方法應連結至 和 UI 控制項，使用者輕觸這些控制項即可提供意見回饋。

第三種方法 clearSuggestionFeedback() 可讓使用者移除對建議自動化動作的意見回饋。

使用者意見回饋會影響日後的建議。

這個範例說明如何擷取 Structure 的可用自動化建議、擷取建議 ID，以及使用 likeSuggestion()、clearSuggestionFeedback() 和 dislikeSuggestion() 記錄使用者意見回饋。

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.google.home.Structure
import kotlinx.coroutines.launch

class AutomationSuggestionsViewModel(private val structure: Structure) : ViewModel() {

  fun loadAndGiveFeedback() {
    viewModelScope.launch {
      // 1. Fetch suggestions from structure
      val suggestions = structure.suggestions()
      val firstSuggestion = suggestions.firstOrNull() ?: return@launch

      // Extract string suggestion ID
      val suggestionId: String = firstSuggestion.id.id

      // 2. Like the suggestion (thumbs up)
      val liked = structure.likeSuggestion(suggestionId)

      // 3. Clear previous feedback if the user toggled it off
      if (liked) {
        structure.clearSuggestionFeedback(suggestionId)
      }

      // 4. Dislike the suggestion (thumbs down)
      structure.dislikeSuggestion(suggestionId)
    }
  }
}

動態指令參數

開發人員可使用動態指令參數建構動作參數，在執行階段動態解析，而不必完全依賴靜態常數值。這項功能主要有兩大用途：

  • 從啟動條件 (例如事件酬載) 或狀態讀取器節點，或從自動化動作流程中宣告的本機變數，傳遞屬性值的參照。
  • 擷取執行階段動態值 (例如事件屬性或狀態值)，並將動態值直接傳遞至指令參數的運算式。

用途

將傳送多重按壓事件的實體旋轉開關，繫結至可調光燈具。點擊次數是執行階段傳入 LevelControl 步驟指令的動態值。

動態參數的運作方式

在 Android 的自動化 DSL 中，指令參數會直接接受 Expression 或 Reference 執行個體，而非靜態常數值。建構自動化動作時，DSL 會將這些動作封裝成 Parameter 定義。

驗證規則

動態指令參數須遵守下列驗證限制：

  • 探索期間，系統會假設動態參數的結構有效，因為探索 API 只會評估靜態引數的具體值限制。
  • 參照或運算式節點必須出現在自動化動作圖的上游，才能在下游指令動作中參照。

在 Android 上使用動態指令參數

直接將動態運算式傳遞至指令參數：

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val keypressAutomation = automation {
  name = "Dynamic command parameters example"
  description = "Pass starter event field directly to command"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountExpr,
        )
      )
    }
  }
}

或者，您也可以將運算式指派給區域變數宣告，並在流程中稍後參照該變數：

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.automation.variable
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val myAutomationWithVariable = automation {
  name = "Dynamic command parameters with variables"
  description = "Declare a variable, assign value, and pass reference"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    val clickCountVar = variable<UInt>()
    clickCountVar.assign(clickCountExpr)

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountVar,
        )
      )
    }
  }
}

類型限制

確認變數和運算式的類型與接收指令參數所需的 Matter 結構定義類型定義 (例如 UShort、UByte 或 UInt8) 一致。

資源限制

Home API 的自動化動作有以下限制：

表格：Automation API 資源限制
指標 限制
每個住家結構體的自動化動作數量上限 64
每個自動化動作的節點數量上限 128
每個自動化動作的運算式節點數量上限 64
每個住家結構體的自動化動作執行個體數量上限 1024
每位開發人員在每個住家結構體中可建立的自動化動作執行個體數量上限 64
每個住家結構體每天的執行次數上限 1024
每位開發人員在每個住家結構體，每日可執行的動作數量上限 128
下一頁
設計自動化動作