พื้นฐานภาษา

ทำความเข้าใจ 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 รายการต่อไปนี้

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

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

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

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

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

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

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

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

ฟิลด์เพิ่มเติมใน Struct ต้องเป็นไปตามข้อกำหนดของ Struct ย่อย (type) ตัวอย่างเช่น เมื่อใช้ device.state.OnOff เป็น type เฉพาะ ฟิลด์ที่ระบุสำหรับ ประเภทนั้น จะใช้ได้ใน starter Struct นั้น

อาร์เรย์

ใน YAML อาร์เรย์ของค่าจะขึ้นต้นด้วย - (ขีดกลางตามด้วยการเว้นวรรค) อาร์เรย์สามารถเก็บค่า Struct หรือค่า Primitive ได้หลายค่า แต่ค่าในอาร์เรย์ต้องเป็นประเภทเดียวกัน

เมื่ออาร์เรย์มีรายการเดียว คุณอาจละเว้นขีดกลางและช่องว่างได้

# 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

Primitive

สคริปต์การทำงานอัตโนมัติรองรับประเภทข้อมูลพื้นฐานต่อไปนี้ สคีมา

สี

คุณระบุสีได้ 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 อื่นๆ อาจต้องมีหลายระดับจึงจะไปถึงรายการที่ต้องการได้ และ รูปแบบจะแตกต่างกันระหว่าง 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