Android の Automation API の概要

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

Google Home エコシステムの自動化は、Android 用 Home API を通じて利用できるようになりました。 GHAルーティンとscript editorで使用されているものと同じ基本コンセプトを使用していますが、 Home API を通じてのみ可能な機能が強化されています。 たとえば、次のような機能があります。

• Home API に表示される、デバイスのすべての Matter 標準トレイトと smart home トレイトにアクセスできます。
• 順次実行、並列実行、選択実行フローをサポートしています。

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

デバイスと構造 API または Automation API を使用してアプリで使用するトレイトとタイプは、初期化時に登録する必要があります。Android でホームを初期化するをご覧ください。

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

ユーザーがすべての権限を取り消すと、既存の自動化はすべて停止します。また、ユーザーが特定のデバイスへのアクセスを取り消すと、それらのデバイスに関連付けられたスターター、条件、アクションは停止します。

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

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

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

Automation API は、大規模な開発プロセスの 1 つの要素です。ユーザーが自動化を使用できるように、構造 API とデバイス API を統合した後に使用します。

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

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

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

自動化の提案

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

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

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

likeSuggestion() と dislikeSuggestion() メソッドは、ユーザーがタップしてフィードバックを提供できる thumb_upと thumb_downの 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)
    }
  }
}

リソースに関する上限

Home API の自動化には、次の上限が適用されます。