本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# CloudFormation Hooks 堆栈级别过滤器
<a name="hooks-stack-level-filtering"></a>

你可以在 CloudFormation Hook 中添加堆栈级别过滤器，根据堆栈名称和角色定位特定的堆栈。如果您有多个资源类型相同的堆栈，但是 Hook 适用于特定的堆栈，则此功能很有用。

本节说明了这些过滤器的工作原理，并提供了您可以遵循的示例。

没有堆栈级别筛选的 Hook 配置的基本结构如下所示：

```
{
  "CloudFormationConfiguration": {
    "HookConfiguration": {
      "HookInvocationStatus": "ENABLED",
      "TargetOperations": [
        "STACK",
        "RESOURCE"
      ],
      "FailureMode": "WARN",
      "Properties": {},
      "TargetFilters": {
        "Actions": [
          "CREATE",
          "UPDATE",
          "DELETE"
        ]
      }
    }
  }
}
```

有关`HookConfiguration`语法的更多信息，请参阅[挂钩配置架构语法参考](hook-configuration-schema.md)。

要使用堆栈级别筛选器，请在下方添加一个`StackFilters`密钥`HookConfiguration`。

该`StackFilters`密钥有一个必填成员和两个可选成员。
+ `FilteringCriteria`（必需）
+ `StackNames`（可选）
+ `StackRoles`（可选）

`StackNames`或`StackRoles`属性是可选的。但是，您必须指定其中至少一个属性。

如果您创建了以 [Cloud Control API](https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/what-is-cloudcontrolapi.html) 操作为目标的 Hook，则所有堆栈级别的过滤器都将被忽略。

## `FilteringCriteria`
<a name="stack-level-filtering-components-filteringcriteria"></a>

`FilteringCriteria`是指定筛选行为的必填参数。可以将其设置为`ALL`或`ANY`。
+ `ALL`如果所有过滤器都匹配，则调用 Hook。
+ `ANY`如果匹配任何一个过滤器，则调用 Hook。

## `StackNames`
<a name="stack-level-filtering-components-stacknames"></a>

要在 Hooks 配置中将一个或多个堆栈名称指定为过滤器，请使用以下 JSON 结构：

```
"StackNames": {
  "Include": [
    "string"
  ],
  "Exclude": [
    "string"
  ]
}
```

您必须指定以下各项之一：
+ `Include`：要包含的堆栈名称列表。只有此列表中指定的堆栈才会调用 Hook。
  + 类型：字符串数组
  + 最大物品数量:50
  + 最少物品:1
+ `Exclude`：要排除的堆栈名称列表。除此处列出的堆栈外，所有堆栈都将调用 Hook。
  + 类型：字符串数组
  + 最大物品数量:50
  + 最少物品:1

`Include`和`Exclude`数组中的每个堆栈名称都必须符合以下模式和长度要求：
+ 模式：`^[a-zA-Z][-a-zA-Z0-9]*$`
+ 最大长度：128 

`StackNames`支持具体的堆栈名称和完整的通配符匹配。要查看使用通配符的示例，请参阅[使用带有 Hook 目标名称的通配符](wildcard-hook-targets.md)。

## `StackRoles`
<a name="stack-level-filtering-components-StackRoles"></a>

要在 Hook 配置中将一个或多个 [IAM 角色](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-servicerole.html)指定为筛选条件，请使用以下 JSON 结构：

```
"StackRoles": {
  "Include": [
    "string"
  ],
  "Exclude": [
    "string"
  ]
}
```

您必须指定以下各项之一：
+ `Include`: ARNs 用于定位与这些角色关联的堆栈的 IAM 角色列表。只有由这些角色启动的堆栈操作才会调用 Hook。
  + 类型：字符串数组
  + 最大物品数量:50
  + 最少物品:1
+ `Exclude`: 您要排除的堆栈 ARNs 的 IAM 角色列表。Hook 将在除指定角色启动的堆栈之外的所有堆栈上调用。
  + 类型：字符串数组
  + 最大物品数量:50
  + 最少物品:1

`Include`和`Exclude`数组中的每个堆栈角色都必须遵守以下模式和长度要求：
+ 模式：`arn:.+:iam::[0-9]{12}:role/.+`
+ 最大长度：256

