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

فهم تنسيق 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.

نص التشغيل الآلي

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

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

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

بنية

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

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

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

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

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

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

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

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

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

بنية مكتوبة

يمكن أن تمثّل بعض Structs إجراءات التفعيل استنادًا إلى جدول زمني أو تغيير في حالة الجهاز. يجب أن يقدّم كل نوع من 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 هو بنية من النوع Typed Struct، يتم تمديدها من خلال بنى فرعية أخرى في الحقل 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
الوقت	الوقت من اليوم يمكن أن يكون الوقت حسب الساعة أو الوقت الشمسي. بالنسبة إلى وقت الساعة، يمكن استخدام تنسيق AM/PM أو تنسيق 24 ساعة. الثواني اختيارية. بالنسبة إلى التوقيت الشمسي، sunrise وsunset هما كلمتان رئيسيتان، وقد يتبعهما مقدار الاختلاف (بوحدات المدة). 12:30 am 13:00:01 sunrise / sunset sunset+30min / sunset-1hour
DateTime	السنة والشهر واليوم ووقت اليوم يجب ترك مسافة بين جزء التاريخ وجزء الوقت. تنسيق التاريخ هو YYYY-MM-DD أو YYYY/MM/DD. تنسيق الوقت هو نفسه تنسيق [الوقت](#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