Android 上的 Automation API 總覽

自動化動作可自動執行住家中的工作和裝置設定。 Google Home 生態系統已提供自動化功能，使用者可透過 Google Home app (GHA) 中的日常安排和 Google Home for web 上的 automation script editor 使用這項功能。

現在，Google Home 生態系統中的自動化動作可透過 Android 適用的 Home API 使用。這些功能與GHA日常安排和script editor使用的基本概念相同，但透過 Google Home API 提供的強化功能和服務，可實現以下目標：

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

自動化動作是使用 Automation DSL 編寫而成，這是一種專為在 Kotlin 中建構自動化動作而設計的領域特定語言。

如要在應用程式中使用裝置和結構體或自動化 API，必須在初始化時註冊所有特徵和型別。請參閱「在 Android 裝置上初始化住家」。

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

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

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

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

開發人員歷程

自動化 API 是大型開發歷程的一部分。整合 Structure 和 Device API 後，即可確保使用者在想使用自動化動作時，能夠順利操作。

  1. 開發人員規劃自動化作業，並使用 Automation 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 中的所有建構區塊，建構複雜的自動化程序。

自動化動作建議

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 的 Automation 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
下一頁
設計自動化動作