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

# 向注册自定义 Hook CloudFormation
<a name="registering-hooks"></a>

创建自定义 Hook 后，需要向其注册 CloudFormation 才能使用它。在本节中，你将学习如何打包和注册你的Hook，以便在你的 AWS 账户。

## Package a Hook (Java)
<a name="registering-hooks-package"></a>

如果你是用 Java 开发的 Hook，请使用 Maven 对其进行打包。

在 Hook 项目的目录中，运行以下命令来构建 Hook，运行单元测试，并将项目打包为可用于将 Hook 提交到 CloudFormation 注册表`JAR`的文件中。

```
mvn clean package
```

## 注册一个自定义 Hook
<a name="registering-hooks-register"></a>

**注册挂钩**

1. （可选）通过提交[https://docs.aws.amazon.com/cli/latest/reference/configure/](https://docs.aws.amazon.com/cli/latest/reference/configure/)操作`us-west-2`，将您的默认 AWS 区域 名称配置为。

   ```
   $ aws configure
   AWS Access Key ID [None]: <Your Access Key ID>
   AWS Secret Access Key [None]: <Your Secret Key>
   Default region name [None]: us-west-2
   Default output format [None]: json
   ```

1. （可选）以下命令无需注册即可构建和打包您的 Hook 项目。

   ```
   $ cfn submit --dry-run
   ```

1. 使用 CloudFormation CLI [https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-submit.html](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-submit.html)操作注册您的挂钩。

   ```
   $ cfn submit --set-default
   ```

   该命令将返回以下命令。

   ```
   {‘ProgressStatus’: ‘COMPLETE’}
   ```

   *结果*：您已成功注册您的 Hook。

## 验证您的账户中是否可以访问 Hook
<a name="verifying-hooks"></a>

确认您的 Hook 在您 AWS 账户 和您提交该挂钩的区域中可用。

1. 要验证您的 Hook，请使用[https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html)命令列出您新注册的 Hook 并返回其摘要描述。

   ```
   $ aws cloudformation list-types
   ```

   该命令返回以下输出，还将向您显示可在 AWS 账户 和区域中激活的公开可用的 Hook。

   ```
   {
       "TypeSummaries": [
           {
               "Type": "HOOK",
               "TypeName": "MyCompany::Testing::MyTestHook",
               "DefaultVersionId": "00000001",
               "TypeArn": "arn:aws:cloudformation:us-west-2:ACCOUNT_ID/type/hook/MyCompany-Testing-MyTestHook",
               "LastUpdated": "2021-08-04T23:00:03.058000+00:00",
               "Description": "Verifies S3 bucket and SQS queues properties before creating or updating"
           }
       ]
   }
   ```

1. `TypeArn`从 Hook 的`list-type`输出中检索并保存。

   ```
   export HOOK_TYPE_ARN=arn:aws:cloudformation:us-west-2:ACCOUNT_ID/type/hook/MyCompany-Testing-MyTestHook
   ```

要了解如何发布 Hook 供公众使用，请参阅[发布 Hook 供公众使用](hooks-publishing.md)。

### 配置挂钩
<a name="configure-hooks"></a>

开发并注册了 Hook 后，您可以 AWS 账户 通过将其发布到注册表来配置您的 Hook。
+ 要在您的账户中配置 Hook，请使用[https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_SetTypeConfiguration.html)操作。此操作启用挂钩架构 `properties` 部分中定义的挂钩属性。在以下示例中，该`minBuckets`属性在配置`1`中设置为。
**注意**  
通过在您的账户中启用 Hook，即授权 Hook 使用您的 AWS 账户已定义权限。 CloudFormation 在将您的权限传递给 Hook 之前，会移除不需要的权限。 CloudFormation 建议客户或 Hook 用户在账户中启用 Hook 之前，先查看 Hook 权限并了解允许 Hook 拥有哪些权限。

  在同一个账户中为你注册的 Hook 扩展指定配置数据，然后 AWS 区域。

  ```
  $ aws cloudformation set-type-configuration --region us-west-2 
    --configuration '{"CloudFormationConfiguration":{"HookConfiguration":{"HookInvocationStatus":"ENABLED","FailureMode":"FAIL","Properties":{"minBuckets": "1","minQueues": "1", "encryptionAlgorithm": "aws:kms"}}}}'
    --type-arn $HOOK_TYPE_ARN
  ```
**重要**  
要使您的 Hook 能够主动检查堆栈的配置，您必须在账户`ENABLED`中注册并激活 Hook 之后，在该`HookConfiguration`部分中将设置为。`HookInvocationStatus`

## AWS APIs 在处理程序中访问
<a name="accessing-apis-in-handlers"></a>

如果您的 Hook 在其任何处理程序中使用 AWS API，则 CFN-CLI 会自动创建 IAM 执行角色模板。`hook-role.yaml`该`hook-role.yaml`模板基于在 Hook 架构的处理程序部分中为每个处理程序指定的权限。如果在[https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-generate.html](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-generate.html)操作期间未使用该`--role-arn`标志，则将配置此堆栈中的角色并将其用作 Hook 的执行角色。

有关更多信息，请参阅[AWS APIs 从资源类型访问。](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-develop.html#resource-type-develop-executionrole)

### hook-role.yaml 模板
<a name="resource-role.yaml"></a>

**注意**  
如果您选择创建自己的执行角色，我们强烈建议您遵循最低权限原则，即仅允许上架`hooks.cloudformation.amazonaws.com`和`resources.cloudformation.amazonaws.com`。

以下模板使用 IAM、Amazon S3 和亚马逊 SQS 权限。

```
AWSTemplateFormatVersion: 2010-09-09
Description: >
  This CloudFormation template creates a role assumed by CloudFormation during
  Hook operations on behalf of the customer.
Resources:
  ExecutionRole:
    Type: 'AWS::IAM::Role'
    Properties:
      MaxSessionDuration: 8400
      AssumeRolePolicyDocument:
        Version: 2012-10-17
        Statement:
          - Effect: Allow
            Principal:
              Service:
                - resources.cloudformation.amazonaws.com
                - hooks.cloudformation.amazonaws.com
            Action: 'sts:AssumeRole'
            Condition:
              StringEquals:
                aws:SourceAccount: !Ref AWS::AccountId
              StringLike:
                aws:SourceArn: !Sub arn:${AWS::Partition}:cloudformation:${AWS::Region}:${AWS::AccountId}:type/hook/MyCompany-Testing-MyTestHook/*
      Path: /
      Policies:
        - PolicyName: HookTypePolicy
          PolicyDocument:
            Version: 2012-10-17
            Statement:
              - Effect: Allow
                Action:
                  - 's3:GetEncryptionConfiguration'
                  - 's3:ListBucket'
                  - 's3:ListAllMyBuckets'
                  - 'sqs:GetQueueAttributes'
                  - 'sqs:GetQueueUrl'
                  - 'sqs:ListQueues'
                Resource: '*'
Outputs:
  ExecutionRoleArn:
    Value: !GetAtt 
      - ExecutionRole
      - Arn
```