本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS SAM CLI 組態檔案
AWS Serverless Application Model 命令列界面 (AWS SAM CLI) 支援專案層級組態檔案，可用來設定 AWS SAM CLI命令參數值。
如需建立和使用組態檔案的文件，請參閱 [設定 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)
## 預設組態檔案設定
AWS SAM 使用以下預設組態檔案設定：
+ **Name** (名稱) – `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
```
## 支援的組態檔案格式
`TOML` 支援 和 `[YAML|YML]` 格式。請參閱下列基本語法：
### TOML
```
version = 0.1
[environment]
[environment.command]
[environment.command.parameters]
option = parameter value
```
### YAML
```
version: 0.1
environment:
command:
parameters:
option: parameter value
```
## 指定組態檔案
根據預設， 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 SAM CLI需要判斷套用組態的內容。`samconfig.toml` 檔案會管理您 版本的組態設定 AWS SAM CLI，而 CLI 會在 `samconfig.toml` 檔案的相對資料夾中尋找 `template.yaml` 檔案 （或覆寫組態檔案參數）。
## 組態檔案基本概念
### Environment
**環境**是具名識別符，其中包含一組唯一的組態設定。您可以在單一 AWS SAM 應用程式中擁有多個環境。
預設環境名稱為 `default`。
使用 AWS SAM CLI`--config-env`選項來指定要使用的環境。
### 命令
**命令**是 AWS SAM CLI指定 參數值的命令。
若要為所有命令指定參數值，請使用 `global`識別符。
參考命令 AWS SAM CLI時，請以底線 (` `) 取代空格 (`–`) 和連字號 ()`_`。請參閱以下範例：
+ `build`
+ `local_invoke`
+ `local_start_api`
### Parameters
**參數**指定為鍵/值對。
+ **索引鍵**是 AWS SAM CLI命令選項名稱。
+ **值**是要指定的值。
指定金鑰時，請使用長格式的命令選項名稱，並以底線 (`–`) 取代連字號 ()`_`。範例如下：
+ `region`
+ `stack_name`
+ `template_file`
## 參數值規則
### TOML
+ 布林值可以是 `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
+ 布林值可以是 `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
```
## 組態優先順序
設定值時，會發生下列優先順序：
+ 您在命令列提供的參數值優先於組態檔案和範本檔案`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
```
------
## 建立和修改組態檔案
### 建立組態檔案
當您使用 建立應用程式時`sam init`，會建立預設`samconfig.toml`檔案。您也可以手動建立組態檔案。
### 修改組態檔案
您可以手動修改您的組態檔案。此外，在任何 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刪除特定項目，以便全域值。