יסודות השפה

הסבר על 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 מוזחות (ב-2 רווחים) כדי לציין שהן צאצאים של המפתח 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

שפת הסקריפטים לאוטומציה מגדירה כמה 'בלוקים' או מבני נתונים סטנדרטיים, שנקראים Structs.

אפשר לראות את המבנה automation, שמגדיר ארבעה שדות:

בקטע Reference מוצגות הגדרות סכימה לכל מבני הנתונים הזמינים.

שמות המפתחות הם ייחודיים בתוך מבנה נתונים מסוים, והם תלויי אותיות רישיות.

סוגי הערכים האפשריים הם:

• סוג פרימיטיבי: bool,‏ number,‏ string,‏ time וכו'.
• סוג Struct: אוסף של שדות.
• מערך של סוג הנתונים. מערך מסומן על ידי []. לדוגמה, [string] הוא מערך של מחרוזות, ו-[Starter] הוא מערך של מבני נתונים מסוג Starter.
• סוגים מיוחדים אחרים: Entity, FieldPath.

תיאור כל שדה מכיל מידע חשוב, כולל:

• חובה או אופציונלי, כדי לציין אם השדה הוא חובה או שאפשר לדלג עליו.
• תלות בשדה. רק לשדות אופציונליים יש תלות. התיאור הזה כולל את הבדיקות הנוספות שמתבצעות כשמשתמשים בשדה הזה, כמו שימוש בשדה ב' רק אם שדה א' מוגדר או כשמשתמשים בשדה א', לא מגדירים את שדה ב' או את שדה ג'.
• ערכים אפשריים. לדוגמה, קבוצת הערכים המוגבלת של EnumField מסוג מחרוזת, או טווח של מספרים שאפשר להשתמש בהם בשדה מסוג מספר.

Typed 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 הוא מבנה מוקלד, שמוכלל על ידי מבני צאצא אחרים ב-Field‏ type, כמו time.schedule או device.state.OnOff, כדי לספק פונקציות שונות. גם המבנים condition ו-action הם מוקלדים.

שדות נוספים ב-Struct צריכים להיות בהתאם למפרט של ה-Struct המשני (type). לדוגמה, אם משתמשים ב-device.state.OnOff בתור type, רק השדותשצוינו עבור הסוג הזה והשדה תקפים במבנה starter הזה.

מערך

ב-YAML, מערך של ערכים מתחיל ב-- (מקף ואחריו רווח). המערך יכול להכיל כמה ערכי Struct או כמה ערכים פרימיטיביים. אבל הערכים במערך חייבים להיות מאותו סוג.

אם המערך מכיל פריט אחד, אפשר להשמיט את המקף והרווח:

# 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

פורמט מחרוזת מיוחד שמשמש לאיתור חלק מנתוני מטען ייעודי (payload). בדוגמה הבאה, 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 אחרים, והפורמט שונה בין starter לבין action.

התחלות מסומנות בנקודה, והנתיב כולו מופיע באותו שדה. הפעולה הזו מתבצעת בעיקר למטרות השוואה בלוגיקה של סימנים לתחילת פעולה. לדוגמה, כדי להשתמש בטמפרטורת הצבע כהתחלה, צריך להשתמש ב-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