终止支持通知：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
```
**说明**
该筛选条件为 Amazon Elastic Container Service (Amazon ECS) 任务定义 `ContainerDefinition` 部分的 [Environment 属性](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
```
**说明**
此过滤器格式化了要在 AWS Lambda 函数定义`Properties`部分的 En [vironment 属性](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 策略 ARNs 以包含在 IAM 角色中
**声明**
```
dict → proton_cfn_iam_policy_arns → YAML list
```
**说明**
此筛选器格式化了要在 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/` ARNs 从输出参数列表中提取有效的 IAM 策略。您可以使用该筛选条件，将输出参数值中的策略附加到服务模板中的 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
```
**说明**
这是一个通用的筛选条件。可以使用该筛选条件验证参数值的安全性。该筛选条件验证值是否与正则表达式 `^[a-zA-Z0-9_-]*$` 匹配或者是有效的 Amazon 资源名称 (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}}
```
## 为不存在的引用提供默认值
**描述**
在命名空间引用不存在时，`default` 筛选条件提供默认值。可以使用它编写强大的模板，即使您引用的参数丢失，也可以成功进行渲染。
### 示例
如果服务实例没有附加直接定义的（默认）组件，或者附加的组件没有名为 `test` 的输出，服务模板中的以下引用将导致模板渲染失败。
```
# ...
{{ service_instance.components.default.outputs.test }}
```
要避免该问题，请添加 `default` 筛选条件。
```
# ...
{{ service_instance.components.default.outputs.test | default("{{[optional-value]}}") }}
```