مبانی زبان

درک YAML

YAML یک زبان محبوب است که برای مشخص کردن پیکربندی نرم‌افزار استفاده می‌شود. این زبان روشی واضح و خوانا برای نمایش اطلاعات ساختاریافته ارائه می‌دهد. در اینجا چند نکته اساسی وجود دارد که باید قبل از ایجاد اولین اتوماسیون اسکریپتی خود در مورد YAML بدانید. برای کسب اطلاعات بیشتر در مورد YAML به طور کلی، به مشخصات نسخه ۱.۱ مراجعه کنید.

جفت‌های کلید-مقدار

اسناد 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

نظرات

هر متنی که بعد از # قرار بگیرد، به عنوان یک کامنت در نظر گرفته می‌شود و توسط موتور اتوماسیون نادیده گرفته می‌شود.

خطی که با # شروع می‌شود، یک توضیح (comment) است.

یک نظر می‌تواند در همان خط محتوای اسکریپت ظاهر شود، اما قبل از علامت # باید یک فاصله قرار گیرد .

# This is a comment. It will be ignored.
name: chromecast #This is a TV.

اسکریپت اتوماسیون

مشخصات مربوط به سینتکس اسکریپت Automations، طرحواره (schema) نامیده می‌شود.

طرح اتوماسیون، چند ساختار داده را تعریف می‌کند:

• یک جفت کلید-مقدار واحد، فیلد (Field) نامیده می‌شود.
• مجموعه‌ای از فیلدها که توسط طرحواره تعریف می‌شوند، Struct نامیده می‌شوند.

ساختار

زبان اسکریپت‌نویسی اتوماسیون، چندین «بلوک» یا ساختار داده استاندارد را تعریف می‌کند که به آنها Structs گفته می‌شود.

به ساختار automation نگاهی بیندازید که چهار فیلد را تعریف می‌کند:

مرجع این بخش تعاریف طرحواره را برای همه ساختارهای موجود ارائه می‌دهد.

نام کلیدها در یک ساختار مشخص منحصر به فرد هستند و به حروف کوچک و بزرگ حساس می‌باشند.

انواع مقادیر ممکن عبارتند از:

• یک نوع داده اولیه: bool، number، string، time و غیره.
• نوع ساختار: مجموعه‌ای از فیلدها.
• آرایه‌ای از نوع داده. آرایه با [] نشان داده می‌شود. برای مثال، [string] آرایه‌ای از رشته‌ها و [Starter] آرایه‌ای از ساختارهای آغازین است.
• انواع خاص دیگر: Entity، FieldPath.

توضیحات هر فیلد شامل اطلاعات مهمی از جمله موارد زیر است:

• الزامی در مقابل اختیاری، که نشان می‌دهد آیا فیلد اجباری است یا می‌توان از آن صرف نظر کرد.
• وابستگی فیلد. فقط فیلدهای اختیاری وابستگی دارند. این مورد، بررسی‌های اضافی هنگام استفاده از این فیلد را شرح می‌دهد، مانند استفاده از فیلد B فقط در صورتی که فیلد A تنظیم شده باشد ، یا وقتی فیلد A استفاده می‌شود، فیلد B یا فیلد C تنظیم نشود .
• مقادیر ممکن. به عنوان مثال، مجموعه مقادیر محدود یک فیلد شمارشی از نوع رشته، یا طیفی از اعداد که ممکن است در یک فیلد از نوع عدد استفاده شوند.

ساختار تایپ‌شده

برخی از Structها می‌توانند بر اساس یک برنامه زمانی یا تغییر وضعیت دستگاه، شروع‌کننده‌ها را نمایش دهند. هر نوع 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 Field، مانند time.schedule یا device.state.OnOff ، برای ارائه توابع مختلف، گسترش می‌یابد. ساختارهای condition و action نیز نوع‌دار هستند.

فیلدهای اضافی در Struct باید از مشخصات Struct فرزند ( type ) پیروی کنند. برای مثال، هنگام استفاده از device.state.OnOff به عنوان type ، فقطفیلدهای مشخص شده برای آن نوع در آن ساختار starter معتبر هستند.

آرایه

در 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

ابتدایی

انواع داده‌های اولیه زیر توسط طرحواره اسکریپت Automations پشتیبانی می‌شوند:

رنگ

رنگ‌ها را می‌توان به یکی از سه روش زیر مشخص کرد - استفاده از انواع اولیه ColorHex یا ColorTemperature یا نوع ترکیبی SpectrumHSV .

طیف HSV

نوع SpectrumHSV با استفاده از سه فیلد عددی، یک رنگ را مشخص می‌کند:

• رنگ (hue) با طول موج رنگ مطابقت دارد.
• اشباع، شدت رنگ را نشان می‌دهد.
• مقدار، میزان روشنی یا تیرگی نسبی رنگ را نشان می‌دهد.

پویا

گاهی اوقات، نوع داده یک کلید ثابت نیست. می‌تواند یکی از انواع اولیه باشد که بر اساس مقادیر سایر فیلدها تعیین می‌شود.

یک مثال از فیلد نوع داده پویا، 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

مسیر میدانی

یک قالب رشته‌ای خاص که برای یافتن یک قطعه داده در یک داده‌ی payload استفاده می‌شود. در مثال زیر، currentVolume مسیر فیلد برای فیلد 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