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

# CloudFormation 勾點的結構描述語法參考
<a name="hooks-schema"></a>

本節說明您用來開發 CloudFormation Hooks 的結構描述語法。

勾點包含由 JSON 結構描述和勾點處理常式表示的勾點規格。建立自訂勾點的第一步是建立定義勾點、其屬性及其屬性的結構描述模型。當您使用 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 結構描述檔案。使用此結構描述檔案做為定義自訂勾點形狀和語意的起點。

## 結構描述語法
<a name="schema-syntax"></a>

下列結構描述是勾點的結構。

```
{
"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`  <a name="hooks-properties-typeName"></a>
勾點的唯一名稱。為您的勾點指定三個部分的命名空間，建議模式為 `Organization::Service::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`  <a name="hooks-properties-description"></a>
CloudFormation 主控台中顯示的勾點簡短描述。  
*必要*：是

`sourceUrl`  <a name="hooks-properties-sourceUrl"></a>
如果為公有，Hook 的來源碼 URL。  
*必要*：否  
*上限*：`4096`

`documentationUrl`  <a name="hooks-properties-documentationurl"></a>
為 勾點提供詳細文件的頁面 URL。  
*必要*：是  
*模式*：`^https\:\/\/[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])(\:[0-9]*)*([\?/#].*)?$`  
*上限*：`4096`  
雖然勾點結構描述應包含完整且準確的屬性描述，但您可以使用 `documentationURL` 屬性為使用者提供更多詳細資訊，包括範例、使用案例和其他詳細資訊。

`definitions`  <a name="hooks-properties-definitions"></a>
使用 `definitions`區塊提供共用的 Hook 屬性結構描述。  
最佳實務是使用 `definitions`區段來定義結構描述元素，可用於勾點類型結構描述中的多個點。然後，您可以使用 JSON 指標在勾點類型結構描述中的適當位置參考該元素。  
*必要*：否

`typeConfiguration`  <a name="hooks-properties-typeconfiguration"></a>
Hook 組態資料的定義。  
*必要*：是

`properties`  <a name="hooks-properties-properties"></a>
勾點的屬性。勾點的所有屬性都必須在結構描述中表示。將勾點結構描述屬性與勾點類型組態屬性對齊。  
不允許巢狀屬性。反之，請在 `definitions`元素中定義任何巢狀屬性，並使用`$ref`指標在所需的屬性中參考它們。
目前支援下列屬性：  
+ `default` – 屬性的預設值。
+ `description` – 屬性的描述。
+ `pattern` – 用於驗證輸入的 regex 模式。
+ `type` – 屬性的已接受類型。

`additionalProperties`  <a name="hooks-properties-additionalproperties"></a>
`additionalProperties` 必須設定為 `false`。勾點的所有屬性都必須以結構描述表示：不允許任意輸入。  
*必要*：是  
*有效值*：`false`

`handlers`  <a name="hooks-properties-handlers"></a>
處理常式指定可啟動結構描述中定義的勾點的操作，例如勾點叫用點。例如，`preUpdate`在處理常式中所有指定目標的更新操作之前，會叫用處理常式。  
*有效值*：`preCreate` \$1 `preUpdate` \$1 `preDelete`  
必須為處理常式指定至少一個值。
導致 狀態的堆疊操作`UpdateCleanup`不會叫用勾點。例如，在以下兩個案例中，不會叫用 Hook 的`preDelete`處理常式：  
+ 堆疊會在從範本中移除一個資源後更新。
+ 會刪除具有[替代](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html#update-replacement)更新類型的資源。

`targetNames`  <a name="hooks-properties-targetNames"></a>
Hook 目標的類型名稱字串陣列。例如，如果`preCreate`處理常式有 `AWS::S3::Bucket`目標，則 Hook 會在預先佈建階段執行 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`  <a name="hooks-properties-permissions"></a>
字串陣列，指定叫用處理常式所需的 AWS 許可。  
*必要*：是

`additionalProperties`  <a name="hooks-additional-properties"></a>
`additionalProperties` 必須設定為 `false`。勾點的所有屬性都必須以結構描述表示：不允許任意輸入。  
*必要*：是  
*有效值*：`false`

## 勾點結構描述範例
<a name="example-hooks"></a>

 **範例 1** 

Java 和 Python 演練使用以下程式碼範例。以下是名為 的勾點的範例結構`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` 的結構描述`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
}
```