دليل Android DSL للعمليات المبرمَجة المعقّدة

يمكن استخدام لغة النطاق الخاصة بالأتمتة لإنشاء عمليات أتمتة أكثر تعقيدًا من تلك التي تم تناولها في دليل لغة النطاق الخاصة بالأتمتة - عمليات الأتمتة الأساسية على Android.

عمليات متسلسلة تتضمّن إجراءات متعددة

يمكن أن تنفّذ عملية الأتمتة أكثر من إجراء واحد. على سبيل المثال، بدلاً من عُقدة action واحدة، يمكنك استخدام عُقد action متعددة يتم تشغيلها بترتيب تسلسلي:

automation {
  sequential {
    starter<_>(...)
    condition {...}
    action {...}
    action {...}
    action {...}
    }
}

عمليات متسلسلة تتضمّن إجراءات متوازية متعددة

إذا وضعت عُقد action متعددة في عُقدة parallel، يتم تنفيذ الإجراءات في الوقت نفسه.

automation {
  sequential {
    starter<_>(...)
    condition {...}
    parallel {
      action {...}
      action {...}
      action {...}
    }
  }
}

إذا كانت هناك عُقد action في عُقدة sequential تأتي بعد عُقدة parallel، تنتظر هذه العُقد حتى تنتهي جميع العُقد داخل عُقدة parallel من التنفيذ.

التنفيذ الشرطي

تنفّذ عملية الأتمتة العُقد بالتسلسل أو بالتوازي تلقائيًا. إذا كنت بحاجة إلى منطق تفرّع شرطي، أي تنفيذ إجراءات أو مسارات مختلفة استنادًا إلى شروط وقت التشغيل، استخدِم عبارات if-then-else، التي يتم إنشاؤها باستخدام عُقد لغة النطاق الخاصة بالتحكّم في التدفق الشرطي: ifThen، elseIf، و orElse.

في حين أنّ عُقدة condition عادية تتحكّم في عملية التشغيل الآلي بأكملها (إذا كانت قيمة الشرط false، يتم إنهاء تنفيذ عملية التشغيل الآلي على الفور)، تتيح عُقد ifThen التحكّم في تدفق التفرّع:

• عُقدة condition: توقف تنفيذ عملية الأتمتة بأكملها (أو مسار التنفيذ الحالي) إذا كانت قيمة التعبير false.
• ifThen / elseIf / orElse: يتم تقييم الشروط بالترتيب. إذا كانت قيمة الشرط false، ينتقل التنفيذ إلى فرع elseIf التالي أو فرع orElse الاحتياطي أو يستمر إلى العُقد اللاحقة في عملية الأتمتة إذا لم يتم استيفاء أي شرط.

تنفيذ إجراء استنادًا إلى شرط

تقيِّم عُقدة ifThen تعبيرًا شرطيًا. إذا كانت قيمة التعبير true، يتم تنفيذ إجراءات لغة النطاق الخاصة بالأتمتة أو العُقد المُضمّنة داخل العُقدة. إذا كانت قيمة التعبير false، يتم تخطّي الإجراءات وتستمر عملية الأتمتة إلى العُقد اللاحقة في التدفق التسلسلي.

يمكنك استخدام عُقدة ifThen مستقلة عندما تريد تنفيذ إجراء بشكلٍ شرطي فقط بدون حظر العُقد اللاحقة في عملية الأتمتة أو إنهاء تنفيذها:

// When a door opens, turn on the light only if it is off,
// and always broadcast an announcement.
automation {
  sequential {
    val contactState = starter<_>(
      contactSensor,
      ContactSensorDevice,
      BooleanState,
    )
    val lightState = stateReader<_>(
      light,
      DimmableLightDevice,
      OnOff,
    )

    condition {
      // Door opened (contact sensor open)
      expression = contactState.stateValue equals false
    }

    // Conditionally turn on the light if it's off
    ifThen(lightState.onOff equals false) {
      action(light, DimmableLightDevice) { command(OnOff.on()) }
    }

    // Continue executing subsequent actions in the sequential flow
    action(structure) {
      command(AssistantBroadcast.broadcast("The door was opened."))
    }
  }
}

تنفيذ إجراءات مختلفة استنادًا إلى شرط

لتنفيذ مجموعة واحدة من الإجراءات عندما يكون الشرط صحيحًا ومجموعة بديلة من الإجراءات عندما يكون الشرط غير صحيح، اربط العُقدة الاختيارية .orElse { ... } بعد ifThen(...) { ... }:

// When the door is unlocked, turn on the entryway light if it is off;
// otherwise, broadcast a welcome message.
automation {
  sequential {
    val doorLockEvent = starter<_>(
      doorLock,
      DoorLockDevice,
      LockOperationEvent,
    )
    val lightState = stateReader<_>(
      light,
      DimmableLightDevice,
      OnOff,
    )

    condition {
      expression =
        doorLockEvent.lockOperationType equals LockOperationTypeEnum.Unlock
    }

    ifThen(lightState.onOff equals false) {
      action(light, DimmableLightDevice) { command(OnOff.on()) }
    }.orElse {
      action(structure) {
        command(AssistantBroadcast.broadcast("Welcome home!"))
      }
    }
  }
}

ربط شروط متعددة بالتسلسل

يمكنك ربط عُقدة واحدة أو أكثر من عُقد .elseIf(...) { ... } الاختيارية لتقييم شروط متعددة بالتسلسل. يتم تنفيذ الفرع الأول الذي تكون قيمة الشرط فيه true، ويتم تخطّي جميع الفروع المتبقية. إذا لم تكن قيمة أي من الشروط true، يتم تنفيذ عُقدة .orElse { ... } اختيارية (إذا تم توفيرها):

