本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# H CloudFormation ooks 的架构语法参考
本节介绍用于开发 CloudFormation Hook 的架构的语法。
Hook 包括由 JSON 架构和 Hook 处理程序表示的 Hook 规范。创建自定义 Hook 的第一步是对定义挂钩及其属性的架构进行建模。使用 CloudFormation CLI [https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-init.html](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-init.html)命令初始化自定义 Hook 项目时，将为您创建一个 Hook 架构文件。使用此架构文件作为定义自定义 Hook 的形状和语义的起点。
## 架构语法
以下架构是 Hook 的结构。
```
{
"typeName": "string",
"description": "string",
"sourceUrl": "string",
"documentationUrl": "string",
"definitions": {
"definitionName": {
. . .
}
},
"typeConfiguration": {
"properties": {
"propertyName": {
"description": "string",
"type": "string",
. . .
},
},
"required": [
"propertyName"
. . .
],
"additionalProperties": false
},
"handlers": {
"preCreate": {
"targetNames": [
],
"permissions": [
]
},
"preUpdate": {
"targetNames": [
],
"permissions": [
]
},
"preDelete": {
"targetNames": [
],
"permissions": [
]
}
},
"additionalProperties": false
}
```
`typeName`
您的 Hook 的唯一名称。为 Hook 指定由三部分组成的命名空间，推荐的`Organization::Service::Hook`模式为。
以下组织命名空间已预留，不能用于您的 Hook 类型名称：
+ `Alexa`
+ `AMZN`
+ `Amazon`
+ `ASK`
+ `AWS`
+ `Custom`
+ `Dev`
*是否必需*：是
*图案*：`^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$`
*最小值*：`10`
*最大值*：`196`
`description`
CloudFormation 控制台中显示的 Hook 的简短描述。
*是否必需*：是
`sourceUrl`
Hook 源代码的网址（如果是公开的）。
*必需*：否
*最大值*：`4096`
`documentationUrl`
提供 Hook 详细文档的页面的 URL。
*是否必需*：是
*图案*：`^https\:\/\/[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])(\:[0-9]*)*([\?/#].*)?$`
*最大值*：`4096`
尽管 Hook 架构应包含完整而准确的属性描述，但您可以使用该`documentationURL`属性为用户提供更多详细信息，包括示例、用例和其他详细信息。
`definitions`
使用该`definitions`块提供共享的 Hook 属性架构。
使用该`definitions`部分来定义可在您的 Hook 类型架构中的多个位置使用的架构元素被认为是一种最佳实践。然后，您可以使用 JSON 指针在 Hook 类型架构中的相应位置引用该元素。
*必需*：否
`typeConfiguration`
Hook 配置数据的定义。
*是否必需*：是
`properties`
挂钩的属性。Hook 的所有属性都必须在架构中表达。将 Hook 架构属性与挂钩类型配置属性对齐。
不允许使用嵌套属性。相反，在`definitions`元素中定义任何嵌套属性，然后使用`$ref`指针在所需的属性中引用它们。
目前支持以下属性：
+ `default`-属性的默认值。
+ `description`-对属性的描述。
+ `pattern`— 用于验证输入的正则表达式模式。
+ `type`— 可接受的属性类型。
`additionalProperties`
`additionalProperties` 必须设置为 `false`。Hook 的所有属性都必须在架构中表达：不允许任意输入。
*是否必需*：是
*有效值*：`false`
`handlers`
处理程序指定可以启动架构中定义的 Hook 的操作，例如 Hook 调用点。例如，`preUpdate`处理程序是在处理程序中所有指定目标的更新操作之前调用的。
*有效值*：`preCreate` \$1 `preUpdate` \$1 `preDelete`
必须为处理程序指定至少一个值。
导致状态为的堆栈操作`UpdateCleanup`不会调用 Hook。例如，在以下两个场景中，不会调用 Hook 的`preDelete`处理程序：
+ 从模板中移除一个资源后，堆栈即会更新。
+ 更新类型为[替换](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)的资源被删除。
`targetNames`
Hook 瞄准的类型名称的字符串数组。例如，如果`preCreate`处理程序有`AWS::S3::Bucket`目标，则挂钩将在预配置阶段为 Amazon S3 存储桶运行。
+ `TargetName`
为每个已实现的处理程序指定至少一个目标名称。
*图案*：`^[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}::[a-zA-Z0-9]{2,64}$`
*最小值*：`1`
*是否必需*：是
**警告**
SSM SecureString 和 Secrets Manager 动态引用在传递给 Hooks 之前无法解析。
`permissions`
一个字符串数组，它指定调用处理程序所需的 AWS 权限。
*是否必需*：是
`additionalProperties`
`additionalProperties` 必须设置为 `false`。Hook 的所有属性都必须在架构中表达：不允许任意输入。
*是否必需*：是
*有效值*：`false`
## Hooks 架构示例
**示例 1**
Java 和 Python 演练使用以下代码示例。以下是名为的 Hook 的示例结构`mycompany-testing-mytesthook.json`。
```
{
"typeName":"MyCompany::Testing::MyTestHook",
"description":"Verifies S3 bucket and SQS queues properties before create and update",
"sourceUrl":"https://mycorp.com/my-repo.git",
"documentationUrl":"https://mycorp.com/documentation",
"typeConfiguration":{
"properties":{
"minBuckets":{
"description":"Minimum number of compliant buckets",
"type":"string"
},
"minQueues":{
"description":"Minimum number of compliant queues",
"type":"string"
},
"encryptionAlgorithm":{
"description":"Encryption algorithm for SSE",
"default":"AES256",
"type":"string",
"pattern": "[a-zA-Z]*[1-9]"
}
},
"required":[
],
"additionalProperties":false
},
"handlers":{
"preCreate":{
"targetNames":[
"AWS::S3::Bucket",
"AWS::SQS::Queue"
],
"permissions":[
]
},
"preUpdate":{
"targetNames":[
"AWS::S3::Bucket",
"AWS::SQS::Queue"
],
"permissions":[
]
},
"preDelete":{
"targetNames":[
"AWS::S3::Bucket",
"AWS::SQS::Queue"
],
"permissions":[
"s3:ListBucket",
"s3:ListAllMyBuckets",
"s3:GetEncryptionConfiguration",
"sqs:ListQueues",
"sqs:GetQueueAttributes",
"sqs:GetQueueUrl"
]
}
},
"additionalProperties":false
}
```
**示例 2**
以下示例是一个使用`STACK`和 `CHANGE_SET` for `targetNames` 来定位堆栈模板和更改集操作的架构。
```
{
"typeName":"MyCompany::Testing::MyTestHook",
"description":"Verifies Stack and Change Set properties before create and update",
"sourceUrl":"https://mycorp.com/my-repo.git",
"documentationUrl":"https://mycorp.com/documentation",
"typeConfiguration":{
"properties":{
"minBuckets":{
"description":"Minimum number of compliant buckets",
"type":"string"
},
"minQueues":{
"description":"Minimum number of compliant queues",
"type":"string"
},
"encryptionAlgorithm":{
"description":"Encryption algorithm for SSE",
"default":"AES256",
"type":"string",
"pattern": "[a-zA-Z]*[1-9]"
}
},
"required":[
],
"additionalProperties":false
},
"handlers":{
"preCreate":{
"targetNames":[
"STACK",
"CHANGE_SET"
],
"permissions":[
]
},
"preUpdate":{
"targetNames":[
"STACK"
],
"permissions":[
]
},
"preDelete":{
"targetNames":[
"STACK"
],
"permissions":[
]
}
},
"additionalProperties":false
}
```