`StackRoles`允许在以下 [ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html#arns-syntax) 语法部分使用通配符：
+ `partition`
+ `account-id`
+ `resource-id`

要查看 ARN 语法部分中使用通配符的示例，请参阅。[使用带有 Hook 目标名称的通配符](wildcard-hook-targets.md)

## `Include` 和 `Exclude`
<a name="stack-level-filtering-components-include-and-exclude"></a>

每个筛选器（`StackNames`和`StackRoles`）都有一个`Include`列表和`Exclude`列表。`StackNames`举个例子，Hook 只能在`Include`列表中指定的堆栈上调用。如果仅在`Exclude`列表中指定堆栈名称，则仅在*不*在`Exclude`列表中的堆栈上调用该挂钩。如果同时指定了`Include`和`Exclude`，则 Hook 会瞄准`Include`列表中的内容，而不是`Exclude`列表中的内容。

例如，假设你有四个堆栈：A、B、C 和 D。
+ `"Include": ["A","B"]`在 A 和 B 上调用 Hook
+ `"Exclude": ["B"]`在 A、C 和 D 上调用 Hook
+ `"Include": ["A","B","C"], "Exclude": ["A","D"]`在 B 和 C 上调用 Hook
+ `"Include": ["A","B","C"], "Exclude": ["A”,"B","C"]`不会在任何堆栈上调用 Hook。

## 堆栈级过滤器示例
<a name="stack-level-filtering-examples"></a>

本节提供了一些示例，您可以按照这些示例为 CloudFormation Hook 创建堆栈级过滤器。

### 示例 1：包括特定的堆栈
<a name="stack-level-filtering-example-1"></a>

以下示例指定了一个`Include`列表。Hook 只能在名为`stack-test-1`、`stack-test-2`和`stack-test-3`的堆栈上调用。

```
{
  "CloudFormationConfiguration": {
    "HookConfiguration": {
      "HookInvocationStatus": "ENABLED",
      "TargetOperations": [
        "STACK",
        "RESOURCE"
      ],
      "FailureMode": "WARN",
      "Properties": {},
      "StackFilters": {
        "FilteringCriteria": "ALL",
        "StackNames": {
          "Include": [
            "stack-test-1",
            "stack-test-2",
            "stack-test-3"
          ]
        }
      }
    }
  }
}
```

### 示例 2：排除特定堆栈
<a name="stack-level-filtering-example-2"></a>

如果改为将堆栈名称添加到`Exclude`列表中，则会在任何*未*命名的堆栈上调用 Hook`stack-test-1`，`stack-test-2`或`stack-test-3`。

```
{
  "CloudFormationConfiguration": {
    "HookConfiguration": {
      "HookInvocationStatus": "ENABLED",
      "TargetOperations": [
        "STACK",
        "RESOURCE"
      ],
      "FailureMode": "WARN",
      "Properties": {},
      "StackFilters": {
        "FilteringCriteria": "ALL",
        "StackNames": {
          "Exclude": [
            "stack-test-1",
            "stack-test-2",
            "stack-test-3"
          ]
        }
      }
    }
  }
}
```

### 示例 3：合并包含和排除
<a name="stack-level-filtering-example-3"></a>

如果未指定`Include`和`Exclude`列表，则仅在`Exclude`列表中未`Include`包含的堆栈上调用 Hook。在以下示例中，Hook 仅在上调用`stack-test-3`。

```
{
  "CloudFormationConfiguration": {
    "HookConfiguration": {
      "HookInvocationStatus": "ENABLED",
      "TargetOperations": [
        "STACK",
        "RESOURCE"
      ],
      "FailureMode": "WARN",
      "Properties": {},
      "StackFilters": {
        "FilteringCriteria": "ALL",
        "StackNames": {
          "Include": [
            "stack-test-1",
            "stack-test-2",
            "stack-test-3"
          ],
          "Exclude": [
            "stack-test-1",
            "stack-test-2"
          ]
        }
      }
    }
  }
}
```

### 示例 4：将堆栈名称和角色与`ALL`标准相结合
<a name="stack-level-filtering-example-4"></a>

以下 Hook 包括三个堆栈名称和一个堆栈角色。由于指定`FilteringCriteria`为`ALL`，因此只有*同时*具有匹配堆栈名称*和*匹配堆栈角色的堆栈才会调用 Hook。

```
{
  "CloudFormationConfiguration": {
    "HookConfiguration": {
      "HookInvocationStatus": "ENABLED",
      "TargetOperations": [
        "STACK",
        "RESOURCE"
      ],
      "FailureMode": "WARN",
      "Properties": {},
      "StackFilters": {
        "FilteringCriteria": "ALL",
        "StackNames": {
          "Include": [
            "stack-test-1",
            "stack-test-2",
            "stack-test-3"
          ]
        },
        "StackRoles": {
          "Include": ["arn:aws:iam::123456789012:role/hook-role"]
        }
      }
    }
  }
}
```

### 示例 5：将堆栈名称和角色与`ANY`标准相结合
<a name="stack-level-filtering-example-5"></a>

以下 Hook 包括三个堆栈名称和一个堆栈角色。*由于指定`FilteringCriteria`为`ANY`，因此会为具有匹配堆栈名称*或*匹配堆栈角色的堆栈调用 Hook。*

```
{
  "CloudFormationConfiguration": {
    "HookConfiguration": {
      "HookInvocationStatus": "ENABLED",
      "TargetOperations": [
        "STACK",
        "RESOURCE"
      ],
      "FailureMode": "WARN",
      "Properties": {},
      "StackFilters": {
        "FilteringCriteria": "ANY",
        "StackNames": {
          "Include": [
            "stack-test-1",
            "stack-test-2",
            "stack-test-3"
          ]
        },
        "StackRoles": {
            "Include": ["arn:aws:iam::123456789012:role/hook-role"]
        }
      }
    }
  }
}
```