พื้นฐานภาษา

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

YAML เป็นภาษายอดนิยมที่ใช้ระบุการกำหนดค่าซอฟต์แวร์ มอบวิธีที่ชัดเจนและสามารถอ่านเข้าใจได้ในการแสดงถึง Structured Data มาดูข้อมูลเบื้องต้นที่คุณต้องทำความเข้าใจกัน 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 คือรายการคู่คีย์-ค่า 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

โครงสร้าง

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

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

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

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

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

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

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

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

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

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

แบบพื้นฐาน

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

สี

สามารถระบุสีได้ด้วยวิธีใดวิธีหนึ่งใน 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