YAML 语法

本页提供有关正确 YAML 语法的基本概述，这是 Ansible 剧本（我们的配置管理语言）表达的方式。

我们使用 YAML，因为它比其他常见的格式（如 XML 或 JSON）更容易让人类阅读和编写。此外，大多数编程语言中都有可用于处理 YAML 的库。

您可能还想同时阅读使用剧本，以了解如何在实践中使用它。

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 剧本真正需要了解的有关 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"

另请参见

使用剧本: 了解剧本可以做什么以及如何编写/运行它们。
YAMLLint: YAML Lint（在线）可以帮助您调试 YAML 语法，如果您遇到问题。
维基百科 YAML 语法参考: 有关 YAML 语法的良好指南。
YAML 1.1 规范: PyYAML 和 libyaml 目前正在实施的 YAML 1.1 规范。
YAML 1.2 规范: 为了完整起见，YAML 1.2 是 1.1 的后续版本。
沟通: 有问题吗？需要帮助吗？想分享您的想法吗？请访问 Ansible 沟通指南。