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

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

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

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

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

• النوع الأساسي: 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

بدائي

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

اللون

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