本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用已與您共用的第三方私有擴充功能
若要使用已與您共用的第三方私有擴充功能，您必須先在希望使用這些擴充功能的帳戶及區域中，向 CloudFormation *註冊*這些資源提供者。註冊擴充功能會將其複本上傳到帳戶中的 CloudFormation 登錄檔並啟用它。註冊私有擴充功能後，該擴充功能會出現在該 AWS 帳戶 和 區域的 CloudFormation 登錄檔中，您可以在堆疊範本中使用它。
**Topics**
+ [註冊私有擴充功能的第三方 IAM 許可](#registry-register-permissions)
+ [使用私有擴充功能的常用 AWS CLI 命令](#registry-commonly-used-commands-private-extensions)
+ [在您的帳戶中註冊第三方私有擴充功能](registry-register-private-extension.md)
+ [從帳戶移除第三方私有擴充功能](registry-private-deregister-extension.md)
## 註冊私有擴充功能的第三方 IAM 許可
作為註冊私有擴充功能的一部分，您可能需要指定一個包含擴充功能專案套件的 Amazon S3 儲存貯體。此套件包含要註冊的擴充功能所需之任何來源檔案。註冊擴充功能的使用者必須能夠存取 Amazon S3 儲存貯體中的專案套件。為此，使用者必須具備該擴充功能套件的 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) 許可。
無論您是使用 的 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html)命令 AWS CLI，還是 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)命令，都是如此。
如需詳細資訊，請參閱*服務授權參考*中的 [Amazon S3 的動作、資源和條件索引鍵](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazons3.html)。
## 使用私有擴充功能的常用 AWS CLI 命令
處理私有擴充功能的常用命令包括：
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html)：在您的帳戶中註冊私有擴充功能。
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type-registration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type-registration.html)：傳回註冊請求的目前狀態。
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html)：列出您帳戶中的擴充功能。
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html)：傳回特定擴充功能或特定擴充功能版本的詳細資訊，包括目前的組態資料。
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html)：用於指定您帳戶中某個擴充功能的組態資料，以及停用和啟用勾點。
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-default-version.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-default-version.html)：指定哪個版本的擴充功能是預設版本。
+ [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html)：從您的帳戶中移除私有擴充功能或擴充功能版本。
# 在您的帳戶中註冊第三方私有擴充功能
本主題涵蓋註冊與您共用的第三方私有擴充功能的步驟，使其可在您的帳戶中使用。
**注意**
在繼續之前，請確認您擁有註冊私有擴充功能所需的 [IAM 許可](registry-private.md#registry-register-permissions)。
**註冊與您共用的私有擴充功能 (AWS CLI)**
1. 找出包含您想在帳戶中註冊之私有擴充功能專案套件的 Amazon S3 儲存貯體。
1. 使用 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/register-type.html) 命令在帳戶中註冊擴充功能。
例如，以下命令會在指定的 AWS 帳戶中註冊 `My::Resource::Example` 資源類型：
```
aws cloudformation register-type --type RESOURCE \
--type-name My::Resource::Example \
--schema-handler-package [s3 object path] --region us-west-2
```
`RegisterType` 是一種非同步操作，會傳回您可以用來追蹤註冊請求進度的註冊權杖。
```
{
"RegistrationToken": "f5525280-104e-4d35-bef5-8f1fexample"
}
```
如果您的延伸模組呼叫 AWS APIs做為其功能的一部分，您必須建立 IAM 執行角色，其中包含呼叫這些 AWS APIs的必要許可，並在您的帳戶中佈建該執行角色。然後您可以使用 `--execution-role-arn` 選項來指定此執行角色。CloudFormation 接著會取得該執行角色，為您的資源類型提供適當的憑證。
```
--execution-role-arn arn:aws:iam::123456789012:role/MyIAMRole
```
1. (選用) 搭配 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type-registration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type-registration.html) 命令使用註冊字符，追蹤您註冊請求的進度。
當 CloudFormation 完成註冊請求時，會將請求的進度狀態設為 `COMPLETE`。
以下範例會使用以上 `describe-type-registration` 命令傳回的註冊權杖來傳回註冊狀態資訊。
```
aws cloudformation describe-type-registration \
--registration-token f5525280-104e-4d35-bef5-8f1fexample \
--region us-west-2
```
命令會傳回下列輸出：
```
{
"ProgressStatus": "COMPLETE",
"TypeArn": "arn:aws:cloudformation:us-west-2:123456789012:type/resource/My-Resource-Example",
"Description": "Deployment is currently in DEPLOY_STAGE of status COMPLETED; ",
"TypeVersionArn": "arn:aws:cloudformation:us-west-2:123456789012:type/resource/My-Resource-Example/00000001"
}
```
**重要**
若您要註冊的擴充功能是勾點，則必須執行下一個步驟。您必須為 `HookInvocationStatus` 屬性指定 `ENABLED`。此操作將啟用勾點結構描述 `properties` 區段中定義的掛鉤屬性。有關詳細資訊，請參閱《CloudFormation Hooks 使用者指南**》中的[勾點組態結構描述語法參考](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hook-configuration-schema.html)。
**若要指定勾點 (AWS CLI) 的組態資料**
1. 取得勾點的 ARN 並儲存。您可以使用 AWS 管理主控台 或 取得勾點的 ARN AWS CLI。如需更多資訊，請參閱[在 CloudFormation 登錄檔中檢視可用的與已啟用擴充功能](registry-view.md)。
```
export HOOK_TYPE_ARN="arn:aws:cloudformation:us-west-2:123456789012:type/hook/Organization-Service-Hook/"
```
1. 若要指定組態資料，請使用 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html) 命令。您為 `--configuration` 傳遞的 JSON 必須根據勾點的組態結構描述進行驗證。要啟用勾點，您必須在 `HookConfiguration` 區段將 `HookInvocationStatus` 屬性設定為 `ENABLED`。
```
aws cloudformation set-type-configuration \
--configuration "{"CloudFormationConfiguration":{"HookConfiguration":{"HookInvocationStatus": "ENABLED", "FailureMode": "FAIL", "Properties":{}}}}" \
--type-arn $HOOK_TYPE_ARN --region us-west-2
```
有關詳細資訊，請參閱《CloudFormation Hooks 使用者指南**》中的[勾點組態結構描述語法參考](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hook-configuration-schema.html)。
# 從帳戶移除第三方私有擴充功能
要移除第三方私有擴充功能或擴充功能版本，請使用 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html) 命令。
您可取消註冊特定的擴充功能版本，或整個擴充功能。要取消註冊擴充功能，必須分別取消註冊該擴充功能的全部已註冊版本。若某個擴充功能僅有一個已註冊版本，取消註冊該版本會導致取消註冊擴充功能本身。您無法取消註冊擴充功能的預設版本，除非是該擴充功能的唯一已註冊版本，這種情況下擴充功能本身也會被取消註冊。
**警告**
私人擴充功能的取消註冊操作無法撤銷。此動作將會：
使該擴充功能在所有 CloudFormation 操作中無法使用。
導致未來使用此擴充功能的堆疊更新失敗 (適用於模組和資源類型)。儘管您稍後可以重新私下註冊該擴充功能，但如果 CloudFormation 依賴舊版本，可能會導致失敗。
繼續之前，使用 [list-stacks](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-stacks.html) 與 [get-template](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/get-template.html) 命令，驗證是否沒有作用中的堆疊使用此擴充功能。
## 取消註冊擴充功能命令的範例
本節提供範例，說明取消註冊私有擴充功能的不同方式。
**依據類型名稱取消註冊**
搭配 `--type` 和 `--type-name` 選項使用 [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deregister-type.html) 命令，即可取消註冊您的擴充功能。
```
aws cloudformation deregister-type \
--type MODULE \
--type-name My::S3::SampleBucket::MODULE
```
**依據類型名稱和版本取消註冊**
要取消註冊特定版本的擴充功能，請在命令中指定 `--version-id` 選項。
```
aws cloudformation deregister-type \
--type MODULE \
--type-name My::S3::SampleBucket::MODULE \
--version-id 00000001
```
**提示**
要先將不同版本的擴充功能設定為預設版本，使用 [set-type-default-version](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-default-version.html) 命令。
**依據 ARN 取消註冊**
搭配 `--arn` 選項並指定您擴充功能的 ARN，即可取消註冊該擴充功能。
```
aws cloudformation deregister-type \
--arn arn:aws:cloudformation:us-west-2:123456789012:type/resource/Organization-Service-Resource
```