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

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

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

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

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

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

بنية

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

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

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

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

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

• نوع أساسي: قيمة منطقية ورقم وسلسلة ووقت وما إلى ذلك.
• نوع Struct: مجموعة من الحقول
• مصفوفة من نوع البيانات يُشار إلى المصفوفة بالرمز []. على سبيل المثال، [string] هو مصفوفة من السلاسل، و[Starter] هو مصفوفة من Starter Structs.
• الأنواع الخاصة الأخرى: 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 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

بدائي

تتوافق أنواع البيانات الأساسية التالية مع مخطط نص الأتمتة:

اللون

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

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

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