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

فهم 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.

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

تُسمى مواصفات بنية النص البرمجي للتشغيل الآلي المخطّط.

يحدِّد مخطّط عمليات التشغيل الآلي بعض بُنى البيانات:

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

بنية

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

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

المفتاح	النوع	الوصف
name	سلسلة	اختياريّ. تمثّل هذه السمة اسم قاعدة التشغيل الآلي. لن يظهر هذا الاسم للمستخدمين، بل هو كمرجع لمطوّري البرامج فقط.
starters	[مستخدم المبتدئين]	مطلوبة. تمثّل هذه السمة قائمة بالمبتدئين.
condition	الحالة	اختياريّ. الحالة.
actions	[الإجراء]	مطلوبة. قائمة بالإجراءات

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

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

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

• النوع الأساسي: قيمة منطقية ورقم وسلسلة ووقت وما إلى ذلك.
• نوع الهيكل: مجموعة من الحقول.
• مصفوفة من نوع البيانات. يُشار إلى المصفوفة بـ []. على سبيل المثال، [string] هي مصفوفة من السلاسل، و[Starter] هي مصفوفة من بنية المبتدئين.
• أنواع خاصة أخرى: Entity وFieldPath.

يتضمن وصف كل حقل معلومات مهمة، ومنها:

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

هيكل مكتوب

يمكن أن تمثل بعض الهياكل إجراءات التفعيل استنادًا إلى جدول زمني أو تغيير حالة الجهاز. يجب أن يوفّر كل نوع من 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.

مصفوفة

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

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

# 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

المجموعة الأولية

تتوافق أنواع البيانات الأساسية التالية مع مخطط النص البرمجي للتشغيل الآلي:

منطقية	true false
العدد	عدد صحيح أو عدد عشري
سلسلة	نص عادي لا حاجة إلى اقتباس السلاسل إلا في حالات معيّنة.
التاريخ	الشهر واليوم التنسيق هو MM-DD أو MM/DD. 09/01 09-01
الوقت	وقت اليوم يمكن أن يكون توقيت الساعة أو الوقت الشمسي. بالنسبة إلى وقت الساعة، يمكن أن يستخدم إما تنسيق صباحًا/مساءً أو تنسيق 24 ساعة. أما الثواني، فاختيارية. بالنسبة إلى التوقيت الشمسي، يكون sunrise وsunset كلمات رئيسية، وقد تتبعها معادلة (في أحكام "المدة"). 12:30 am 13:00:01 sunrise / sunset sunset+30min / sunset-1hour
DateTime	السنة والشهر واليوم والوقت من اليوم. يجب إضافة مسافة بيضاء بين جزء "التاريخ" والجزء "الوقت". تنسيق التاريخ هو YYYY-MM-DD أو YYYY/MM/DD. تنسيق الوقت هو نفسه [Time](#time). المنطقة الزمنية غير متاحة. 2022/01/01 14:00 2022-12-31 sunrise+30min
أيام الأسبوع	‫MONDAY (أو MON) ‫TUESDAY (أو TUE) ‫WEDNESDAY (أو WED) ‫THURSDAY (أو THU) ‫FRIDAY (أو FRI) ‫SATURDAY (أو SAT) ‫SUNDAY (أو SUN)
المدة	فترة زمنية. 30min 1hour 20sec 1hour10min20sec
ColorHex	رمز سداسي عشري مكوَّن من ستة أرقام يمثل لونًا. لا توجد # بادئة. FFFFFF B5D2A1 DFA100
درجة الحرارة	بيانات درجة الحرارة الطبيعية أضِف دائمًا 'C' أو 'F' إلى القيمة للإشارة إلى قياس درجة الحرارة. 20.5C 90F
ColorTemperature	درجة حرارة الألوان بالكلفن. 5000K

اللون

يمكن تحديد الألوان بطريقة من ثلاث طرق، إما باستخدام النوع الأساسي 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

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

تستخدم البداية ترميزًا نقطيًا، مع وجود المسار بالكامل في نفس الحقل. يتم ذلك بشكل أساسي لأغراض المقارنة في منطق البدء. على سبيل المثال، لاستخدام درجة حرارة الألوان كإجراء تفعيل، عليك استخدام 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