// Adjust climate controls based on room temperature changes.
automation {
  sequential {
    val tempStarter = starter<_>(
      tempSensor,
      TemperatureSensorDevice,
      TemperatureMeasurement,
    )

    // If temperature is high (>= 28°C / 2800 mC), switch thermostat to Cool mode
    ifThen(tempStarter.measuredValue greaterThanOrEquals 2800) {
      action(thermostat, ThermostatDevice) {
        command(
          SimplifiedThermostat.setSystemMode(
            SimplifiedThermostatSystemModeEnum.Cool
          )
        )
      }
    }.elseIf(tempStarter.measuredValue lessThan 1800) {
      // If temperature is low (< 18°C / 1800 mC), switch to Heat mode
      action(thermostat, ThermostatDevice) {
        command(
          SimplifiedThermostat.setSystemMode(
            SimplifiedThermostatSystemModeEnum.Heat
          )
        )
      }
    }.orElse {
      // Otherwise, turn on the fan
      action(fan, FanDevice) {
        command(OnOff.on())
      }
    }
  }
}

التدفقات الشرطية المُضمّنة

يمكن تضمين العُقد الشرطية داخل عُقد ifThen أو elseIf أو orElse الأخرى، بالإضافة إلى دمجها مع عُقد parallel وdelayFor وstateReader.

تنفّذ عُقد ifThen وelseIf وorElse محتوياتها كتدفقات تسلسلية. يمكنك وضع أي عُقد تسلسلية داخل كل فرع، بما في ذلك عُقد action وstateReader وparallel وdelayFor وعُقد ifThen المُضمّنة.

التأخيرات

يمكنك إيقاف عمليات الأتمتة مؤقتًا باستخدام الكلمة الرئيسية delayFor ، التي تأخذ وسيطة java.time.Duration تمثّل مدة الإيقاف المؤقت قبل مواصلة التنفيذ. يمكن أن تكون مدة الإيقاف المؤقت خمس ثوانٍ أو 24 ساعة.

على سبيل المثال، لتبديل المصباح أربع مرات مع إيقاف مؤقت لمدة خمس ثوانٍ بين كل عملية تبديل:

sequential {
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
  delayFor(Duration.ofSeconds(5))
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
  delayFor(Duration.ofSeconds(5))
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
  delayFor(Duration.ofSeconds(5))
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
}

إيقاف المشغِّل

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

لتطبيق ميزة إيقاف المشغِّل على عملية الأتمتة، استخدِم الكلمة الرئيسية suppressFor مع وسيطة java.time.Duration تمثّل مدة الانتظار قبل الاستجابة للمشغِّلات اللاحقة. يمكن أن تكون مدة الإيقاف المؤقت خمس ثوانٍ أو 24 ساعة.

automation {
  sequential {
    val starterNode = starter<_>(device, OccupancySensor, MotionDetection)
    suppressFor(Duration.ofMinutes(30))
    action(light, OnOffLightDevice) { command(OnOff.toggle()) }
}

يُرجى العِلم أنّ ميزة إيقاف المشغِّل تؤثر في جميع starters في عملية الأتمتة التي تسبق suppressFor.

الحدّ من عدد عمليات التنفيذ

يمكنك الحدّ من عدد المرات المسموح فيها بتشغيل عملية الأتمتة.

على سبيل المثال، قد تريد إعداد عملية أتمتة لمرة واحدة لتشغيل المكنسة الكهربائية أثناء غيابك عن المنزل طوال اليوم.

لإجراء ذلك، اضبط حقل البيانات الوصفية لعملية maxExecutionCount الأتمتة. المثال التالي هو عملية تشغيل آلي لا يمكن تنفيذها إلا مرة واحدة:

automation {
  // The automation can only be executed once.
  maxExecutionCount = 1
  // When the door lock state changes
  sequential {
    val doorLockEvent = starter<_>(doorLock, DoorLockDevice, LockOperationEvent)
    // if the door is unlocked
    condition() {
      expression = (doorLockEvent.lockOperationType equals LockOperationTypeEnum.Unlock)
    }
    // turn the light on
    action(light, DimmableLightDevice) { command(OnOff.on()) }
  }
}

يتم حذف عملية الأتمتة على الفور بعد اكتمال تنفيذها للمرة الأخيرة والوصول إلى maxExecutionCount. يبقى سجلّ عملية الأتمتة في علامة التبويب Google Home app (GHA) النشاط في تطبيق Google Home، بما في ذلك automation_id.

ضبط سمات السمة في إجراء

لضبط قيمة سمة السمة:

1. أنشئ عُقدة update داخل عُقدة action، بما في ذلك السمة ذات الصلة كحجة لعُقدة update

   action(deviceReference, deviceType) {
     update(trait) {
   
     }
   }

2. داخل عُقدة update، لكل سمة سيتم تعديلها، استخدِم دالة معدِّلة، ومرِّر القيمة الجديدة إليها. لتكوين اسم الدالة المعدِّلة:
   1. استخدِم الأحرف الكبيرة في اسم السمة
   2. أضِف الكلمة set قبل الاسم.
   على سبيل المثال، لتعديل سمة باسم defaultMoveRate، استخدِم دالة معدِّلة باسم setDefaultMoveRate.

يُرجى العِلم أنّ عُقدة update يمكن أن تتضمّن دوال معدِّلة متعددة. في ما يلي مثال يتم فيه تعديل سمتَين:

action(device, Fan) {
  update(FanControl) {
    setPercentSetting(50u)
    setRockSetting(FanControlCluster.RockBitmap.rockUpDown)
  }
}