نظرة عامة على Automation API على Android

عمليات التشغيل الآلي هي طريقة لتنفيذ المهام وإعدادات الأجهزة في المنزل بشكل آلي. تتوفّر عمليات التشغيل الآلي في منظومة Google Home المتكاملة كسلاسل إجراءات في Google Home app (GHA) ومن خلال automation script editor على Google Home for web.

أصبحت الآن عمليات التشغيل الآلي في منظومة Google Home متوفّرة من خلال Home API لنظام Android. تستخدم هذه الإجراءات المفاهيم الأساسية نفسها المستخدَمة في سلاسل إجراءات GHA وscript editor، ولكن مع ميزات وإمكانات محسّنة لا يمكن توفيرها إلا من خلال واجهات برمجة تطبيقات Home، بما في ذلك:

• الوصول إلى جميع سمات Matter العادية وsmart home لجهاز معيّن، كما هو موضّح في Home APIs
• دعم مسارات التنفيذ المتسلسلة والمتوازية والمحددة

تتم كتابة عمليات التشغيل الآلي باستخدام لغة DSL الخاصة بالتشغيل الآلي، وهي لغة خاصة بالنطاق مصمّمة لإنشاء عمليات التشغيل الآلي في Kotlin.

يجب تسجيل أي سمات وأنواع تنوي استخدامها في تطبيقك مع Device & Structure API أو Automation API عند الإعداد. يُرجى الاطّلاع على تهيئة المنزل على Android.

إرشادات في حال ألغى المستخدم الأذونات الكاملة

إذا ألغى المستخدم الأذونات الكاملة، ستتوقف جميع عمليات التشغيل الآلي الحالية عن العمل. بالإضافة إلى ذلك، إذا ألغى المستخدم إمكانية الوصول إلى أجهزة معيّنة، ستتوقف إجراءات التفعيل والشروط والإجراءات المرتبطة بهذه الأجهزة عن العمل.

في كل مرة يبدأ فيها التطبيق، تأكَّد من أنّ الأذونات لا تزال سارية. وإذا تم إبطالها، تأكَّد من إزالة جميع البيانات السابقة، بما في ذلك أي بيانات مخزّنة مؤقتًا في التطبيق.

عند إبطال إذن الوصول إلى البنية، يتم إرسال StructureAccessRevokedEvent إلى الخلفية السحابية. يُرجى الرجوع إلى بنية الأذونات للاطّلاع على سير العمل الشامل لإلغاء أذونات التطبيقات المتوافقة مع الأجهزة الجوّالة والسحابة الإلكترونية التابعة للشركاء.

رحلة المطوّر

تُعدّ Automation API جزءًا من رحلة تطوير أكبر. ويأتي ذلك بعد دمج واجهات برمجة التطبيقات Structure وDevice لضمان إمكانية استخدام المستخدم لعملية التشغيل الآلي عندما يريد ذلك.

1. يخطّط المطوّر لعملية التشغيل الآلي ويحدّدها باستخدام لغة DSL للتشغيل الآلي.
2. يُضمِّن المطوّر تعريف التشغيل الآلي في تطبيق Android بلغة Kotlin.
3. يعرض التطبيق مهام التشغيل الآلي للمستخدم استنادًا إلى معلومات عن أجهزته، بما في ذلك السمات والخصائص والأوامر والأحداث التي يتم جمعها باستخدام Discovery API أو Device API.
   1. باستخدام Discovery API، يمكن للتطبيق إنشاء مسودة لعملية تشغيل آلي مخصّصة لأنواع الأجهزة والسمات المتوفّرة في بنية المستخدم، سواء بإدخال المستخدم أو بدونه.
   2. يمكن أن توفّر Device API معظم المعلومات نفسها التي توفّرها Discovery API، ولكنّها غير محسّنة لحالات الاستخدام المتعلّقة بالتشغيل الآلي. لمزيد من التفاصيل، يمكنك الاطّلاع على مقارنة بين Device API وDiscovery API.
4. ينشئ التطبيق عملية التشغيل الآلي الفعلية المرتبطة بالبنية المحدّدة.
5. أصبحت عملية التشغيل الآلي متاحة الآن في بنية المستخدم ويمكن تنفيذها أو حذفها باستخدام طرق واجهة برمجة التطبيقات Structure API.

يمكن للمستخدم إنشاء نُسخ جديدة من عملية التشغيل الآلي في أي وقت، واختيار بنية مختلفة أو مجموعة مختلفة من الأجهزة، حسب منطق التطبيق. في كل مرة يفعلون ذلك، ينشئ التطبيق مثيلًا جديدًا للأتمتة.

