พื้นฐานภาษา

ทำความเข้าใจ YAML

YAML เป็นภาษายอดนิยมที่ใช้ระบุการกำหนดค่าซอฟต์แวร์ โดยเป็นวิธีการนำเสนอข้อมูลที่มีโครงสร้างที่ชัดเจนและมนุษย์อ่านเข้าใจได้ ต่อไปนี้เป็นข้อมูลพื้นฐานที่คุณควรทำความเข้าใจเกี่ยวกับ YAML ก่อนที่จะสร้างการทำงานอัตโนมัติที่ใช้สคริปต์รายการแรก ดูข้อมูลเพิ่มเติมเกี่ยวกับ YAML ทั่วไปได้ที่ข้อมูลจำเพาะของเวอร์ชัน 1.1

คู่คีย์-ค่า

โดยทั่วไปแล้วเอกสาร YAML คือคอลเล็กชันคู่คีย์-ค่า ในตัวอย่างต่อไปนี้ คีย์คือ name และค่าคือ TV on lights off คีย์และค่าจะคั่นด้วยเครื่องหมายโคลอนตามด้วยเว้นวรรค ต้องมีอักขระทั้ง 2 ตัว สำหรับ 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 คือรายการคู่คีย์-ค่า 2 คู่ (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

หลายค่า

หากคีย์หนึ่งๆ มีหลายค่า แต่ละค่าจะแสดงในบรรทัดใหม่ และแต่ละบรรทัดจะขึ้นต้นด้วยเครื่องหมายขีดกลางและเว้นวรรค ในตัวอย่างต่อไปนี้ มี 2 รายการ คือ

  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.

สคริปต์การทำงานอัตโนมัติ

ข้อกำหนดสำหรับไวยากรณ์สคริปต์การทำงานอัตโนมัติเรียกว่าสคีมา

สคีมาการทำงานอัตโนมัติกำหนดโครงสร้างข้อมูล 2 แบบดังนี้

  • คู่คีย์-ค่าเดียวเรียกว่าช่อง
  • คอลเล็กชันของช่องที่สคีมากำหนดเรียกว่า Struct

โครงสร้าง

ภาษาสคริปต์การทำงานอัตโนมัติจะกำหนด "การบล็อก" หรือโครงสร้างข้อมูลที่เป็นมาตรฐานหลายรายการ หรือที่เรียกว่า Structs

ลองดูโครงสร้าง automation ซึ่งกำหนด 4 ช่องต่อไปนี้

คีย์ ประเภท คำอธิบาย

name

สตริง

ไม่บังคับ

ชื่อการทำงานอัตโนมัติ

ข้อมูลนี้ไม่ได้แสดงต่อผู้ใช้ แต่มีไว้สำหรับการอ้างอิงของนักพัฒนาซอฟต์แวร์เท่านั้น

starters

[เงื่อนไขเริ่มต้น]

ต้องระบุ

รายการเงื่อนไขเริ่มต้น

condition

สภาพสินค้า

ไม่บังคับ

สภาพ

actions

[การดำเนินการ]

ต้องระบุ

รายการการดำเนินการ

ส่วน ข้อมูลอ้างอิง มีคำจำกัดความของสคีมาสำหรับ Structs ทั้งหมดที่พร้อมใช้งาน

ชื่อคีย์จะไม่ซ้ำกันใน Struct ที่ระบุและคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่

ประเภทค่าที่เป็นไปได้มีดังนี้

  • ประเภทพื้นฐาน เช่น บูลีน ตัวเลข สตริง เวลา ฯลฯ
  • ประเภทโครงสร้าง: คอลเล็กชันของช่อง
  • อาร์เรย์ของประเภทข้อมูล อาร์เรย์ จะกำกับด้วย [] เช่น [string] คืออาร์เรย์ของสตริง และ [Starter] คืออาร์เรย์ของโครงสร้างเริ่มต้น
  • ประเภทพิเศษอื่นๆ: เอนทิตี, FieldPath

คำอธิบายของแต่ละฟิลด์มีข้อมูลสำคัญ ได้แก่

  • "ต้องระบุ" หรือ "ไม่บังคับ" โดยระบุว่าช่องนี้เป็นช่องบังคับหรือข้ามได้
  • การขึ้นต่อกันของช่อง เฉพาะฟิลด์ที่ไม่บังคับเท่านั้นที่มีการขึ้นต่อกัน ซึ่งอธิบายการตรวจสอบเพิ่มเติมเมื่อใช้ช่องนี้ เช่น ใช้ช่อง B เฉพาะในกรณีที่มีการตั้งค่าช่อง A เท่านั้น หรือเมื่อใช้ช่อง A อย่าตั้งค่าช่อง B หรือช่อง C
  • ค่าที่เป็นไปได้ ตัวอย่างเช่น ชุดค่าที่จำกัดของฟิลด์ประเภทสตริง Enum หรือช่วงของตัวเลขที่สามารถใช้ในช่องของจำนวนประเภท

โครงสร้างที่ถูกพิมพ์

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 Struct

อาร์เรย์

ใน 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

สี

คุณระบุสีได้ 3 วิธีโดยใช้ประเภทดั้งเดิม ColorHex หรือ ColorTemperature หรือประเภทสารประกอบ SpectrumHSV

SpectrumHSV

ประเภท SpectrumHSV จะระบุสีโดยใช้ช่องตัวเลข 3 ช่อง ได้แก่

  • โทนสีจะสอดคล้องกับความยาวคลื่นสี
  • ความอิ่มตัวจะแสดงความเข้มของสี
  • ค่าจะบ่งบอกถึงความสว่างหรือความมืดสัมพัทธ์ของสี

ไดนามิก

บางครั้งประเภทข้อมูลของคีย์อาจไม่คงที่ อาจเป็นประเภทพื้นฐาน โดยอิงตามค่าจากช่องอื่นๆ

ตัวอย่างของช่องประเภทข้อมูลแบบไดนามิกคือ 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 อื่นๆ อาจต้องใช้หลายระดับเพื่อไปยังรายการที่ต้องการ และรูปแบบเริ่มต้นและการดําเนินการจะแตกต่างกันไป

เงื่อนไขเริ่มต้นจะใช้สัญลักษณ์จุด โดยทั้งเส้นทางในช่องเดียวกัน การดำเนินการนี้มีจุดประสงค์เพื่อเปรียบเทียบในตรรกะเริ่มต้นเป็นหลัก เช่น หากต้องการใช้อุณหภูมิสีเป็นเงื่อนไขเริ่มต้น ให้ใช้ 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