พื้นฐานภาษา

ทําความเข้าใจ 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 Struct ซึ่งกำหนดช่อง 4 ช่อง ได้แก่

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

name

สตริง

ไม่บังคับ

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

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

starters

[Starter]

ต้องระบุ

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

condition

สภาพสินค้า

ไม่บังคับ

สภาพ

actions

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

ต้องระบุ

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

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

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

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

  • ประเภทพื้นฐาน: bool, ตัวเลข, สตริง, เวลา และอื่นๆ
  • ประเภท Struct: ชุดฟิลด์
  • อาร์เรย์ของประเภทข้อมูล อาร์เรย์จะแสดงด้วย [] เช่น [string] คืออาร์เรย์สตริง และ [Starter] คืออาร์เรย์ของสตรูคเจอร์เงื่อนไขเริ่มต้น
  • ประเภทพิเศษอื่นๆ: เอนทิตี, FieldPath

คําอธิบายของช่องแต่ละช่องจะมีข้อมูลสําคัญต่อไปนี้

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

โครงสร้างที่มีการจัดประเภท

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 ที่มีประเภท ซึ่งขยายโดย Struct ย่อยอื่นๆ ในช่อง type เช่น time.schedule หรือ device.state.OnOff เพื่อให้บริการฟังก์ชันต่างๆ โครงสร้าง condition และ action เป็นแบบมีการกำหนดประเภทด้วย

ช่องเพิ่มเติมใน 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) ไม่รองรับเขตเวลา

  • 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 ช่อง ได้แก่

  • Hue สอดคล้องกับความยาวคลื่นของสี
  • ความอิ่มตัวแสดงถึงระดับความเข้มของสี
  • ค่าระบุความสว่างหรือความมืดของสี

ไดนามิก

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

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