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

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

Struct

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

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

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

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

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

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

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

• مطلوب مقابل اختياري، الإشارة إلى ما إذا كان الحقل إلزاميًا أو يمكن تخطيها.
• التبعية الميدانية. لا تتضمّن سوى الحقول الاختيارية عناصر تابعة. يصف هذا عمليات التحقّق الإضافية عند استخدام هذا الحقل، مثل استخدام الحقل "ب" فقط إذا كان الحقل "أ" set, or عند استخدام الحقل أ، لا يتم تعيين الحقل ب أو الحقل ج.
• القيم المحتملة. على سبيل المثال، مجموعة القيم المحدودة لحقل 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 عبارة عن بنية مكتوبة، ويتم توسيعها بواسطة بنيات فرعية أخرى في الحقل 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

قد تتطلب مسارات 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