終止支援通知：將於 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)。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# CloudFormation IaC 檔案的參數篩選條件
當您參考 AWS CloudFormation IaC 檔案中的[AWS Proton 參數](parameters.md)時，您可以使用稱為*篩選條件*的 Jinja 修飾詞，在參數值插入轉譯範本之前對其進行驗證、篩選和格式化。參考[元件](ag-components.md)輸出參數時，篩選條件驗證特別有用，因為元件建立和連接是由開發人員完成，而且在服務執行個體範本中使用元件輸出的管理員可能想要驗證其存在和有效性。不過，您可以在任何 Jinja IaC 檔案中使用篩選條件。
下列各節說明和定義可用的參數篩選條件，並提供範例。 AWS Proton 定義這些篩選條件的大部分。`default` 篩選條件是 Jinja 內建篩選條件。
## 為 Amazon ECS 任務格式化環境屬性
**宣告**
```
dict → proton_cfn_ecs_task_definition_formatted_env_vars (raw: boolean = True) → YAML list of dicts
```
**Description**
此篩選條件會在 Amazon Elastic Container Service (Amazon ECS) 任務定義的 `ContainerDefinition`區段中，格式化要在[環境屬性](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-taskdefinition-containerdefinitions.html#cfn-ecs-taskdefinition-containerdefinition-environment)中使用的輸出清單。
`raw` 設定為 `False`以驗證參數值。在此情況下，需要 值才能符合規則表達式 `^[a-zA-Z0-9_-]*$`。如果值未通過此驗證，範本轉譯會失敗。
### 範例
使用下列自訂元件範本：
```
Resources:
# ...
Outputs:
Output1:
Description: "Example component output 1"
Value: hello
Output2:
Description: "Example component output 2"
Value: world
```
以及下列服務範本：
```
Resources:
TaskDefinition:
Type: AWS::ECS::TaskDefinition
Properties:
# ...
ContainerDefinitions:
- Name: MyServiceName
# ...
Environment:
{{ service_instance.components.default.outputs
| proton_cfn_ecs_task_definition_formatted_env_vars }}
```
轉譯的服務範本如下所示：
```
Resources:
TaskDefinition:
Type: AWS::ECS::TaskDefinition
Properties:
# ...
ContainerDefinitions:
- Name: MyServiceName
# ...
Environment:
- Name: Output1
Value: hello
- Name: Output2
Value: world
```
## 格式化 Lambda 函數的環境屬性
**宣告**
```
dict → proton_cfn_lambda_function_formatted_env_vars (raw: boolean = True) → YAML dict
```
**Description**
此篩選條件會格式化要在 AWS Lambda 函數定義的 `Properties`區段中的[環境屬性](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html#cfn-lambda-function-environment)中使用的輸出清單。
`raw` 設定為 `False`以驗證參數值。在此情況下，需要 值才能符合規則表達式 `^[a-zA-Z0-9_-]*$`。如果值未通過此驗證，範本轉譯會失敗。
### 範例
使用下列自訂元件範本：
```
Resources:
# ...
Outputs:
Output1:
Description: "Example component output 1"
Value: hello
Output2:
Description: "Example component output 2"
Value: world
```
以及下列服務範本：
```
Resources:
Lambda:
Type: AWS::Lambda::Function
Properties:
Environment:
Variables:
{{ service_instance.components.default.outputs
| proton_cfn_lambda_function_formatted_env_vars }}
```
轉譯的服務範本如下所示：
```
Resources:
Lambda:
Type: AWS::Lambda::Function
Properties:
Environment:
Variables:
Output1: hello
Output2: world
```
## 擷取要包含在 IAM 角色中的 IAM 政策 ARNs
**宣告**
```
dict → proton_cfn_iam_policy_arns → YAML list
```
**Description**
此篩選條件會格式化 AWS Identity and Access Management (IAM) 角色定義 `Properties` 區段中要在 [ManagedPolicyArns 屬性](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html#cfn-iam-role-managepolicyarns)中使用的輸出清單。篩選條件使用規則表達`^arn:[a-zA-Z-]+:iam::\d{12}:policy/`式，從輸出參數清單中擷取有效的 IAM 政策 ARNs。您可以使用此篩選條件，將輸出參數值中的政策附加至服務範本中的 IAM 角色定義。
### 範例
使用下列自訂元件範本：
```
Resources:
# ...
ExamplePolicy1:
Type: AWS::IAM::ManagedPolicy
Properties:
# ...
ExamplePolicy2:
Type: AWS::IAM::ManagedPolicy
Properties:
# ...
# ...
Outputs:
Output1:
Description: "Example component output 1"
Value: hello
Output2:
Description: "Example component output 2"
Value: world
PolicyArn1:
Description: "ARN of policy 1"
Value: !Ref ExamplePolicy1
PolicyArn2:
Description: "ARN of policy 2"
Value: !Ref ExamplePolicy2
```
以及下列服務範本：
```
Resources:
# ...
TaskRole:
Type: AWS::IAM::Role
Properties:
# ...
ManagedPolicyArns:
- !Ref BaseTaskRoleManagedPolicy
{{ service_instance.components.default.outputs
| proton_cfn_iam_policy_arns }}
# Basic permissions for the task
BaseTaskRoleManagedPolicy:
Type: AWS::IAM::ManagedPolicy
Properties:
# ...
```
轉譯的服務範本如下所示：
```
Resources:
# ...
TaskRole:
Type: AWS::IAM::Role
Properties:
# ...
ManagedPolicyArns:
- !Ref BaseTaskRoleManagedPolicy
- arn:aws:iam::123456789012:policy/{{cfn-generated-policy-name-1}}
- arn:aws:iam::123456789012:policy/{{cfn-generated-policy-name-2}}
# Basic permissions for the task
BaseTaskRoleManagedPolicy:
Type: AWS::IAM::ManagedPolicy
Properties:
# ...
```
## 清理屬性值
**宣告**
```
string → proton_cfn_sanitize → string
```
**Description**
這是一般用途篩選條件。使用它來驗證參數值的安全性。篩選條件會驗證該值是否符合規則表達式，`^[a-zA-Z0-9_-]*$`或是有效的 Amazon Resource Name (ARN)。如果值未通過此驗證，範本轉譯會失敗。
### 範例
使用下列自訂元件範本：
```
Resources:
# ...
Outputs:
Output1:
Description: "Example of valid output"
Value: "This-is_valid_37"
Output2:
Description: "Example incorrect output"
Value: "this::is::incorrect"
SomeArn:
Description: "Example ARN"
Value: arn:aws:{{some-service}}::123456789012:{{some-resource}}/{{resource-name}}
```
+ 服務範本中的下列參考：
```
# ...
{{ service_instance.components.default.outputs.Output1
| proton_cfn_sanitize }}
```
轉譯方式如下：
```
# ...
This-is_valid_37
```
+ 服務範本中的下列參考：
```
# ...
{{ service_instance.components.default.outputs.Output2
| proton_cfn_sanitize }}
```
具有下列轉譯錯誤的結果：
```
Illegal character(s) detected in "this::is::incorrect". Must match regex ^[a-zA-Z0-9_-]*$ or be a valid ARN
```
+ 服務範本中的下列參考：
```
# ...
{{ service_instance.components.default.outputs.SomeArn
| proton_cfn_sanitize }}
```
轉譯方式如下：
```
# ...
arn:aws:{{some-service}}::123456789012:{{some-resource}}/{{resource-name}}
```
## 提供不存在參考的預設值
**Description**
當命名空間參考不存在時，`default`篩選條件會提供預設值。使用它來撰寫強大的範本，即使在您參考的參數遺失時，也能在沒有失敗的情況下轉譯。
### 範例
如果服務執行個體沒有直接定義的 （預設） 元件，或者連接的元件沒有名為 的輸出，則服務範本中的下列參考會導致範本轉譯失敗`test`。
```
# ...
{{ service_instance.components.default.outputs.test }}
```
若要避免此問題，請新增`default`篩選條件。
```
# ...
{{ service_instance.components.default.outputs.test | default("{{[optional-value]}}") }}
```