YAML 语法
此页面提供了有关正确 YAML 语法的基本概述,Ansible playbook(我们的配置管理语言)就是用这种语法表达的。
我们使用 YAML 是因为它比其他常见的数据格式(如 XML 或 JSON)更容易让人阅读和编写。此外,大多数编程语言中都有可用于处理 YAML 的库。
您可能还想同时阅读 使用 playbook,以了解它在实践中的用法。
YAML 基础
对于 Ansible,几乎每个 YAML 文件都以列表开头。列表中的每个项目都是一系列键值对,通常称为“哈希”或“字典”。因此,我们需要了解如何在 YAML 中编写列表和字典。
YAML 还有一个小的特性。所有 YAML 文件(无论是否与 Ansible 相关)都可以选择以 ---
开头,以 ...
结尾。这是 YAML 格式的一部分,表示文档的开始和结束。
列表的所有成员都是以相同缩进级别开头的行,以 "- "
(破折号和空格)开头
---
# A list of tasty fruits
- Apple
- Orange
- Strawberry
- Mango
...
字典以简单的 key: value
形式表示(冒号后面必须跟一个空格)
# An employee record
martin:
name: Martin D'vloper
job: Developer
skill: Elite
还可以使用更复杂的数据结构,例如字典列表、值为列表的字典或两者的混合
# Employee records
- martin:
name: Martin D'vloper
job: Developer
skills:
- python
- perl
- pascal
- tabitha:
name: Tabitha Bitumen
job: Developer
skills:
- lisp
- fortran
- erlang
如果确实需要,字典和列表也可以以简写形式表示
---
martin: {name: Martin D'vloper, job: Developer, skill: Elite}
fruits: ['Apple', 'Orange', 'Strawberry', 'Mango']
这些称为“流集合”。
Ansible 并不经常使用这些,但您也可以指定 布尔值(true/false)的几种形式
create_key: true
needs_agent: false
knows_oop: True
likes_emacs: TRUE
uses_cvs: false
如果要与默认的 yamllint 选项兼容,请在字典中使用小写“true”或“false”作为布尔值。
可以使用 |
或 >
使值跨越多行。使用“文字块标量” |
跨越多行将包括换行符和任何尾随空格。使用“折叠块标量” >
将换行符折叠为空格;它用于使原本很长的行更容易阅读和编辑。在这两种情况下,缩进都将被忽略。示例如下:
include_newlines: |
exactly as you see
will appear these three
lines of poetry
fold_newlines: >
this is really a
single line of text
despite appearances
在上面的 >
示例中,所有换行符都被折叠为空格,但有两种方法可以强制保留换行符
fold_some_newlines: >
a
b
c
d
e
f
或者,可以通过包含换行符 \n
字符来强制执行
fold_same_newlines: "a b\nc d\n e\nf\n"
让我们将到目前为止学到的知识结合在一个任意 YAML 示例中。这与 Ansible 没有任何关系,但会让您对格式有所了解
---
# An employee record
name: Martin D'vloper
job: Developer
skill: Elite
employed: True
foods:
- Apple
- Orange
- Strawberry
- Mango
languages:
perl: Elite
python: Elite
pascal: Lame
education: |
4 GCSEs
3 A-Levels
BSc in the Internet of Things
这就是开始编写 Ansible playbook 所需了解的全部 YAML 知识。
注意事项
虽然您几乎可以在未加引号的标量中放入任何内容,但有一些例外。冒号后跟空格(或换行符)": "
是映射的指示符。空格后跟井号 " #"
表示注释的开始。
因此,以下内容将导致 YAML 语法错误
foo: somebody said I should put a colon here: so I did
windows_drive: c:
…但以下内容将起作用
windows_path: c:\windows
您需要使用冒号后跟空格或行尾来引用哈希值
foo: 'somebody said I should put a colon here: so I did'
windows_drive: 'c:'
…然后冒号将被保留。
或者,您可以使用双引号
foo: "somebody said I should put a colon here: so I did"
windows_drive: "c:"
单引号和双引号之间的区别在于,在双引号中可以使用转义字符
foo: "a \t TAB and a \n NEWLINE"
允许的转义字符列表可以在 YAML 规范的“转义序列”(YAML 1.1)或“转义字符”(YAML 1.2)下找到。
以下是无效的 YAML
foo: "an escaped \' single quote"
此外,Ansible 使用“{{ var }}”表示变量。如果冒号后面的值以“{”开头,YAML 会将其视为字典,因此您必须对其进行引用,如下所示
foo: "{{ variable }}"
如果您的值以引号开头,则必须引用整个值,而不仅仅是部分值。以下是一些有关如何正确引用内容的其他示例
foo: "{{ variable }}/additional/string/literal"
foo2: "{{ variable }}\\backslashes\\are\\also\\special\\characters"
foo3: "even if it is just a string literal it must all be quoted"
无效
foo: "E:\\path\\"rest\\of\\path
除了 '
和 "
之外,还有许多字符是特殊的(或保留的),不能用作未加引号的标量的第一个字符:[] {} > | * & ! % # ` @ ,
。
您还应该注意 ? : -
。在 YAML 中,如果后面跟着非空格字符,则允许它们出现在字符串的开头,但 YAML 处理器实现有所不同,因此最好使用引号。
在流集合中,规则更加严格
a scalar in block mapping: this } is [ all , valid
flow mapping: { key: "you { should [ use , quotes here" }
布尔转换很有用,但当您想要将 yes 或其他布尔值作为字符串字面量时,这可能是一个问题。在这些情况下,只需使用引号即可
non_boolean: "yes"
other_string: "False"
YAML 将某些字符串转换为浮点值,例如字符串 1.0。如果您需要指定版本号(例如,在 requirements.yml 文件中),则如果该值看起来像浮点值,则需要对其进行引用
version: "1.0"
另请参阅
- 使用 playbook
了解 playbook 的功能以及如何编写/运行它们。
- YAMLLint
YAML Lint(在线)可以帮助您调试 YAML 语法(如果遇到问题)
- 维基百科 YAML 语法参考
YAML 语法的良好指南
- YAML 1.1 规范
YAML 1.1 的规范,PyYAML 和 libyaml 目前正在实现该规范
- YAML 1.2 规范
为了完整起见,YAML 1.2 是 1.1 的后续版本
- 沟通
有问题?需要帮助?想分享您的想法?请访问 Ansible 沟通指南