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

فهم تنسيق 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 Struct، الذي يحدّد أربعة حقول:

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

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

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

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

بدائي

تتيح بنية النص البرمجي للتحكّم الآلي أنواع البيانات الأساسية التالية:

اللون

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