Automation API unter Android – Übersicht

Automatisierte Abläufe sind eine Möglichkeit, Aufgaben und Geräteeinstellungen in einem Zuhause zu automatisieren. Sie sind im Google Home-Ökosystem als Abläufe in der Google Home app (GHA) und über den automation script editor auf Google Home for web verfügbar.

Jetzt sind automatisierte Abläufe im Google Home-Ökosystem über die Home APIs für Android verfügbar. Sie verwenden dieselben grundlegenden Konzepte wie GHA Abläufe und der script editor, bieten aber erweiterte Funktionen und Möglichkeiten, die nur über die Home APIs möglich sind, darunter:

• Zugriff auf alle Matter Standard- und smart home Merkmale für ein Gerät, wie in den Home APIs dargestellt.
• Unterstützung für sequenzielle, parallele und ausgewählte Ausführungsabläufe.

Automatisierte Abläufe werden mit Automation DSL geschrieben, einer domänenspezifischen Sprache, die für die Erstellung von automatisierten Abläufen in Kotlin entwickelt wurde.

Alle Merkmale und Typen, die Sie in Ihrer App mit den Device &Structure APIs oder der Automation API verwenden möchten, müssen bei der Initialisierung registriert werden. Weitere Informationen finden Sie unter Zuhause unter Android initialisieren.

Anleitung, wenn der Nutzer alle Berechtigungen widerruft

Wenn der Nutzer alle Berechtigungen widerruft, funktionieren alle vorhandenen automatisierten Abläufe nicht mehr. Wenn der Nutzer den Zugriff auf bestimmte Geräte widerruft, funktionieren auch die mit diesen Geräten verknüpften Starter, Bedingungen und Aktionen nicht mehr.

Prüfen Sie bei jedem Start der App, ob die Berechtigungen noch gültig sind. Wenn sie widerrufen wurden, müssen alle vorherigen Daten entfernt werden, einschließlich aller in der Anwendung gespeicherten Daten.

Wenn der Zugriff auf die Struktur widerrufen wird, wird ein StructureAccessRevokedEvent an Ihr Cloud-Back-End gesendet. Weitere Informationen finden Sie unter Strukturzuweisungen für den End-to-End-Widerrufsablauf für Partner-Cloud und mobile App.

Entwicklerprozess

Die Automation API ist nur ein Teil eines größeren Entwicklungsprozesses. Sie wird nach der Einbindung der Structure API und der Device API verwendet, um sicherzustellen, dass ein Nutzer einen automatisierten Ablauf verwenden kann.

1. Der Entwickler plant den automatisierten Ablauf und definiert ihn mit Automation DSL.
2. Der Entwickler bettet die Definition des automatisierten Ablaufs in eine Kotlin-Android-App ein.
3. Die App präsentiert dem Nutzer automatisierte Abläufe basierend auf Informationen zu seinen Geräten, einschließlich Merkmalen, Attributen, Befehlen und Ereignissen, die mit der Discovery API oder der Device API erfasst wurden.
   1. Mit der Discovery API kann die App einen Entwurf für einen automatisierten Ablauf erstellen, der an die Gerätetypen und Merkmale in der Struktur des Nutzers angepasst ist, mit oder ohne Eingabe des Nutzers.
   2. Die Device API kann die meisten Informationen liefern, die auch die Discovery API liefert, ist aber nicht für Anwendungsfälle mit automatisierten Abläufen optimiert. Weitere Informationen finden Sie unter Device API und Discovery API vergleichen.
4. Die App erstellt den eigentlichen automatisierten Ablauf, der mit der ausgewählten Struktur verknüpft ist.
5. Der automatisierte Ablauf ist jetzt in der Struktur des Nutzers verfügbar und kann mit Methoden der Structure API ausgeführt oder gelöscht werden.

Der Nutzer kann jederzeit neue Instanzen des automatisierten Ablaufs erstellen und dabei eine andere Struktur oder je nach App-Logik möglicherweise eine andere Gruppe von Geräten auswählen. Jedes Mal, wenn er das tut, erstellt die App eine neue Instanz des automatisierten Ablaufs.

