语言基础知识

了解 YAML

YAML 是一种用于指定软件配置的常用语言。它提供了一种清晰、人类可读懂的方式来表示结构化信息。在创建首个脚本化自动化之前，您需要了解有关 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 的值是一个包含两个键值对（name 和 description）的列表：

metadata:
  name: TV on lights off
  description: Turn off lights when TV turns on

缩进

YAML 使用缩进来表示结构。在前面的示例中，name 和 description 缩进（用两个空格），以表示它们是键 metadata 的子项。

YAML 中的缩进非常严格。子结构的缩进必须比其父结构更深，同级别的键值对必须具有相同的缩进。

metadata:
  name:
    en: TV on lights off
  description:
    en: Turn off lights when TV turns on

多个值

如果给定键具有多个值，则每个值都会另起一行，并且每行开头，后跟短划线和空格。以下示例有两个列表：

  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.

自动化操作脚本

自动化操作脚本语法的规范称为“架构”。

自动化操作架构定义了几个数据结构：

  • 单个键值对称为“字段”。
  • 由架构定义的字段集合称为结构体。

结构体

自动化脚本语言定义了多个标准“块”或数据结构，称为结构体。

我们来看一下 automation 结构体，它定义了四个字段：

键 类型 说明

name

字符串

可选。

自动化操作的名称。

此名称不会向用户显示，仅供开发者参考。

starters

[入门版]

必填。

启动方式列表。

condition

条件

可选。

使用情况。

actions

[操作]

必填。

操作列表。

参考文档 部分提供了所有可用结构体的架构定义。

键名在给定结构体中是唯一的，并且区分大小写。

可能的值类型包括：

  • 基元类型：bool、数字、字符串、时间等。
  • 结构体类型：字段集合。
  • 数据类型的数组。数组由 [] 表示。例如，[string] 是一个字符串数组，[Starter] 是入门结构的数组。
  • 其他特殊类型：Entity、FieldPath。

每个字段的说明都包含重要信息，包括：

  • 必需与可选，指示该字段是必填字段还是可以跳过。
  • 字段依赖项。只有可选字段具有依赖项。这介绍了使用此字段时需要执行的其他检查，例如：仅在已设置字段 A 时才使用字段 B，或者使用字段 A 时，请勿设置字段 B 或字段 C。
  • 可能的值。例如，字符串类型的枚举字段的有限值集，或可以在数字类型的字段中使用的数字范围。

类型化结构体

某些结构体可以根据时间表或设备状态变化表示启动方式。每种类型的 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 结构体也是类型化结构。

结构体中的其他字段必须遵循子级结构体 (type) 规范。例如，将 device.state.OnOff 用作 type 时，只有为该类型指定的为该类型指定的字段 在该 starter 结构体中有效。

数组

在 YAML 中，值数组以 - 开头（短划线后跟空格）。数组可以包含多个结构体值，或多个基元值。但数组中的值必须属于同一类型。

当数组包含单个项时，可以省略短划线和空格：

# 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

原初

自动化操作脚本架构支持以下原始数据类型：

Bool
  • true
  • false

数字

整数或小数

字符串

纯文本

字符串无需用引号引起来，除非在特定情况下。

日期

月和日。格式为 MM-DD 或 MM/DD。

  • 09/01
  • 09-01

时间

时段。它可以是时钟时间或太阳时间。 对于时钟时间，可以使用 AM/PM 格式或 24H 格式。秒数是可选的。对于太阳时，sunrise 和 sunset 是关键字，后跟偏移量（在 Duration 中）。

  • 12:30 am
  • 13:00:01
  • sunrise/sunset
  • sunset+30min/sunset-1hour

DateTime

年、月、日和时段。日期部分和时间部分之间需要空格。日期格式为 YYYY-MM-DD 或 YYYY/MM/DD。 时间格式与 [Time](#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

颜色

您可以通过以下三种方式之一指定颜色：使用 ColorHex 或 ColorTemperature 基元类型，或者使用化合物类型 SpectrumHSV。

SpectrumHSV

SpectrumHSV 类型使用三个数字字段指定颜色：

  • 色相对应于颜色波长。
  • 饱和度表示颜色的强度。
  • 值表示颜色的相对亮度或暗度。

动态

有时，键的数据类型不是固定的。它可以是某个基元类型，具体取决于其他字段中的值。

举例来说，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 是 state 字段的 FieldPath。

# 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