יסודות השפה

הסבר על 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

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

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

מפתח	סוג	תיאור
name	מחרוזת	זה שינוי אופציונלי. השם של הפעולה האוטומטית. לא מוצג למשתמשים, הוא מיועד למפתחים בלבד.
starters	[Starter]	חובה. רשימה של סימנים לתחילת פעולה.
condition	מצב	זה שינוי אופציונלי. תנאי.
actions	[פעולה]	חובה. רשימה של פעולות.

הקטע קובץ העזר מספק הגדרות של סכימה לכל ה-Structs הזמינים.

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

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

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

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

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

מבנה מוקלד

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

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

Array

ב-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

פרימיטיבי

סכימת הסקריפטים האוטומטית תומכת בסוגי הנתונים הפרמיטיביים הבאים:

בוליאני	true false
מספרים	מספר שלם או מספר עשרוני
מחרוזת	טקסט פשוט אין צורך לצטט מחרוזות, למעט במקרים ספציפיים.
תאריך	חודש ויום. הפורמט הוא MM-DD או MM/DD. 09/01 09-01
שעה	השעה ביום. ניתן לציין את השעה בשעון או שעון סולארי. אפשר לציין את השעה בפורמט AM/PM או בפורמט 24H. שניות הן אופציונליות. בזמן סולארי, sunrise ו-sunset הן מילות מפתח, וייתכנו קיזוזים עבורן (במונחים של משך הזמן). 12:30 am 13:00:01 sunrise / sunset sunset+30min / sunset-1hour
DateTime	שנה, חודש, יום ושעה ביום. נדרש רווח לבן בין החלק 'תאריך' לחלק 'שעה'. פורמט התאריך הוא YYYY-MM-DD או YYYY/MM/DD. פורמט השעה זהה לערך [שעה](#time). אזור הזמן אינו נתמך. 2022/01/01 14:00 2022-12-31 sunrise+30min
יום חול	MONDAY (או MON) TUESDAY (או TUE) WEDNESDAY (או WED) THURSDAY (או THU) FRIDAY (או FRI) SATURDAY (או SAT) SUNDAY (או SUN)
משך הקורס	תקופת זמן מסוימת. 30min 1hour 20sec 1hour10min20sec
ColorHex	קוד הקסדצימלי בן 6 ספרות שמייצג צבע. אין # מובילה. FFFFFF B5D2A1 DFA100
טמפרטורה	נתוני טמפרטורה רגילים. צריך תמיד להוסיף 'C' או 'F' לערך כדי לציין מדידת טמפרטורה. 20.5C 90F
ColorTemperature	טמפרטורת הצבע בקלווין. 5000K

צבע

אפשר לציין את הצבעים באחת משלוש דרכים – באמצעות הסוגים הפרימיטיביים ColorHex או ColorTemperature, או באמצעות הסוג המורכב SpectrumHSV.

SpectrumHSV

הסוג 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

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

ב-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