יסודות השפה

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

בקטע 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

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