本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# CloudFormation 組態屬性參考
<a name="continuous-delivery-codepipeline-action-reference"></a>

當您建置 CodePipeline 管道時，您可以將`Deploy`動作以 CloudFormation 做為提供者新增至管道。然後，您必須指定管道叫用 CloudFormation 的動作和動作的設定。本主題說明 CloudFormation 組態屬性。若要指定屬性，您可以使用 CodePipeline 主控台，也可以建立 JSON 物件以用於 AWS CLI、CodePipeline API 或 CloudFormation 範本。

**Topics**
+ [組態屬性 (主控台)](#continuous-delivery-codepipeline-action-reference-console)
+ [組態屬性 (JSON 物件)](#continuous-delivery-codepipeline-action-reference-json)
+ [另請參閱](#continuous-delivery-codepipeline-action-reference-see-also)

## 組態屬性 (主控台)
<a name="continuous-delivery-codepipeline-action-reference-console"></a>

CodePipeline [主控台](https://console.aws.amazon.com/codepipeline/)會顯示組態屬性，根據您選擇的動作模式指示哪些屬性為必要項目。

**注意**  
當您建立管道時，您只能指定 **Create or update a stack (建立或更新堆疊)** 或 **Create or replace a change set (建立或取代變更組)** 動作模式。**Advanced (進階)** 區段中的屬性只有在您編輯管道時才可使用。

**Action mode (動作模式)**  
CodePipeline 在處理關聯階段時呼叫 CloudFormation 的動作。選擇下列其中一個動作模式：  
+ **Create or replace a change set (建立或取代變更組)** 會根據您提交的堆疊名稱和範本建立變更組 (若不存在的話)。如果變更集存在， 會將其 CloudFormation 刪除，然後建立新的變更集。
+ **Create or update a stack (建立或更新堆疊)** 會在指定堆疊不存在時建立堆疊。如果堆疊存在， 會 CloudFormation 更新堆疊。使用此動作來更新現有堆疊。CodePipeline 不會取代堆疊。
+ **Delete a stack (刪除堆疊)** 刪除堆疊。若您指定不存在的堆疊，動作會成功完成，而不會刪除任何堆疊。
+ **Execute a change set (執行變更組)** 執行變更組。
+ **Replace a failed stack (取代故障堆疊)** 會在指定堆疊不存在時建立堆疊。如果堆疊存在且處於失敗狀態 （報告為 `ROLLBACK_COMPLETE`、`ROLLBACK_FAILED`、`DELETE_FAILED`、 或 `UPDATE_ROLLBACK_FAILED`)`CREATE_FAILED`， 會 CloudFormation 刪除堆疊，然後建立新的堆疊。如果堆疊未處於失敗狀態， 會 CloudFormation 更新它。使用此動作來取代故障的堆疊，無須復原或故障診斷。您通常會選擇此模式以進行測試。

**Stack name (堆疊名稱)**  
與現有堆疊或您希望建立的堆疊建立關聯的名稱。在您 AWS 建立堆疊的區域中，名稱必須是唯一的。  
堆疊名稱僅能使用英數字元 (區分大小寫) 和連字號。必須以字母字元開頭，且長度不可超過 128 個字元。

**Change set name (變更組合名稱)**  
現有變更組或您希望為指定堆疊建立之新變更組的名稱。

**Template (範本)**  
 CloudFormation 範本檔案的位置，其格式為 `{{ArtifactName}}::{{TemplateFileName}}`。

**Template configuration (範本組態)**  
範本組態檔案的位置，其格式為 `{{ArtifactName}}::{{TemplateConfigurationFileName}}`。範本組態檔案可包含範本參數值、堆疊政策和標籤。若您在其中包含敏感資訊 (例如密碼)，請限制此檔案的存取。如需詳細資訊，請參閱[CloudFormation 成品](continuous-delivery-codepipeline-cfn-artifacts.md)。

**功能**  
對於包含特定資源的堆疊，明確認可 CloudFormation 可能會建立或更新這些資源。例如，若您的堆疊範本包含 AWS Identity and Access Management (IAM) 資源，您必須指定 `CAPABILITY_IAM`。如需詳細資訊，請參閱 [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) API 操作請求參數。  
若您在您的堆疊範本中具有 IAM 資源，您必須指定此屬性。  
您可以指定多個功能。

**Role name (角色名稱)**  
在指定堆疊中的資源上操作時， CloudFormation 擔任的 IAM 服務角色名稱。

**Output file name (輸出檔案名稱)**  
在 **Advanced (進階)** 區段中，您可以指定輸出檔案名稱 (例如 `CreateStackOutput.json`)，CodePipeline 會在執行指定動作之後將其新增至[輸出成品](https://docs.aws.amazon.com/codepipeline/latest/userguide/concepts.html#concepts-artifacts)。輸出成品包含 JSON 檔案，其中包含 CloudFormation 範本 `Outputs`區段的內容。  
若您沒有指定名稱，CodePipeline 便不會產生輸出成品。

**Parameter overrides (參數覆寫)**  
參數是在您的範本中定義，而且可讓您在建立或更新堆疊時輸入自訂值。您可以指定覆寫範本組態檔案中範本參數值的 JSON 物件。所有參數名稱都必須在堆疊範本中存在。如需詳細資訊，請參閱[CloudFormation 範本 Parameters 語法](parameters-section-structure.md)。  
能存放在 `ParameterOverrides` 屬性的 JSON 物件具有 1 KB 的最大大小限制。
我們建議您使用範本組態檔案來指定您大多數的參數值。僅使用參數覆寫來指定動態參數值。除非您執行管道，否則動態參數是未知的。  
下列範例會使用參數覆寫函數定義 `ParameterName` 參數的值。函數會從 CodePipeline 輸入成品擷取值。如需參數覆寫函數的詳細資訊，請參閱[搭配 CodePipeline 管道使用參數覆寫函數](continuous-delivery-codepipeline-parameter-override-functions.md)。  

```
{
  "ParameterName" : { "Fn::GetParam" : ["ArtifactName", "config-file-name.json", "ParamName"]}
}
```

## 組態屬性 (JSON 物件)
<a name="continuous-delivery-codepipeline-action-reference-json"></a>

當您指定 `CloudFormation` 作為階段動作的提供者時，請在 `Configuration` 屬性中定義以下屬性。將 JSON 物件用於 AWS CLI、CodePipeline API 或 CloudFormation 範本。如需範例，請參閱 [逐步解說：建置管線以用於測試和生產堆疊](continuous-delivery-codepipeline-basic-walkthrough.md) 和 [CloudFormation 組態屬性參考](#continuous-delivery-codepipeline-action-reference)。

`ActionMode`  
CodePipeline 在處理關聯階段時呼叫 CloudFormation 的動作。僅指定下列其中一個動作模式：  
+ `CHANGE_SET_EXECUTE` 執行變更集。
+ `CHANGE_SET_REPLACE` 根據您提交的堆疊名稱和範本建立變更組 (若不存在的話)。如果變更集存在， 會將其 CloudFormation 刪除，然後建立新的變更集。
+ `CREATE_UPDATE` 在指定堆疊不存在時建立堆疊。若堆疊存在，則 CloudFormation 會更新堆疊。使用此動作來更新現有堆疊。CodePipeline 不會取代堆疊。
+ `DELETE_ONLY` 刪除堆疊。若您指定不存在的堆疊，動作會成功完成，而不會刪除任何堆疊。
+ `REPLACE_ON_FAILURE` 在指定堆疊不存在時建立堆疊。如果堆疊存在且處於失敗狀態 `ROLLBACK_FAILED`（報告為 `ROLLBACK_COMPLETE`、`DELETE_FAILED`、、 或 `UPDATE_ROLLBACK_FAILED`)`CREATE_FAILED`， 會 CloudFormation 刪除堆疊，然後建立新的堆疊。如果堆疊未處於失敗狀態， 會 CloudFormation 更新它。使用此動作來自動取代故障的堆疊，無須復原或故障診斷。您通常會選擇此模式以進行測試。
此屬性為必要。

`Capabilities`  
對於包含特定資源的堆疊，明確認可 CloudFormation 可能會建立或更新這些資源。例如，若您的堆疊範本包含 AWS Identity and Access Management (IAM) 資源，您必須指定 `CAPABILITY_IAM`。如需詳細資訊，請參閱 [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) API 操作請求參數。  
此屬性為條件式。若您在您的堆疊範本中具有 IAM 資源，您必須指定此屬性。  
您可以指定多個功能。下列範例會將 `CAPABILITY_IAM` 和 `CAPABILITY_AUTO_EXPAND` 屬性新增至範本：  

```
configuration:
  ActionMode: CHANGE_SET_REPLACE
  {{Capabilities: CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND}}
  ChangeSetName: pipeline-changeset
  RoleArn: CloudFormation_Role_ARN
  StackName: my-pipeline-stack
  TemplateConfiguration: 'my-pipeline-stack::template-configuration.json'
  TemplatePath: 'my-pipeline-stack::template-export.yml'
```

```
 "configuration": {
        "ActionMode": "CHANGE_SET_REPLACE",
        {{"Capabilities": "CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND",}}
        "ChangeSetName": "pipeline-changeset",
        "RoleArn": "CloudFormation_Role_ARN",
        "StackName": "my-pipeline-stack",
        "TemplateConfiguration": "my-pipeline-stack::template-configuration.json",
        "TemplatePath": "my-pipeline-stack::template-export.yml"
    }
```

`ChangeSetName`  
現有變更組或您希望為指定堆疊建立之新變更組的名稱。  
針對下列動作模式，此屬性為必要：`CHANGE_SET_REPLACE` 和 `CHANGE_SET_EXECUTE`。針對其他所有動作模式，可忽略此屬性。

`OutputFileName`  
輸出檔案的名稱，例如 `CreateStackOutput.json`。CodePipeline 會在執行指定動作之後將檔案新增至[輸出成品](https://docs.aws.amazon.com/codepipeline/latest/userguide/concepts.html#concepts-artifacts)。輸出成品包含 JSON 檔案，其中包含 CloudFormation 範本 `Outputs`區段的內容。  
此屬性為選擇性。若您沒有指定名稱，CodePipeline 便不會產生輸出成品。

`ParameterOverrides`  
參數是在您的範本中定義，而且可讓您在建立或更新堆疊時輸入自訂值。您可以指定覆寫範本組態檔案中範本參數值的 JSON 物件。所有參數名稱都必須在堆疊範本中存在。如需詳細資訊，請參閱[CloudFormation 範本 Parameters 語法](parameters-section-structure.md)。  
下列範例會將 `InstanceType` 和 `KeyName` 參數覆寫新增至範本：  

```
configuration:
  ActionMode: CHANGE_SET_REPLACE
  Capabilities: CAPABILITY_NAMED_IAM
  ChangeSetName: pipeline-changeset
  {{ParameterOverrides: '{"InstanceType": "t2.small","KeyName": "my-keypair"}'}}
  RoleArn: CloudFormation_Role_ARN
  StackName: my-pipeline-stack
  TemplateConfiguration: 'my-pipeline-stack::template-configuration.json'
  TemplatePath: 'my-pipeline-stack::template-export.yml'
```

```
"configuration": {
        "ActionMode": "CHANGE_SET_REPLACE",
        "Capabilities": "CAPABILITY_NAMED_IAM",
        "ChangeSetName": "pipeline-changeset",
        {{"ParameterOverrides": "{\"InstanceType\": \"t2.small\",\"KeyName\": \"my-keypair\"}",}}
        "RoleArn": "CloudFormation_Role_ARN",
        "StackName": "my-pipeline-stack",
        "TemplateConfiguration": "my-pipeline-stack::template-configuration.json",
        "TemplatePath": "my-pipeline-stack::template-export.yml"
    }
```
可存放至 `ParameterOverrides` 屬性的 JSON 物件大小上限為 1 KB。
我們建議您使用範本組態檔案來指定您大多數的參數值。僅使用參數覆寫來指定動態參數值。除非您執行管道 , 否則動態參數值都是未知的。  
下列範例會使用參數覆寫函數定義 `ParameterName` 參數的值。函數會從 CodePipeline 輸入成品擷取值。如需參數覆寫函數的詳細資訊，請參閱[搭配 CodePipeline 管道使用參數覆寫函數](continuous-delivery-codepipeline-parameter-override-functions.md)。  

```
{
  "ParameterName" : { "Fn::GetParam" : ["ArtifactName", "config-file-name.json", "ParamName"]}
}
```
此屬性為選擇性。

`RoleArn`  
IAM 服務角色的 Amazon Resource Name (ARN)，其會在堆疊中的資源上操作時 CloudFormation 擔任。  
針對下列動作模式，此屬性為必要：`CREATE_UPDATE`、`REPLACE_ON_FAILURE`、`DELETE_ONLY` 及 `CHANGE_SET_REPLACE`。執行變更集時，不會套用 `RoleArn`。若您不使用 CodePipeline 來建立變更集，請確定變更集或堆疊具有關聯角色。

`StackName`  
現有堆疊或您希望建立之堆疊的名稱。  
針對所有動作模式，此屬性為必要。

`TemplateConfiguration`  
`TemplateConfiguration` 是範本組態檔案。您將檔案包含在此動作的輸入成品中。範本組態檔案名稱遵循此格式：  
`{{Artifactname}}::{{TemplateConfigurationFileName}}`  
`Artifactname` 是出現在 CodePipeline 中的輸入成品名稱。例如，來源階段的成品名稱為 `SourceArtifact` 且 `test-configuration.json` 檔案名稱建立 `TemplateConfiguration` 名稱，如此範例所顯示：  

```
"TemplateConfiguration": "SourceArtifact::test-configuration.json"
```
範本組態檔案可包含範本參數值和堆疊政策。若您在其中包含敏感資訊 (例如密碼)，請限制此檔案的存取。如需範例範本組態檔，請參閱 [CloudFormation 成品](continuous-delivery-codepipeline-cfn-artifacts.md)。  
此屬性為選擇性。

`TemplatePath`  
`TemplatePath` 代表 CloudFormation 範本檔案。您將檔案包含在此動作的輸入成品中。該檔案名稱遵循此格式：  
`{{Artifactname}}::{{TemplateFileName}}`  
`Artifactname` 是出現在 CodePipeline 中的輸入成品名稱。例如，來源階段的成品名稱為 `SourceArtifact` 且 `template.yaml` 檔案名稱建立 `TemplatePath` 名稱，如此範例所顯示：  

```
"TemplatePath": "SourceArtifact::template.yaml"
```
針對下列動作模式，此屬性為必要：`CREATE_UPDATE`、`REPLACE_ON_FAILURE` 和 `CHANGE_SET_REPLACE`。針對其他所有動作模式，可忽略此屬性。

## 另請參閱
<a name="continuous-delivery-codepipeline-action-reference-see-also"></a>

以下相關資源可協助您使用這些參數。
+ 如需有關 CodePipeline 中 CloudFormation 動作參數的詳細資訊，請參閱《AWS CodePipeline 使用者指南》**中的 [CloudFormation 部署動作組態參考](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CloudFormation.html)。
+ 如需動作提供者的範例範本值 (例如 `Owner` 欄位或 `configuration` 欄位)，請參閱 *AWS CodePipeline User Guide* (《 使用者指南》) 中的 [Action structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference.html) (動作結構參考)。
+ 若要下載 YAML 或 JSON 格式的管道堆疊範本範例，請參閱《AWS CodePipeline 使用者指南》中的[教學課程：使用 CloudFormation建立管道](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-cloudformation.html)。**