AWS SAM CLI 組態檔案

AWS Serverless Application Model 命令列界面 (AWS SAM CLI) 支援專案層級組態檔案，可用來設定 AWS SAM CLI命令參數值。

如需建立和使用組態檔案的文件，請參閱 設定 AWS SAM CLI。

預設組態檔案設定

AWS SAM 使用以下預設組態檔案設定：

• Name (名稱) – samconfig。

• 位置 – 位於專案的根目錄。這與 template.yaml 檔案的位置相同。

• 格式 – TOML。若要進一步了解，請參閱 TOML 文件中的 TOML。

以下是包含預設組態檔案名稱和位置的範例專案結構：

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會先尋找此檔案。

2. 預設samconfig.toml檔案 – 這是位於專案根目錄的預設組態檔案名稱和格式。如果您未指定自訂組態檔案，則 AWS SAM CLI會接著尋找此檔案。

3. 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刪除特定項目，以便全域值。