语言基础知识

了解 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 结构体，它定义了四个字段：

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

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

可能的值类型包括：

• 原初类型：bool、数字、字符串、时间等。
• 结构体类型：字段集合。
• 数据类型的数组。数组用 [] 表示。例如，[string] 是字符串数组，[Starter] 是 Starter 结构体数组。
• 其他特殊类型：实体、FieldPath。

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

• 必填与可选，表示该字段是强制性的还是可以跳过。
• 字段依赖项。只有可选字段具有依赖项。这描述了使用此字段时的 其他检查，例如“仅当设置了字段 A 时才 使用字段 B”，或者“使用字段 A 时，请勿设置字段 B 或字段 C”。
• 可能的值。例如，类型为字符串的枚举字段的有限值集，或者类型为数字的字段中可能使用的数字范围。

类型化结构体

某些结构体可以根据时间安排或设备状态更改来表示 starter。每种 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

原初类型

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

颜色

颜色可以通过三种方式之一指定 - 使用 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 和操作的格式不同。

Starter 使用点表示法，整个路径位于同一字段中。这主要是为了在 starter 逻辑中进行比较。例如，如需使用色温作为 starter，您可以使用 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