本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# AWS SAMCLI 配置文件
<a name="serverless-sam-cli-config"></a>

 AWS Serverless Application Model 命令行界面 (AWS SAMCLI) 支持可用于配置 AWS SAMCLI命令参数值的项目级配置文件。

有关创建和使用配置文件的文档，请参阅[配置 AWS SAM CLI](using-sam-cli-configure.md)。

**Topics**
+ [默认配置文件设置](#serverless-sam-cli-config-default)
+ [支持的配置文件格式](#serverless-sam-cli-config-formats)
+ [指定配置文件](#serverless-sam-cli-config-specify)
+ [配置文件基础](#serverless-sam-cli-config-basics)
+ [参数值规则](#serverless-sam-cli-config-rules)
+ [配置优先级](#serverless-sam-cli-config-precedence)
+ [创建和修改配置文件](#serverless-sam-cli-config-using)

## 默认配置文件设置
<a name="serverless-sam-cli-config-default"></a>

AWS SAM 使用以下默认配置文件设置：
+ **名称** – `samconfig`。
+ **位置** - 位于项目的根目录中。此位置与 `template.yaml` 文件的位置相同。
+ **格式** – `TOML`。要了解更多信息，请参阅*TOML 文档*中的[TOML](https://toml.io/en/)。

以下是一个包含默认配置文件名和位置的示例项目结构：

```
sam-app
├── README.md
├── __init__.py
├── events
├── hello_world
├── samconfig.toml
├── template.yaml
└── tests
```

以下是 `samconfig.toml` 文件示例：

```
...
version = 0.1

[default]
[default.global]
[default.global.parameters]
stack_name = "sam-app"

[default.build.parameters]
cached = true
parallel = true

[default.deploy.parameters]
capabilities = "CAPABILITY_IAM"
confirm_changeset = true
resolve_s3 = true

[default.sync.parameters]
watch = true

[default.local_start_api.parameters]
warm_containers = "EAGER"

[prod]
[prod.sync]
[prod.sync.parameters]
watch = false
```

## 支持的配置文件格式
<a name="serverless-sam-cli-config-formats"></a>

支持 `TOML` 和 `[YAML|YML]` 格式。请参阅以下基本语法：

### TOML
<a name="serverless-sam-cli-config-formats-toml"></a>

```
version = 0.1
[environment]
[environment.command]
[environment.command.parameters]
option = parameter value
```

### YAML
<a name="serverless-sam-cli-config-formats-yaml"></a>

```
version: 0.1
environment:
  command:
    parameters:
      option: parameter value
```

## 指定配置文件
<a name="serverless-sam-cli-config-specify"></a>

默认情况下， AWS SAM CLI 按以下顺序查找配置文件：

1. **自定义配置文件** - 如果您使用 `--config-file` 选项指定了文件名和位置， AWS SAM CLI 会先查找此文件。

1. **默认 `samconfig.toml` 文件** - 这是默认配置文件名和格式，位于项目的根目录中。如果您未指定自定义配置文件，则 AWS SAM CLI 接下来会查找此文件。

1. **`samconfig.[yaml|yml]` 文件** - 如果 `samconfig.toml` 不存在于项目的根目录中，则 AWS SAM CLI 会查找此文件。

以下示例说明了如何使用 `--config-file` 选项指定自定义配置文件：

```
$ sam deploy --config-file myconfig.yaml
```

**注意**  
该`--config-file`参数必须相对于 AWS SAM 模板文件的位置，因为 AWS SAMCLI需要确定应用配置的上下文。该`samconfig.toml`文件管理您的版本的配置设置 AWS SAMCLI，CLI 将在`samconfig.toml`文件的相对文件夹中查找文件（或覆盖的配置文件参数）。`template.yaml`

## 配置文件基础
<a name="serverless-sam-cli-config-basics"></a>

### 环境
<a name="serverless-sam-cli-config-basics-environment"></a>

**环境**是包含一组唯一配置设置的命名标识符。你可以在一个 AWS SAM 应用程序中拥有多个环境。

默认环境名称是 `default`。

使用 AWS SAMCLI`--config-env`选项指定要使用的环境。

### 命令
<a name="serverless-sam-cli-config-basics-command"></a>

**命令**是要为其指定参数值的 AWS SAM CLI 命令。

要为所有命令指定参数值，请使用 `global` 标识符。

引用 AWS SAM CLI 命令时，请将空格 (` `) 和连字符 (`–`) 替换为下划线 (`_`)。请参阅以下示例：
+ `build`
+ `local_invoke`
+ `local_start_api`

### 参数
<a name="serverless-sam-cli-config-basics-parameters"></a>

**参数**指定为键值对。
+ **键**是 AWS SAM CLI 命令选项名称。
+ **值**是要指定的值。

指定键时，请使用长格式的命令选项名称，并将连字符 (`–`) 替换为下划线 (`_`)。示例如下：
+ `region`
+ `stack_name`
+ `template_file`

## 参数值规则
<a name="serverless-sam-cli-config-rules"></a>

### TOML
<a name="serverless-sam-cli-config-rules-toml"></a>
+ 布尔值可以是 `true` 或 `false`。例如 `confirm_changeset = true`。
+ 对于字符串值，请使用引号 (`""`)。例如 `region = "us-west-2"`。
+ 对于列表值，请使用引号 (`""`)，并使用空格 (` `) 分隔每个值。例如：`capabilities = "CAPABILITY_IAM CAPABILITY_NAMED_IAM"`。
+ 对于包含键值对列表的值，这些键值对以空格分隔 (` `)，并且每对的值用编码的引号 (`\" \"`) 括起。例如 `tags = "project=\"my-application\" stage=\"production\""`。
+ 对于可以多次指定的参数值，值是参数数组。例如：`image_repositories = ["my-function-1=image-repo-1", "my-function-2=image-repo-2"]`。

### YAML
<a name="serverless-sam-cli-config-rules-yaml"></a>
+ 布尔值可以是 `true` 或 `false`。例如 `confirm_changeset: true`。
+ 对于包含单个字符串值的条目，引号 (`""`) 是可选的。例如 `region: us-west-2`。这包括包含以单个字符串形式提供的多个键值对的条目。以下是示例：

  ```
  $ sam deploy --tags "foo=bar hello=world"
  ```

  ```
  default:
    deploy:
      parameters:
        tags: foo=bar hello=world
  ```
+ 对于包含值列表的条目或可在单个命令中多次使用的条目，请将其指定为字符串列表。

  以下是示例：

  ```
  $ sam remote invoke --parameter "InvocationType=Event" --parameter "LogType=None"
  ```

  ```
  default:
    remote_invoke:
      parameters:
          parameter:
          - InvocationType=Event
          - LogType=None
  ```

## 配置优先级
<a name="serverless-sam-cli-config-precedence"></a>

配置值时，以下优先级适用：
+ 在命令行中提供的参数值优先于配置文件和模板文件 `Parameters` 部分中相应的值。
+ 如果在命令行或带有 `parameter_overrides` 键的配置文件中使用 `--parameter-overrides` 选项，则其值优先于模板文件 `Parameters` 部分中的值。
+ 在配置文件中，为特定命令提供的条目优先于全局条目。在以下示例中，`sam deploy` 命令使用堆栈名称 `my-app-stack`。

------
#### [ TOML ]

  ```
  [default.global.parameters]
  stack_name = "common-stack"
  
  [default.deploy.parameters]
  stack_name = "my-app-stack"
  ```

------
#### [ YAML ]

  ```
  default:
    global:
      parameters:
        stack_name: common-stack
    deploy:
      parameters:
        stack_name: my-app-stack
  ```

------

## 创建和修改配置文件
<a name="serverless-sam-cli-config-using"></a>

### 创建配置文件
<a name="serverless-sam-cli-config-using-create"></a>

使用 `sam init` 创建应用程序时，系统会创建默认 `samconfig.toml` 文件。您也可以手动创建配置文件。

### 修改配置文件
<a name="serverless-sam-cli-config-using-modify"></a>

您可以手动修改配置文件。此外，在任何 AWS SAM CLI 交互式流程中，配置的值都会显示在方括号 (`[ ]`) 中。如果您修改这些值， AWS SAM CLI 会更新配置文件。

以下是使用 `sam deploy --guided` 命令的交互式流程的示例：

```
$ sam deploy --guided

Configuring SAM deploy
======================

    Looking for config file [samconfig.toml] :  Found
    Reading default arguments  :  Success

    Setting default arguments for 'sam deploy'
    =========================================
    Stack Name [sam-app]: ENTER
    AWS Region [us-west-2]: ENTER
    #Shows you resources changes to be deployed and require a 'Y' to initiate deploy
    Confirm changes before deploy [Y/n]: n
    #SAM needs permission to be able to create roles to connect to the resources in your template
    Allow SAM CLI IAM role creation [Y/n]: ENTER
    #Preserves the state of previously provisioned resources when an operation fails
    Disable rollback [y/N]: ENTER
    HelloWorldFunction may not have authorization defined, Is this okay? [y/N]: y
    Save arguments to configuration file [Y/n]: ENTER
    SAM configuration file [samconfig.toml]: ENTER
    SAM configuration environment [default]: ENTER
```

修改配置文件时， AWS SAM CLI 会按如下方式处理全局值：
+ 如果参数值存在于配置文件的 `global` 部分中， AWS SAM CLI 不会将值写入到特定的命令部分。
+ 如果参数值同时存在于 `global` 部分和特定的命令部分中， AWS SAM  CLI 会删除特定条目，以支持使用全局值。