終止支援通知：將於 2026 年 10 月 7 日 AWS 結束對 的支援 AWS Proton。2026 年 10 月 7 日之後，您將無法再存取 AWS Proton 主控台或 AWS Proton 資源。您部署的基礎設施將保持不變。如需詳細資訊，請參閱[AWS Proton 服務棄用和遷移指南](https://docs.aws.amazon.com/proton/latest/userguide/proton-end-of-support.html)。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 結構描述檔案
身為管理員，當您使用 Open API [Data Models （結構描述） 區段](https://swagger.io/docs/specification/data-models/)來定義範本套件的參數結構描述 YAML 檔案時， AWS Proton 可以根據您在結構描述中定義的需求驗證參數值輸入。
如需格式和可用關鍵字的詳細資訊，請參閱 OpenAPI 的[結構描述物件](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#schemaObject)區段。
## 環境範本套件的結構描述需求
您的結構描述必須遵循 YAML 格式 OpenAPI [的資料模型 （結構描述） 區段](https://swagger.io/docs/specification/data-models/)。它也必須是環境範本套件的一部分。
對於您的環境結構描述，您必須包含格式化標頭，以確定您使用的是 Open API 的資料模型 （結構描述） 區段。在下列環境結構描述範例中，這些標頭會出現在前三行中。
`environment_input_type` 必須包含並定義您提供的名稱。在下列範例中，這在第 5 行定義。透過定義此參數，您可以將其與 AWS Proton 環境資源建立關聯。
若要遵循 Open API 結構描述模型，您必須包含 `types`。在下列範例中，這是第 6 行。
在 之後`types`，您必須定義 `environment_input_type`類型。您可以將環境的輸入參數定義為 的屬性`environment_input_type`。您必須包含至少一個名稱與環境基礎設施中列出的至少一個參數相符的屬性，做為與結構描述相關聯的程式碼 (IaC) 檔案。
當您建立環境並提供自訂參數值時， AWS Proton 會使用結構描述檔案來比對、驗證和插入至相關聯 CloudFormation IaC 檔案中的大括號參數。針對每個屬性 （參數），提供 `name`和 `type`。或者，您也可以提供 `description`、 `default`和 `pattern`。
下列範例*標準*環境範本結構描述的定義參數包括 `vpc_cidr`、 和 `subnet_one_cidr`，`subnet_two_cidr`以及`default`關鍵字和預設值。當您使用此環境範本套件結構描述建立環境時，您可以接受預設值或提供自己的值。如果參數*沒有*預設值並列為`required`屬性 （參數），您必須在建立環境時為其提供值。
第二個範例*標準*環境範本結構描述會列出 `required` 參數 `my_other_sample_input`。
您可以為兩種類型的環境範本建立結構描述。如需詳細資訊，請參閱[註冊和發佈範本](template-create.md)。
+ ***標準*環境範本**
在下列範例中，使用描述和輸入屬性定義環境輸入類型。此結構描述範例可與[範例 3 ](ag-infrastructure-tmp-files-cloudformation.md#ag-proton-env-cfn-example)中顯示的 AWS Proton CloudFormation IaC 檔案搭配使用。
*標準*環境範本的範例結構描述：
```
schema: # required
format: # required
openapi: "3.0.0" # required
# required defined by administrator
environment_input_type: "PublicEnvironmentInput"
types: # required
# defined by administrator
PublicEnvironmentInput:
type: object
description: "Input properties for my environment"
properties:
vpc_cidr: # parameter
type: string
description: "This CIDR range for your VPC"
default: 10.0.0.0/16
pattern: ([0-9]{1,3}\.){3}[0-9]{1,3}($|/(16|24))
subnet_one_cidr: # parameter
type: string
description: "The CIDR range for subnet one"
default: 10.0.0.0/24
pattern: ([0-9]{1,3}\.){3}[0-9]{1,3}($|/(16|24))
subnet_two_cidr: # parameter
type: string
description: "The CIDR range for subnet one"
default: 10.0.1.0/24
pattern: ([0-9]{1,3}\.){3}[0-9]{1,3}($|/(16|24))
```
包含 `required` 參數*的標準*環境範本範例結構描述：
```
schema: # required
format: # required
openapi: "3.0.0" # required
# required defined by administrator
environment_input_type: "MyEnvironmentInputType"
types: # required
# defined by administrator
MyEnvironmentInputType:
type: object
description: "Input properties for my environment"
properties:
my_sample_input: # parameter
type: string
description: "This is a sample input"
default: "hello world"
my_other_sample_input: # parameter
type: string
description: "Another sample input"
another_optional_input: # parameter
type: string
description: "Another optional input"
default: "!"
required:
- my_other_sample_input
```
+ ***客戶受*管環境範本**
在下列範例中，結構描述只會包含輸出清單，這些輸出會複寫您用來佈建*客戶受*管基礎設施的 IaC 輸出。您只需要將*輸出值類型定義為字串 *(*而非*清單、陣列或其他類型）。例如，下一個程式碼片段會顯示外部 CloudFormation 範本的輸出區段。這是來自[範例 1 ](ag-infrastructure-tmp-files-cloudformation.md#ag-env-cfn-example)中顯示的範本。它可用於為從[範例 4](ag-infrastructure-tmp-files-cloudformation.md#ag-proton-svc-cfn-example) 建立的 AWS Proton Fargate 服務建立外部*客戶受*管基礎設施。
**重要**
身為管理員，您必須確保佈建和管理的基礎設施和所有輸出參數都與相關聯的*客戶受*管環境範本相容。 AWS Proton 無法代表您考慮變更，因為這些變更不可見 AWS Proton。不一致會導致失敗。
*客戶受*管環境範本的範例 CloudFormation IaC 檔案輸出：
```
// Cloudformation Template Outputs
[...]
Outputs:
ClusterName:
Description: The name of the ECS cluster
Value: !Ref 'ECSCluster'
ECSTaskExecutionRole:
Description: The ARN of the ECS role
Value: !GetAtt 'ECSTaskExecutionRole.Arn'
VpcId:
Description: The ID of the VPC that this stack is deployed in
Value: !Ref 'VPC'
[...]
```
對應 AWS Proton *客戶受*管環境範本套件的結構描述如下列範例所示。每個輸出值都定義為字串。
*客戶受*管環境範本的範例結構描述：
```
schema: # required
format: # required
openapi: "3.0.0" # required
# required defined by administrator
environment_input_type: "EnvironmentOutput"
types: # required
# defined by administrator
EnvironmentOutput:
type: object
description: "Outputs of the environment"
properties:
ClusterName: # parameter
type: string
description: "The name of the ECS cluster"
ECSTaskExecutionRole: # parameter
type: string
description: "The ARN of the ECS role"
VpcId: # parameter
type: string
description: "The ID of the VPC that this stack is deployed in"
[...]
```
## 服務範本套件的結構描述需求
您的結構描述必須遵循 YAML 格式 OpenAPI [的資料模型 （結構描述） 區段](https://swagger.io/docs/specification/data-models/)，如下列範例所示。您必須在服務範本套件中提供結構描述檔案。
在下列服務結構描述範例中，您必須包含格式化的標頭。在下列範例中，這位於前三行。這是為了確認您使用的是 Open API 的資料模型 （結構描述） 區段。
`service_input_type` 必須包含並定義您提供的名稱。在下列範例中，這是第 5 行。這會將參數與服務 AWS Proton 資源建立關聯。
當您使用主控台或 CLI 建立 AWS Proton 服務時，預設會包含服務管道。當您包含服務的服務管道時，您必須`pipeline_input_type`包含您提供的名稱。在下列範例中，這是第 7 行。如果您*未*包含 AWS Proton 服務管道，*請勿*包含此參數。如需詳細資訊，請參閱[註冊和發佈範本](template-create.md)。
若要遵循 Open API 結構描述模型，您必須包含`types`下列範例中的第 9 行。
在 之後`types`，您必須定義`service_input_type`類型。您可以將服務的輸入參數定義為 的屬性`service_input_type`。您必須包含至少一個屬性，其名稱至少符合服務基礎設施中列出的至少一個參數做為與結構描述相關聯的程式碼 (IaC) 檔案。
若要定義服務管道，請在`service_input_type`定義下方定義 `pipeline_input_type`。如上所述，您必須包含至少一個屬性，其名稱至少符合與結構描述相關聯的管道 IaC 檔案中列出的至少一個參數。如果您*未*包含 AWS Proton 服務管道，*請勿*包含此定義。
身為管理員或開發人員，當您建立服務並提供自訂參數值時， AWS Proton 會使用結構描述檔案來比對、驗證和插入相關聯的 CloudFormation IaC 檔案的大括號參數。針對每個屬性 （參數），提供 `name`和 `type`。或者，您也可以提供 `description`、 `default`和 `pattern`。
範例結構描述的定義參數包括 `port`、 `task_size`和 `desired_count`，`image`以及`default`關鍵字和預設值。當您使用此服務範本套件結構描述建立服務時，您可以接受預設值或提供自己的值。參數`unique_name`也包含在範例中，*而且沒有*預設值。它被列為`required`屬性 （參數）。身為管理員或開發人員，您必須在建立服務時提供`required`參數的值。
如果您想要使用服務管道建立服務範本，請在結構描述`pipeline_input_type`中包含 。
**包含 服務 AWS Proton 管道之服務的服務結構描述檔案範例。**
此結構描述範例可與[範例 4 ](ag-infrastructure-tmp-files-cloudformation.md#ag-proton-svc-cfn-example)和[範例 5 ](ag-infrastructure-tmp-files-cloudformation.md#ag-proton-pipeline-cfn-example)中顯示的 AWS Proton IaC 檔案搭配使用。包含服務管道。
```
schema: # required
format: # required
openapi: "3.0.0" # required
# required defined by administrator
service_input_type: "LoadBalancedServiceInput"
# only include if including AWS Proton service pipeline, defined by administrator
pipeline_input_type: "PipelineInputs"
types: # required
# defined by administrator
LoadBalancedServiceInput:
type: object
description: "Input properties for a loadbalanced Fargate service"
properties:
port: # parameter
type: number
description: "The port to route traffic to"
default: 80
minimum: 0
maximum: 65535
desired_count: # parameter
type: number
description: "The default number of Fargate tasks you want running"
default: 1
minimum: 1
task_size: # parameter
type: string
description: "The size of the task you want to run"
enum: ["x-small", "small", "medium", "large", "x-large"]
default: "x-small"
image: # parameter
type: string
description: "The name/url of the container image"
default: "public.ecr.aws/z9d2n7e1/nginx:1.19.5"
minLength: 1
maxLength: 200
unique_name: # parameter
type: string
description: "The unique name of your service identifier. This will be used to name your log group, task definition and ECS service"
minLength: 1
maxLength: 100
required:
- unique_name
# defined by administrator
PipelineInputs:
type: object
description: "Pipeline input properties"
properties:
dockerfile: # parameter
type: string
description: "The location of the Dockerfile to build"
default: "Dockerfile"
minLength: 1
maxLength: 100
unit_test_command: # parameter
type: string
description: "The command to run to unit test the application code"
default: "echo 'add your unit test command here'"
minLength: 1
maxLength: 200
```
如果您想要在沒有服務管道的情況下建立服務範本，*請不要*在結構描述`pipeline_input_type`中包含 ，如下列範例所示。
***不包含*服務 AWS Proton 管道之服務的服務結構描述檔案範例**
```
schema: # required
format: # required
openapi: "3.0.0" # required
# required defined by administrator
service_input_type: "MyServiceInstanceInputType"
types: # required
# defined by administrator
MyServiceInstanceInputType:
type: object
description: "Service instance input properties"
required:
- my_sample_service_instance_required_input
properties:
my_sample_service_instance_optional_input: # parameter
type: string
description: "This is a sample input"
default: "hello world"
my_sample_service_instance_required_input: # parameter
type: string
description: "Another sample input"
```