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

# 向 註冊自訂勾點 CloudFormation
<a name="registering-hooks"></a>

建立自訂勾點後，您需要向 註冊它 CloudFormation ，才能使用它。在本節中，您將學習如何封裝和註冊您的勾點，以便在 中使用 AWS 帳戶。

## 封裝勾點 (Java)
<a name="registering-hooks-package"></a>

如果您已使用 Java 開發 Hook，請使用 Maven 來封裝它。

在 Hook 專案的 目錄中，執行下列命令來建置您的 Hook、執行單元測試，並將您的專案封裝為檔案`JAR`，可用來將 Hook 提交至 CloudFormation 登錄檔。

```
mvn clean package
```

## 註冊自訂勾點
<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’}
   ```

   *結果*：您已成功註冊您的勾點。

## 驗證勾點可在您的帳戶中存取
<a name="verifying-hooks"></a>

確認您的勾點在您提交勾點的 AWS 帳戶 和 區域中可用。

1. 若要驗證您的勾點，請使用 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html)命令列出新註冊的勾點，並傳回其摘要說明。

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

   命令會傳回下列輸出，也會顯示您可以在 AWS 帳戶 和 區域中啟用的公開可用勾點。

   ```
   {
       "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` 從勾點的`list-type`輸出擷取 並儲存它。

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

若要了解如何發佈勾點以供公開使用，請參閱 [發佈勾點以供公開使用](hooks-publishing.md)。

### 設定勾點
<a name="configure-hooks"></a>

開發並註冊 Hook 之後，您可以透過將 Hook 發佈到登錄檔 AWS 帳戶 ，在 中設定您的 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`中設定為 。
**注意**  
在帳戶中啟用勾點，即表示您授權勾點使用您 定義的許可 AWS 帳戶。CloudFormation 會在將您的許可傳遞給勾點之前，移除非必要的許可。CloudFormation 建議客戶或勾點使用者檢閱勾點許可，並注意在您的帳戶中啟用勾點之前允許勾點的許可。

  在相同的 帳戶和 中，指定已註冊的 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 主動檢查堆疊的組態，您必須在帳戶中註冊和啟用 Hook 之後，在 `HookConfiguration`區段`HookInvocationStatus``ENABLED`中將 設定為 。

## 在處理常式中存取 AWS APIs
<a name="accessing-apis-in-handlers"></a>

如果您的 Hooks 在其任何處理常式中使用 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`旗標，則會佈建此堆疊中的角色，並用作勾點的執行角色。

如需詳細資訊，請參閱[從資源類型存取 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 和 Amazon 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
```