יסודות השפה

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

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

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

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

שמות המפתחות הם ייחודיים בתוך Struct נתון, והם תלויי אותיות רישיות (case-sensitive).

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

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

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

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

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 הוא Typed Struct, שמוגדר על ידי מבני צאצא אחרים בשדה 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

פרימיטיבי

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

צבע

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

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