Im einfachsten Fall können Sie Ihren Nutzern einen vordefinierten automatisierten Ablauf vorschlagen, der eine relativ einfache Aufgabe ausführt. Alternativ können Sie ein Grundgerüst eines automatisierten Ablaufs präsentieren, das der Nutzer an seine Bedürfnisse anpassen kann. Oder Sie können einen offenen Editor für automatisierte Abläufe erstellen, mit dem der Nutzer komplexe automatisierte Abläufe mit allen in der Automation API verfügbaren Bausteinen erstellen kann.

Vorschläge für automatisierte Abläufe

Die Home APIs können automatisierte Abläufe für eine Structure basierend auf Faktoren wie den Gerätetypen im Raum vorschlagen.

Vorschläge für automatisierte Abläufe werden durch die AutomationSuggestion Klasse dargestellt.

Die Structure Schnittstelle umfasst die HasSuggestions Schnittstelle, die die suggestions() Funktion bereitstellt, die eine Sammlung von Vorschlägen für automatisierte Abläufe zurückgibt.

Die likeSuggestion() und dislikeSuggestion() Methoden sind für die Verknüpfung mit den thumb_up und thumb_down UI-Steuerelementen vorgesehen, die der Nutzer antippen kann, um Feedback zu geben.

Mit der dritten Methode, clearSuggestionFeedback(), kann der Nutzer sein Feedback zu einem vorgeschlagenen automatisierten Ablauf entfernen.

Nutzerfeedback beeinflusst zukünftige Vorschläge.

In diesem Beispiel wird gezeigt, wie Sie die verfügbaren Vorschläge für automatisierte Abläufe für eine Structureabrufen, eine Vorschlags-ID extrahieren und Nutzerfeedback mit likeSuggestion(), clearSuggestionFeedback() und dislikeSuggestion()aufzeichnen.

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)
    }
  }
}

Dynamische Befehlsparameter

Mit dynamischen Befehlsparametern können Entwickler Aktionsparameter erstellen, die zur Laufzeit dynamisch aufgelöst werden, anstatt sich ausschließlich auf statische, konstante Werte zu verlassen. Dies ermöglicht zwei Hauptfunktionen:

• Verweise, die den Wert einer Eigenschaft von einem Starter (z. B. einer Ereignisnutzlast) oder einem Knoten für den Statusleser oder von lokalen Variablen übergeben, die im automatisierten Ablauf deklariert wurden.
• Ausdrücke, die dynamische Werte zur Laufzeit (z. B. eine Ereigniseigenschaft oder einen Statuswert) erfassen und den dynamischen Wert direkt an einen Befehlsparameter übergeben.

Anwendungsfall

Verknüpfen Sie einen physischen Drehschalter, der ein Ereignis mit mehreren Klicks an eine dimmbare Lampe sendet. Die Anzahl der Klicks ist der dynamische Wert, der zur Laufzeit an einen LevelControl-Befehlsschritt übergeben wird.

Funktionsweise dynamischer Parameter

In Automation DSL unter Android akzeptieren Befehlsparameter Expression oder Reference Instanzen direkt anstelle von statischen konstanten Werten. Die DSL kapselt diese bei der Erstellung des automatisierten Ablaufs in Parameter Definitionen.

Validierungsregeln

Für dynamische Befehlsparameter gelten die folgenden Validierungseinschränkungen:

• Dynamische Parameter werden während der Erkennung als strukturell gültig angenommen, da Erkennungs-APIs nur konkrete Werteinschränkungen für statische Argumente auswerten.
• Verweis- oder Ausdrucksknoten müssen im Diagramm des automatisierten Ablaufs vor einem Befehl im weiteren Verlauf vorhanden sein, bevor auf sie in einer Befehlsaktion im weiteren Verlauf verwiesen wird.

Dynamische Befehlsparameter unter Android verwenden

Übergeben Sie dynamische Ausdrücke direkt an Befehlsparameter:

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,
        )
      )
    }
  }
}

Alternativ können Sie einen Ausdruck einer lokalen Variablendeklaration zuweisen und später im Ablauf auf die Variable verweisen:

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,
        )
      )
    }
  }
}

Typeinschränkungen

Achten Sie darauf, dass die Typen von Variablen und Ausdrücken mit der erforderlichenMatter Schemadefinition des empfangenden Befehlsparameters übereinstimmen (z. B. UShort, UByte, oder UInt8).

Ressourcenlimits

Für automatisierte Abläufe in den Home APIs gelten die folgenden Limits: