本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# CloudFormation 勾點堆疊層級篩選條件
<a name="hooks-stack-level-filtering"></a>

您可以將堆疊層級篩選條件新增至 CloudFormation Hooks，以根據堆疊名稱和角色將特定堆疊設為目標。當您有多個具有相同資源類型的堆疊，但勾點適用於特定堆疊時，這非常有用。

本節說明這些篩選條件的運作方式，並提供您可以遵循的範例。

沒有堆疊層級篩選的勾點組態基本結構如下所示：

```
{
  "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) 操作為目標的勾點，則會忽略所有堆疊層級篩選條件。

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

`FilteringCriteria` 是指定篩選行為的必要參數。它可以設定為 `ALL`或 `ANY`。
+ `ALL` 如果所有篩選條件都相符， 會叫用勾點。
+ `ANY` 如果有任何相符的篩選條件， 會叫用勾點。

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

若要在勾點組態中將一或多個堆疊名稱指定為篩選條件，請使用下列 JSON 結構：

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

您必須指定下列其中一項：
+ `Include`：要包含的堆疊名稱清單。只有此清單中指定的堆疊才會叫用勾點。
  + 類型：字串陣列
  + 項目上限：50
  + 最小項目：1
+ `Exclude`：要排除的堆疊名稱清單。除了此處列出的堆疊之外，所有堆疊都會叫用勾點。
  + 類型：字串陣列
  + 項目上限：50
  + 最小項目：1

`Include` 和 `Exclude`陣列中的每個堆疊名稱必須遵循下列模式和長度要求：
+ 模式：`^[a-zA-Z][-a-zA-Z0-9]*$`
+ 長度上限：128 

`StackNames` 支援具體堆疊名稱和完整萬用字元比對。若要查看使用萬用字元的範例，請參閱 [使用萬用字元搭配勾點目標名稱](wildcard-hook-targets.md)。

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

若要在勾點組態中將一或多個 [IAM 角色](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-servicerole.html)指定為篩選條件，請使用下列 JSON 結構：

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

您必須指定下列其中一項：
+ `Include`：與這些角色相關聯的目標堆疊的 IAM 角色 ARNs 清單。只有這些角色啟動的堆疊操作才會叫用勾點。
  + 類型：字串陣列
  + 項目上限：50
  + 最小項目：1
+ `Exclude`：您要排除之堆疊的 IAM 角色 ARNs 清單。所有堆疊都會叫用勾點，但由指定角色啟動的堆疊除外。
  + 類型：字串陣列
  + 項目上限：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 語法區段中查看使用萬用字元的範例，請參閱 [使用萬用字元搭配勾點目標名稱](wildcard-hook-targets.md)。

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

每個篩選條件 (`StackNames` 和 `StackRoles`) 都有`Include`清單和`Exclude`清單。使用 `StackNames` 作為範例，勾點只會在`Include`清單中指定的堆疊上調用。如果只在`Exclude`清單中指定堆疊名稱，則只會在*不在*`Exclude`清單中的堆疊上叫用掛鉤。如果同時指定 `Exclude` `Include`和 ，Hook 會以`Include`清單中的內容為目標，而不是`Exclude`清單中的內容為目標。

例如，假設您有四個堆疊：A、B、C 和 D。
+ `"Include": ["A","B"]` 在 A 和 B 上調用勾點。
+ `"Exclude": ["B"]` 在 A、C 和 D 上調用勾點。
+ `"Include": ["A","B","C"], "Exclude": ["A","D"]` 在 B 和 C 上調用勾點。
+ `"Include": ["A","B","C"], "Exclude": ["A”,"B","C"]` 任何堆疊上都不會叫用勾點。

## 堆疊層級篩選條件的範例
<a name="stack-level-filtering-examples"></a>

本節提供您可以遵循的範例，為 CloudFormation 勾點建立堆疊層級篩選條件。

### 範例 1：包含特定堆疊
<a name="stack-level-filtering-example-1"></a>

下列範例會指定`Include`清單。僅在名為 `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`清單，則會在*未*命名為 `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`的 堆疊上叫用勾點。在下列範例中，僅在 上叫用勾點`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>

下列勾點包含三個堆疊名稱和一個堆疊角色。由於 `FilteringCriteria` 指定為 `ALL`，因此只會針對*同時*具有相符堆疊名稱*和*相符堆疊角色的堆疊叫用勾點。

```
{
  "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>

下列勾點包含三個堆疊名稱和一個堆疊角色。因為 `FilteringCriteria`指定為 `ANY`，所以針對具有**相符堆疊名稱*或*相符堆疊角色的堆疊叫用勾點。

```
{
  "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"]
        }
      }
    }
  }
}
```