這是新的 *CloudFormation 範本參考指南*。請更新您的書籤和連結。如需 CloudFormation 入門的說明，請參閱 [AWS CloudFormation 使用者指南](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 規格格式
CloudFormation 會建立每種資源類型的規格，例如 `AWS::S3::Bucket` 或 `AWS::EC2::Instance`。下列各節會說明格式及規格的每個欄位。
**Topics**
+ [規格區段](#w2aac37b9c23b7)
+ [屬性規格](#cfn-resource-specification-format-propertytypes)
+ [資源規格](#cfn-resource-specification-format-resourcetype)
+ [範例資源規格](#w2aac37b9c23c13)
## 規格區段
每種資源類型的正式定義分為三大區段：`PropertyTypes`、`ResourceSpecificationVersion` 和 `ResourceTypes`，如下列範例所示：
```
{
"PropertyTypes": {
*Property specifications*
},
"ResourceSpecificationVersion": "Specification version number",
"ResourceTypes": {
*Resource specification*
}
}
```
`PropertyTypes`
在屬性內有屬性 (也稱為子屬性) 的資源，為子屬性規格清單，例如需要哪些屬性、每個屬性允許的值類型及其更新行為。如需詳細資訊，請參閱[屬性規格](#cfn-resource-specification-format-propertytypes)。
如果資源沒有子屬性，會略過這個區段。
`ResourceSpecificationVersion`
資源規格的版本。版本格式為 `majorVersion.minorVersion.patch`，每個版次都會增加版本號碼。無論資源是否更新，所有資源都有相同的版本號碼。
當服務提供回溯相容性錯誤修正，例如修復中斷的文件連結時，CloudFormation 會遞增修補程式數目。當 CloudFormation 新增可回溯相容的資源或屬性時，次要版本號碼會遞增。例如，更新版本的規格可能會新增其他資源屬性，以支援 AWS 服務的新功能。
回溯不相容變更會遞增主要版本號碼。回溯不相容變更的成因可能是資源規格變更 (例如欄位的名稱變更)，或資源變更 (例如建立選用資源屬性)。
`ResourceTypes`
每個資源屬性的資源和資訊清單，例如其屬性名稱、所需屬性，以及其更新行為。如需詳細資訊，請參閱[資源規格](#cfn-resource-specification-format-resourcetype)。
如果您檢視包含一個資源類型定義的檔案，此屬性名稱為 `ResourceType` (單數)。
## 屬性規格
每個屬性的規格都包含下列欄位。子屬性的屬性名稱使用 `resourceType.subpropertyName` 格式。
```
"Property name": {
"Documentation": "Link to the relevant documentation"
"DuplicatesAllowed": "true or false",
"ItemType": "Type of list or map (non-primitive)",
"PrimitiveItemType": "Type of list or map (primitive)",
"PrimitiveType": "Type of value (primitive)",
"Required": "true or false",
"Type": "Type of value (non-primitive)",
"UpdateType": "Mutable, Immutable, or Conditional",
}
```
`Documentation`
提供有關屬性資訊的《AWS CloudFormation 使用者指南》的連結。**
`DuplicatesAllowed`
如果 `Type` 欄位的值為 `List`，則會指出 CloudFormation 是否允許重複的值。如果該值為 `true`，則 CloudFormation 會忽略重複的值。如果值為 `false`，則 CloudFormation 會在您提交重複的值時傳回錯誤。
`ItemType`
如果 `Type` 欄位的值是 `List` 或 `Map`，會指示清單或映射的類型是否包含非基本類型。否則，略過此欄位。針對包含基本類型的清單或映射，`PrimitiveItemType` 屬性會指示有效的值類型。
子屬性名稱是有效的項目類型。例如，如果類型值是 `List` 而項目類型值是 `PortMapping`，您可以指定連接埠映射屬性的清單。
`PrimitiveItemType`
如果 `Type` 欄位的值是 `List` 或 `Map`，會指示清單或映射的類型是否包含基本類型。否則，略過此欄位。針對包含非基本類型的清單或映射，`ItemType` 屬性會指示有效的值類型。
有效的清單和映射基本類型為 `String`、`Long`、`Integer`、`Double`、`Boolean` 或 `Timestamp`。
例如，如果類型值是 `List` 而項目類型值是 `String`，您可以指定屬性的字串清單。如果類型值是 `Map` 而項目類型值是 `Boolean`，您可以指定屬性的布林值映射字串。
`PrimitiveType`
針對基本值，為屬性的有效基本類型。基本類型是資源屬性值的基本資料類型。有效的基本類型為 `String`、`Long`、`Integer`、`Double`、`Boolean`、`Timestamp` 或 `Json`。如果有效值為非基本類型，則略過此欄位，且 `Type` 欄位會指示有效值類型。
`Required`
指示屬性是否為必要。
`Type`
針對非基本類型，為屬性的有效值。有效的類型是子屬性名稱 `List` 或 `Map`。如果有效值為基本類型，則略過此欄位，且 `PrimitiveType` 欄位會指示有效值類型。
清單是以逗號分隔的值清單。映射是一組鍵/值對，其中的金鑰一律為字串。清單和映射的值類型由 `ItemType` 或 `PrimitiveItemType` 欄位指示。
`UpdateType`
在堆疊更新期間，當您新增、移除或修改屬性時的更新行為。當您變更不可變屬性時，CloudFormation 會取代資源。當您變更可變屬性時，CloudFormation 不會取代資源。條件式更新可變或不可變，例如，取決於您更新的其他屬性。如需詳細資訊，請參閱[AWS 資源和屬性類型參考](aws-template-resource-type-ref.md)。
## 資源規格
每個資源類型的規格都包含下列欄位。
```
"Resource type name": {
"Attributes": {
"AttributeName": {
"ItemType": "Return list or map type (non-primitive)",
"PrimitiveItemType": "Return list or map type (primitive)",
"PrimitiveType": "Return value type (primitive)",
"Type": "Return value type (non-primitive)",
}
},
"Documentation": "Link to the relevant documentation",
"Properties": {
*Property specifications*
}
}
```
`Attributes`
您可以在 [`Fn::GetAtt`](intrinsic-function-reference-getatt.md) 函數中使用的資源屬性清單。每個屬性的這個區段都會提供屬性名稱和 CloudFormation 傳回的值類型。
`ItemType`
如果 `Type` 欄位的值是 `List`，指示清單包含非基本類型時，`Fn::GetAtt` 函數傳回的屬性清單類型。有效的類型是屬性名稱。
`PrimitiveItemType`
如果 `Type` 欄位的值是 `List`，指示清單包含基本類型時，`Fn::GetAtt` 函數傳回的屬性清單類型。針對包含非基本類型的清單，`ItemType` 屬性會指示有效的值類型。有效的清單基本類型為 `String`、`Long`、`Integer`、`Double`、`Boolean` 或 `Timestamp`。
例如，如果類型值是 `List` 而基本項目類型值是 `String`，則 `Fn::GetAtt` 函數會傳回字串清單。
`PrimitiveType`
針對基本傳回值，為 `Fn::GetAtt` 函數傳回的屬性基本值類型。基本類型是資源屬性值的基本資料類型。有效的基本類型為 `String`、`Long`、`Integer`、`Double`、`Boolean`、`Timestamp` 或 `Json`。
`Type`
針對非基本傳回值，為 `Fn::GetAtt` 函數傳回的屬性值類型。有效的類型是屬性名稱或 `List`。
清單是以逗號分隔的值清單。清單的值類型由 `ItemType` 或 `PrimitiveItemType` 欄位指示。
`Documentation`
《AWS CloudFormation 使用者指南》的連結，可提供資源資訊。**
`Properties`
資源的屬性規格清單。如需詳細資訊，請參閱[屬性規格](#cfn-resource-specification-format-propertytypes)。
## 範例資源規格
下列範例強調和說明 [AWS::Elasticsearch::Domain](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-elasticsearch-domain.html) 資源規格的部分。
`AWS::Elasticsearch::Domain` 資源類型包含子屬性，因此規格包含 `PropertyTypes` 區段。此區段後面接著 `ResourceSpecificationVersion` 區段，規格版本顯示為 `1.0.0`。規格版本之後是指定資源類型的 `ResourceType` 區段，提供文件連結及資源屬性的詳細資訊。
```
{
"PropertyTypes": {
...
},
"ResourceSpecificationVersion": "1.0.0",
"ResourceType": {
"AWS::Elasticsearch::Domain": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html",
"Properties": {
...
}
}
}
}
}
```
聚焦於 `ResourceType` 區段，下列範例會顯示 `AWS::Elasticsearch::Domain` 資源類型的兩個屬性。`AdvancedOptions` 屬性非為必要，且能接受字串對字串映射。映射是一組鍵/值對，其中的金鑰一律為字串。值類型由 `ItemType` 欄位指示，它是 `String`。因此，類型是字串映射的字串。此屬性的更新行為是可變的。如果更新此屬性，CloudFormation 會保留資源，而不是建立新的資源，然後刪除舊的資源 (不可變更新)。
`SnapshotOptions` 屬性非為必要，且接受名為 `SnapshotOptions` 的子屬性。`SnapshotOptions` 區段提供 `PropertyTypes` 子屬性的詳細資訊。
```
{
"PropertyTypes": {
...
},
"ResourceSpecificationVersion": "1.0.0",
"ResourceType": {
"AWS::Elasticsearch::Domain": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html",
"Properties": {
...
"AdvancedOptions": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-advancedoptions",
"DuplicatesAllowed": false,
"PrimitiveItemType": "String",
"Required": false,
"Type": "Map",
"UpdateType": "Mutable"
},
...
"SnapshotOptions": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-snapshotoptions",
"Required": false,
"Type": "SnapshotOptions",
"UpdateType": "Mutable"
},
...
}
}
}
}
```
在 `PropertyTypes` 中，規格列出資源的所有子屬性 (包括巢狀子屬性)。下列範例詳細說明 `AWS::Elasticsearch::Domain.SnapshotOptions` 子屬性。其包含名為 `AutomatedSnapshotStartHour` 的屬性，此屬性非為必要，且接受整數值類型。
```
"PropertyTypes": {
...
"AWS::Elasticsearch::Domain.SnapshotOptions": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-snapshotoptions.html",
"Properties": {
"AutomatedSnapshotStartHour": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-snapshotoptions.html#cfn-elasticsearch-domain-snapshotoptions-automatedsnapshotstarthour",
"PrimitiveType": "Integer",
"Required": false,
"UpdateType": "Mutable"
}
}
},
...
}
```
下列範例提供完整 `AWS::Elasticsearch::Domain` 資源規格供您參考。
```
{
"PropertyTypes": {
"AWS::Elasticsearch::Domain.EBSOptions": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-ebsoptions.html",
"Properties": {
"EBSEnabled": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-ebsoptions.html#cfn-elasticsearch-domain-ebsoptions-ebsenabled",
"PrimitiveType": "Boolean",
"Required": false,
"UpdateType": "Mutable"
},
"Iops": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-ebsoptions.html#cfn-elasticsearch-domain-ebsoptions-iops",
"PrimitiveType": "Integer",
"Required": false,
"UpdateType": "Mutable"
},
"VolumeSize": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-ebsoptions.html#cfn-elasticsearch-domain-ebsoptions-volumesize",
"PrimitiveType": "Integer",
"Required": false,
"UpdateType": "Mutable"
},
"VolumeType": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-ebsoptions.html#cfn-elasticsearch-domain-ebsoptions-volumetype",
"PrimitiveType": "String",
"Required": false,
"UpdateType": "Mutable"
}
}
},
"AWS::Elasticsearch::Domain.ElasticsearchClusterConfig": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html",
"Properties": {
"DedicatedMasterCount": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html#cfn-elasticsearch-domain-elasticseachclusterconfig-dedicatedmastercount",
"PrimitiveType": "Integer",
"Required": false,
"UpdateType": "Mutable"
},
"DedicatedMasterEnabled": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html#cfn-elasticsearch-domain-elasticseachclusterconfig-dedicatedmasterenabled",
"PrimitiveType": "Boolean",
"Required": false,
"UpdateType": "Mutable"
},
"DedicatedMasterType": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html#cfn-elasticsearch-domain-elasticseachclusterconfig-dedicatedmastertype",
"PrimitiveType": "String",
"Required": false,
"UpdateType": "Mutable"
},
"InstanceCount": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html#cfn-elasticsearch-domain-elasticseachclusterconfig-instancecount",
"PrimitiveType": "Integer",
"Required": false,
"UpdateType": "Mutable"
},
"InstanceType": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html#cfn-elasticsearch-domain-elasticseachclusterconfig-instancetype",
"PrimitiveType": "String",
"Required": false,
"UpdateType": "Mutable"
},
"ZoneAwarenessEnabled": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-elasticsearchclusterconfig.html#cfn-elasticsearch-domain-elasticseachclusterconfig-zoneawarenessenabled",
"PrimitiveType": "Boolean",
"Required": false,
"UpdateType": "Mutable"
}
}
},
"AWS::Elasticsearch::Domain.SnapshotOptions": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-snapshotoptions.html",
"Properties": {
"AutomatedSnapshotStartHour": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-elasticsearch-domain-snapshotoptions.html#cfn-elasticsearch-domain-snapshotoptions-automatedsnapshotstarthour",
"PrimitiveType": "Integer",
"Required": false,
"UpdateType": "Mutable"
}
}
},
"Tag": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html",
"Properties": {
"Key": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html#cfn-resource-tags-key",
"PrimitiveType": "String",
"Required": true,
"UpdateType": "Immutable"
},
"Value": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html#cfn-resource-tags-value",
"PrimitiveType": "String",
"Required": true,
"UpdateType": "Immutable"
}
}
}
},
"ResourceType": {
"AWS::Elasticsearch::Domain": {
"Attributes": {
"DomainArn": {
"PrimitiveType": "String"
},
"DomainEndpoint": {
"PrimitiveType": "String"
}
},
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html",
"Properties": {
"AccessPolicies": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-accesspolicies",
"PrimitiveType": "Json",
"Required": false,
"UpdateType": "Mutable"
},
"AdvancedOptions": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-advancedoptions",
"DuplicatesAllowed": false,
"PrimitiveItemType": "String",
"Required": false,
"Type": "Map",
"UpdateType": "Mutable"
},
"DomainName": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-domainname",
"PrimitiveType": "String",
"Required": false,
"UpdateType": "Immutable"
},
"EBSOptions": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-ebsoptions",
"Required": false,
"Type": "EBSOptions",
"UpdateType": "Mutable"
},
"ElasticsearchClusterConfig": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-elasticsearchclusterconfig",
"Required": false,
"Type": "ElasticsearchClusterConfig",
"UpdateType": "Mutable"
},
"ElasticsearchVersion": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-elasticsearchversion",
"PrimitiveType": "String",
"Required": false,
"UpdateType": "Immutable"
},
"SnapshotOptions": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-snapshotoptions",
"Required": false,
"Type": "SnapshotOptions",
"UpdateType": "Mutable"
},
"Tags": {
"Documentation": "http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticsearch-domain.html#cfn-elasticsearch-domain-tags",
"DuplicatesAllowed": true,
"ItemType": "Tag",
"Required": false,
"Type": "List",
"UpdateType": "Mutable"
}
}
}
},
"ResourceSpecificationVersion": "1.4.1"
}
```