יסודות השפה

הסבר על 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 Struct, שמגדיר ארבעה שדות:

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

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

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

• סוג פרימיטיבי: bool, מספר, מחרוזת, זמן וכו'.
• סוג 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 הוא מבנה נתונים מוקלד, שמוכללים בו מבני נתונים מוקלדים אחרים בשדה 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