Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Android の Automation API の概要

自動化は、家の中のタスクやデバイスの設定を自動化する方法です。自動化は、Google Home エコシステムでは Google Home app (GHA) のルーティンとして、また Google Home for web の automation script editor を通じて利用できます。

Google Home エコシステムの自動化が、Android 向け Home API で利用できるようになりました。GHA ルーティンと script editor で使用されているのと同じ基本コンセプトを使用しますが、Home API でのみ実現可能な拡張機能と機能が追加されています。

Home API に表示される、デバイスのすべての Matter 標準トレイトと smart home トレイトへのアクセス。
シーケンシャル、パラレル、セレクトの実行フローをサポート。

自動化は、Kotlin で自動化を構築するために設計されたドメイン固有言語である Automation DSL を使用して記述されます。

Device & Structure API または Automation API を使用してアプリで使用する特性とタイプは、初期化時に登録する必要があります。Android で家を初期化するをご覧ください。

ユーザーがすべての権限を取り消した場合のガイダンス

ユーザーが完全な権限を取り消すと、既存の自動化はすべて機能しなくなります。また、ユーザーが特定のデバイスへのアクセスを取り消すと、それらのデバイスに関連付けられている開始条件、条件、アクションは機能しなくなります。

アプリを起動するたびに、権限がまだ有効であることを確認してください。取り消された場合は、アプリケーションにキャッシュされたデータを含め、以前のデータがすべて削除されていることを確認してください。

ストラクチャへのアクセスが取り消されると、StructureAccessRevokedEvent がクラウドバックエンドに配信されます。エンドツーエンドのパートナークラウドとモバイルアプリの取り消しワークフローについては、ストラクチャの権限付与をご覧ください。

デベロッパーが実施する手順

Automation API は、より大きな開発プロセスの一部です。これは、Structure API と Device API を統合した後に行い、ユーザーが自動化を使用したいときに使用できるようにします。

デベロッパーは自動化を計画し、Automation DSL を使用して定義します。
デベロッパーは、Kotlin Android アプリに自動化定義を埋め込みます。
アプリは、Discovery API または Device API を使用して収集されたデバイスに関する情報（トレイト、属性、コマンド、イベントなど）に基づいて、自動化をユーザーに提示します。
1. Discovery API を使用すると、アプリは、ユーザーの入力の有無にかかわらず、ユーザーのストラクチャに存在するデバイスタイプとトレイトに合わせてカスタマイズされた自動化の下書きを生成できます。
2. Device API は、Discovery API とほぼ同じ情報を提供できますが、自動化のユースケース向けに最適化されていません。詳細については、Device API と Discovery API の比較をご覧ください。
アプリは、選択したストラクチャに関連付けられた実際の自動化を作成します。
この自動化はユーザーのストラクチャで利用できるようになり、Structure API メソッドを使用して実行または削除できます。

ユーザーは、いつでも自動化の新しいインスタンスを作成できます。その際、別のストラクチャを選択したり、アプリのロジックに応じて別のデバイスセットを選択したりできます。そのたびに、アプリは自動化の新しいインスタンスを生成します。

最も基本的なシナリオでは、比較的基本的なタスクを実行する事前定義された自動化をユーザーに提案できます。または、ユーザーがニーズに合わせてカスタマイズできる自動化のスケルトンを提示することもできます。また、Automation API で利用可能なすべてのビルディングブロックを使用して、ユーザーが複雑な自動化を構築できる、オープンエンドの自動化エディタを作成することもできます。

自動化の提案

Android 向けサンプルアプリに実装済み

Home API は、スペースに存在するデバイスの種類などの要素に基づいて、Structure の自動化を提案できます。

自動化の候補は AutomationSuggestion クラスで表されます。

Structure インターフェースには、HasSuggestions インターフェースが含まれています。このインターフェースは、自動化の候補のコレクションを返す suggestions() 関数を提供します。

likeSuggestion() メソッドと dislikeSuggestion() メソッドは、ユーザーがタップしてフィードバックを提供できる UI コントロールと UI コントロールに接続することを目的としています。

3 つ目のメソッド 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)
    }
  }
}

動的コマンドパラメータ

動的コマンドパラメータを使用すると、デベロッパーは、静的な定数値に厳密に依存するのではなく、実行時に動的に解決されるアクションパラメータを構築できます。これにより、主に次の 2 つの機能が実現します。

スターター（イベントペイロードなど）または状態リーダーノードから、または自動化フロー内で宣言されたローカル変数から、プロパティの値を渡す参照。
ランタイムの動的な値（イベントプロパティや状態値など）を取得し、その動的な値をコマンドパラメータに直接渡す式。

ユースケース

マルチプレスイベントを送信する物理的なロータリースイッチを、調光可能なライトにバインドします。クリック数は、実行時に 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
1 日あたりのストラクチャごとの最大実行数	1024
デベロッパーごと、ストラクチャごと、1 日あたりの最大実行回数	128

自動化を設計する