أساسيات اللغة

فهم YAML

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

أزواج المفتاح/القيمة

مستندات YAML هي في الأساس مجموعة من أزواج المفاتيح والقيم. في المثال التالي، المفتاح هو name والقيمة هي TV on lights off. يتم الفصل بين المفتاح والقيمة بنقطتين متبوعتين بمسافة. يجب تضمين كلا الرمزَين ليكون تنسيق YAML سليمًا.

name: TV on lights off

القيم

يمكن أن تكون القيمة المرتبطة بمفتاح بسيطة مثل سلسلة أو رقم أو تاريخ، أو معقّدة مثل مجموعة أخرى من أزواج المفتاح/القيمة.

السلاسل

إذا بدأت قيمة السلسلة بأحد الأحرف التالية: [ أو { أو " أو ' أو #، أو إذا كانت السلسلة تحتوي على : (نقطتان رأسيتان متبوعتان بمسافات)، يجب وضعها بين علامتَي اقتباس.

يُسمح باستخدام علامات الاقتباس المفردة والمزدوجة، ولكن يجب أن تتطابق علامة الاقتباس الختامية مع علامة الاقتباس الافتتاحية.

الاقتباس الصحيح:

name: 'TV on lights off'

name: "TV on lights off"

الاقتباس غير الصحيح (علامات اقتباس غير متطابقة):

name: 'TV on lights off"

تكون علامات الاقتباس اختيارية لجميع أنواع السلاسل الأخرى.

إذا كنت بحاجة إلى سلسلة متعددة الأسطر، راجِع قسم مواصفات YAML حول القيم العددية المتعددة الأسطر.

name: "[1] TV"
name: '{1} TV'
name: '#TV'
name: '"1" TV'
name: "'1' TV"
name: "\"1\" TV"
name: "TV: bedroom"

أزواج المفتاح/القيمة المتداخلة

في هذا المثال، قيمة المفتاح metadata هي قائمة تتضمّن زوجَين من المفاتيح والقيم (name وdescription):

metadata:
  name: TV on lights off
  description: Turn off lights when TV turns on

المسافة البادئة

تستخدم YAML المسافة البادئة للإشارة إلى البنية. في المثال السابق، تم ترك مسافة بادئة (بمقدار مسافتين) قبل name وdescription للإشارة إلى أنّ هذين العنصرين هما العناصر الفرعية للمفتاح metadata.

يجب الالتزام بالمسافة البادئة في YAML. يجب أن يكون للملفات الفرعية مسافة بادئة أكبر من الملفات الرئيسية، ويجب أن يكون للملفات الفرعية التي تقع في المستوى نفسه المسافة البادئة نفسها.

metadata:
  name:
    en: TV on lights off
  description:
    en: Turn off lights when TV turns on

القيم المتعدّدة

إذا كان لمفتاح معيّن قيم متعددة، يتم إدراج كل قيمة في سطر جديد ويبدأ كل سطر بشرطة ومسافة. في المثال التالي، هناك قائمتان:

1. يمكن أن يتضمّن التشغيل الآلي عدة starters، وبالتالي يبدأ المشغّل الأول بشرطة ومسافة.
2. يمكن أن تتضمّن weekday قيمًا متعددة، وبالتالي يتم ترك مسافة بادئة لكل قيمة إضافية وتبدأ كل قيمة بشرطة ومسافة.

starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

التعليقات

يُعدّ أي نص يلي # تعليقًا ويتم تجاهله من قِبل محرك التشغيل الآلي.

السطر الذي يبدأ بالرمز # هو تعليق.

قد يظهر التعليق على السطر نفسه الذي يظهر فيه محتوى النص البرمجي، ولكن يجب أن يسبق # مسافة.

# This is a comment. It will be ignored.
name: chromecast #This is a TV.

نص برمجي للتشغيل الآلي

تُعرف مواصفات بنية نص Automations البرمجي باسم المخطط.

يحدّد مخطط "عمليات التشغيل الآلي" بنيتَي بيانات:

• يُطلق على زوج المفتاح والقيمة اسم حقل.
• تُسمى مجموعة الحقول المحدّدة بواسطة المخطط بنية.

بنية

تحدّد لغة البرمجة النصية للتشغيل الآلي عدة "مربّعات" أو بنى بيانات عادية، يُشار إليها باسم Structs.

ألقِ نظرة على automation Struct، الذي يحدّد أربعة حقول:

يوفّر قسم المراجع تعريفات المخطط لجميع أنواع Structs المتاحة.

تكون أسماء المفاتيح فريدة ضمن Struct معيّن وحسّاسة لحالة الأحرف.

أنواع القيم المحتملة هي:

• النوع الأساسي: bool، وnumber، وstring، وtime، وما إلى ذلك
• نوع Struct: مجموعة من الحقول
• مصفوفة من نوع البيانات يُشار إلى الصفيف بالرمز []. على سبيل المثال، [string] هي مجموعة من السلاسل، و[Starter] هي مجموعة من "البُنى الأولية".
• أنواع خاصة أخرى: Entity وFieldPath

يحتوي وصف كل حقل على معلومات مهمة، بما في ذلك:

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

بنية مكتوبة

يمكن أن تمثّل بعض البُنى عناصر بدء استنادًا إلى جدول زمني أو تغيير في حالة الجهاز. يجب أن يوفّر كل نوع من starter مجموعة مميزة من الحقول.

# A time schedule starter.
starter:
  type: time.schedule
  at: 10:00

# A device state change starter.
starter:
  type: device.state.OnOff
  device: TV - Living Room
  state: on
  is: true

starter هي بنية مكتوبة، ويتم توسيعها من خلال بنى فرعية أخرى في الحقل type، مثل time.schedule أو device.state.OnOff، لتوفير وظائف مختلفة. تكون بنى condition وaction أيضًا ذات نوع.

يجب أن تتّبع الحقول الإضافية في البنية مواصفات البنية الفرعية (type). على سبيل المثال، عند استخدام device.state.OnOff كـ type، تكون الحقولالمحدّدة لهذا النوع صالحة فقط في starter Struct.

مصفوفة

في YAML، يبدأ صفيف القيم بالرمز - (شرطة متبوعة بمسافة). ويمكن أن يحتوي الصفيف على قيم Struct متعددة أو قيم Primitive متعددة، ولكن يجب أن تكون القيم في الصفيف من النوع نفسه.

عندما تحتوي المصفوفة على عنصر واحد، يمكنك حذف الشرطة والمسافة:

# The starters field accepts an array of Starter Structs.
# This is the standard format.
starters:
- type: time.schedule
  at: sunset
- type: time.schedule
  at: sunrise

# The dash can be omitted if the array only has one item.
# This is also valid.
starters:
  type: time.schedule
  at: sunset

لا تتوافق المصفوفات المتعددة الأبعاد، مثل [[1, 2], [3, 4]]، مع نصوص البرمجة الخاصة بالتشغيل الآلي. سيؤدي محلّل اللغة تلقائيًا إلى تسوية مصفوفة متعدّدة الأبعاد إلى مصفوفة أحادية الأبعاد، وفي هذه الحالة، [1, 2, 3, 4].

# INVALID: multi-dimensional array
- - 1
  - 2
- - 3
  - 4

بدائي

تتيح مخطّطات Automations أنواع البيانات الأساسية التالية:

اللون

يمكن تحديد الألوان بإحدى ثلاث طرق، إما باستخدام النوعَين الأساسيَين ColorHex أو ColorTemperature، أو النوع المركّب SpectrumHSV.

SpectrumHSV

يحدّد النوع SpectrumHSV لونًا باستخدام ثلاثة حقول رقمية:

• تدرّج اللون هو الطول الموجي للون.
• يشير تشبُّع اللون إلى كثافة اللون.
• تشير القيمة إلى درجة سطوع اللون أو قتامته النسبية.

ديناميكية

في بعض الأحيان، لا يكون نوع بيانات المفتاح ثابتًا، بل يمكن أن يكون أحد الأنواع الأساسية، استنادًا إلى القيم من الحقول الأخرى.

مثال على حقل نوع البيانات الديناميكية هو is. يتم تحديد النوع الفعلي من خلال قيم الحقلَين type وstate.

# The 'is' field accepts a number type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1

# The 'is' field accepts a boolean type.
type: device.state.OnOff
device: My TV - Living Room
state: on
is: false

الكيان

تنسيق سلسلة خاص لتحديد كيان يملكه المستخدم بشكل فريد، مثل جهاز أو غرفة.

الجهاز هو العنصر الأكثر شيوعًا في عمليات التشغيل الآلي، وتكون صيغة السلسلة الخاصة بالعنصر device name - room name.

# The device field accepts a Device Entity type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1

FieldPath

تنسيق سلسلة خاص يُستخدَم لتحديد موقع جزء من البيانات في حمولة البيانات. في المثال التالي، currentVolume هو FieldPath للحقل state.

# The state field accepts a FieldPath type.
starters:
  type: device.state.Volume
  device: My TV - Living Room
  state: currentVolume
  is: 5

قد تتطلّب FieldPaths الأخرى مستويات متعدّدة للوصول إلى العنصر المطلوب، ويختلف التنسيق بين إجراء التفعيل والإجراء.

تستخدم أدوات البدء صيغة النقطة، مع تضمين المسار الكامل في الحقل نفسه. ويتم ذلك بشكل أساسي لأغراض المقارنة في منطق أدوات البدء. على سبيل المثال، لاستخدام درجة حرارة اللون كأداة بدء، عليك استخدام color.colorTemperature للحالة:

starters:
- type: device.state.ColorSetting
  device: My Device - Room Name
  state: color.colorTemperature
  is: 2000K

ومع ذلك، تستخدم الإجراءات حقولاً متداخلة. لتغيير لون المصباح إلى الأزرق، بدلاً من color.name وis: blue، عليك تنفيذ ما يلي:

actions:
- type: device.command.ColorAbsolute
  devices: My Device - Room Name
  color:
    name: blue