พื้นฐานภาษา

ทำความเข้าใจ 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

โครงสร้าง

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

ดูที่ automation Struct ซึ่งกำหนด 4 ฟิลด์ต่อไปนี้

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

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

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

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

คำอธิบายของแต่ละช่องจะมีข้อมูลสำคัญ ซึ่งรวมถึงข้อมูลต่อไปนี้

• ต้องระบุหรือไม่บังคับ ซึ่งระบุว่าช่องนั้นเป็นช่องที่ต้องกรอกหรือข้ามได้
• การขึ้นต่อกันของฟิลด์ เฉพาะฟิลด์ตัวเลือกเท่านั้นที่มีทรัพยากร Dependency ซึ่งจะอธิบายการตรวจสอบเพิ่มเติมเมื่อใช้ช่องนี้ เช่น ใช้ช่อง 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 หลายค่าหรือค่า 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

พื้นฐาน

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

สี

คุณระบุสีได้ 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