في السيناريو الأساسي، يمكنك أن تقترح على المستخدمين إجراءً آليًا محدّدًا مسبقًا ينفّذ مهمة أساسية نسبيًا. بدلاً من ذلك، يمكنك تقديم هيكل لعملية تشغيل آلي يخصّصها المستخدم لتلبية احتياجاته. أو يمكنك كتابة محرِّر مهام آلي مفتوح يتيح للمستخدم إنشاء مهام آلية معقّدة باستخدام جميع العناصر الأساسية المتاحة في Automation API.

إنشاء مهام التشغيل الآلي وإدارتها

لإنشاء عمليات التشغيل الآلي وإدارتها على Android، اتّبِع الخطوات التالية:

1. سجِّل جميع أنواع الأجهزة والسمات التي تشير إليها عمليات التشغيل الآلي في FactoryRegistry التي تم تمريرها إلى HomeConfig أثناء إعداد حزمة تطوير البرامج (SDK). للاطّلاع على تفاصيل التسجيل، يُرجى الاطّلاع على إعداد المنزل على Android.
2. يمكنك إنشاء DraftAutomation (BaseAutomation) باستخدام automation() DSL واستدعاء طرق HasAutomations المعيارية على كائن Structure:
   • اتصل بـ createAutomation() لإنشاء عملية تشغيل آلي في البنية.
   • يمكنك استدعاء automations() لإدراج أو استرداد عمليات التشغيل الآلي التي أنشأها تطبيقك في البنية.
   • يمكنك استدعاء update() في مثيل Automation لتعديل بياناته الوصفية أو استبدال automationGraph.
   • استخدِم deleteAutomation() لإزالة عملية تشغيل آلي باستخدام رقم التعريف.

val draft = automation {
  name = "Turn on light"
  description = "Turn on light2 when light1 turns on."
  sequential {
    val starterNode = starter<_>(light1, OnOffLightDevice, OnOff)
    condition { expression = starterNode.onOff equals true }
    action(light2, OnOffLightDevice) { command(OnOff.on()) }
  }
}

val createdAutomation = structure.createAutomation(draft)

للاطّلاع على بنية DSL الكاملة وأمثلة على رموز CRUD، يُرجى الاطّلاع على إنشاء عملية تشغيل آلي على Android.

اقتراحات التشغيل الآلي

   التنفيذ في نموذج التطبيق لنظام التشغيل Android   

يمكن أن تقترح واجهات برمجة التطبيقات Home API عمليات تشغيل آلي لـ Structure استنادًا إلى عوامل مثل أنواع الأجهزة المتوفّرة في المساحة.

يتم تمثيل اقتراحات التشغيل الآلي من خلال الفئة AutomationSuggestion.

تتضمّن واجهة Structure واجهة HasSuggestions التي توفّر دالة suggestions() التي تعرض مجموعة من اقتراحات التشغيل الآلي.

إنّ الطريقتَين likeSuggestion() وdislikeSuggestion() مخصّصتان للربط بعناصر التحكّم في واجهة المستخدم thumb_up وthumb_down التي يمكن للمستخدم النقر عليها لتقديم ملاحظات.

تتيح الطريقة الثالثة، clearSuggestionFeedback()، للمستخدم إزالة ملاحظاته حول عملية تشغيل آلي مقترَحة.

تؤثر ملاحظات المستخدمين في الاقتراحات المستقبلية.

يوضّح هذا المثال كيفية استرداد اقتراحات التشغيل الآلي المتاحة لـ Structure، واستخراج معرّف اقتراح، وتسجيل ملاحظات المستخدمين باستخدام 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 في وقت التشغيل.

آلية عمل المَعلمات الديناميكية

في لغة DSL الخاصة ببرنامج التشغيل الآلي على Android، تقبل مَعلمات الأوامر مثيلات Expression أو Reference مباشرةً بدلاً من القيم الثابتة. تغلّف لغة DSL هذه العناصر في تعريفات Parameter عند إنشاء عملية التشغيل الآلي.

قواعد التحقّق من الصحة

تتّبع مَعلمات الأوامر الديناميكية قيود التحقّق التالية:

• يُفترض أن تكون المَعلمات الديناميكية صالحة من الناحية الهيكلية أثناء عملية الاكتشاف، لأنّ واجهات برمجة التطبيقات الخاصة بالاكتشاف لا تقيّم سوى قيود القيم الملموسة للوسيطات الثابتة.
• يجب أن تظهر عُقد المراجع أو التعبيرات في أعلى الرسم البياني للتشغيل الآلي قبل الإشارة إليها في إجراء أمر في أسفل الرسم البياني.

استخدام مَعلمات الطلبات الديناميكية على 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 APIs: