语言基础知识

了解 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.

自动化脚本

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

“自动化操作”架构定义了两个数据结构：

  • 单个键值对称为字段。
  • 架构定义的一组字段称为结构体。

结构体

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

查看 automation 结构体，其中定义了四个字段：

密钥 类型 说明

name

String

可选。

自动化操作的名称。

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

starters

[Starter]

必填。

启动器列表。

condition

条件

可选。

使用情况。

actions

[操作]

必填。

操作列表。

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

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

可能的值类型包括：

  • 基元类型：布尔值、数字、字符串、时间等。
  • 结构体类型：字段集合。
  • 数据类型的数组。数组用 [] 表示。例如，[string] 是一个字符串数组，[Starter] 是一个起始结构体数组。
  • 其他特殊类型：实体、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 格式或 24 小时制。秒数是可选的。 对于太阳时间，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

表示颜色的六位十六进制代码。

没有前导 #。

  • 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 可能需要多个级别才能到达所需项，并且起始项和操作的格式不同。

起始页面使用点表示法，整个路径都在同一字段中。这主要是为了在启动器逻辑中进行比较。例如，如需将色温用作启动器，您可以为状态使用 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