مبانی زبان

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.

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

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

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

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

ساختار

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

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

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

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

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

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

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

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

آرایه

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

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

وجود، موجودیت

یک قالب رشته خاص برای شناسایی منحصر به فرد موجودیت متعلق به کاربر مانند دستگاه یا اتاق.

دستگاه رایج ترین موجودی است که در اتوماسیون ها استفاده می شود. قالب موجودیت String 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 فیلد مسیر برای فیلد 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