语言基础知识

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

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

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

可能的值类型包括：

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

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

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

类型化结构体

某些 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 结构体中有效。

数组

在 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 可能需要多个层级才能到达所需项，并且启动器和操作之间的格式有所不同。

初学者使用点表示法，将整个路径放在同一字段中。这主要是为了在启动器逻辑中进行比较。例如，如需将色温用作启动器，您需要将 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