יסודות השפה

הסבר על 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 נקרא סכימה.

הסכימה של האוטומציות מגדירה כמה מבני נתונים:

  • צמד מפתח/ערך יחיד נקרא שדה.
  • אוסף של שדות שמוגדרים על ידי הסכימה נקרא Struct.

Struct

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

עיינו ב-Struct‏ automation, שמגדיר ארבעה שדות:

מפתח סוג תיאור

name

מחרוזת

זה שינוי אופציונלי.

השם של האוטומציה.

המידע הזה לא מוצג למשתמשים, והוא מיועד למפתחים בלבד.

starters

[Starter]

חובה.

רשימה של התחלות.

condition

תנאי

זה שינוי אופציונלי.

תנאי.

actions

[פעולה]

חובה.

רשימה של פעולות.

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

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

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

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

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

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

Struct מוגדר

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

שדות נוספים ב-Struct חייבים לעמוד במפרט של Struct הצאצא (type). לדוגמה, כשמשתמשים ב-device.state.OnOff בתור type, רקהשדות שצוינו לסוג הזה הם חוקיים ב-Struct‏ 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

פרימיטיבי

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

בוליאני
  • 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](#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

קוד הקסדצימלי בן שש ספרות שמייצג צבע.

אין # בתחילת השורה.

  • FFFFFF
  • B5D2A1
  • DFA100
טמפרטורה

נתוני טמפרטורה רגילים. תמיד מוסיפים את הערך 'C' או 'F' לערך כדי לציין מדידת טמפרטורה.

  • 20.5C
  • 90F
ColorTemperature

טמפרטורת הצבע בקלווין.

  • 5000K

צבע

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

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