本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Cloud Control API 資源操作
使用 AWS 雲端控制 API 對 中的資源執行 或其他命令動詞建構建立、讀取、更新、移除和列出 (-L) 操作 AWS 帳戶。
**Topics**
+ [先決條件](#resource-operations-prerequisites)
+ [指定登入資料](#resource-operations-permissions)
+ [確保請求是唯一的](#resource-operations-idempotency)
+ [考量事項](#resource-operations-considerations)
+ [建立資源](resource-operations-create.md)
+ [更新資源](resource-operations-update.md)
+ [刪除資源](resource-operations-delete.md)
+ [探索資源](resource-operations-list.md)
+ [讀取資源](resource-operations-read.md)
+ [管理資源請求](resource-operations-manage-requests.md)
+ [使用 識別資源 AWS 雲端控制 API](resource-identifier.md)
## 搭配 Cloud Control API 使用 資源的先決條件
若要使用 Cloud Control API 佈建特定資源，該資源類型必須支援 Cloud Control API，並可在您的 中使用 AWS 帳戶。
+ **可用於 的資源 AWS 帳戶**
若要可在您的帳戶中使用，必須啟用公有資源類型，且必須註冊私有資源類型。支援 AWS 的資源類型為公有且一律啟用。如需詳細資訊，請參閱[使用 Cloud Control API 資源類型](resource-types.md)。
+ **支援 Cloud Control API 的資源**
如需支援 Cloud Control API AWS 的資源類型清單，請參閱 [支援雲端控制 API 的資源類型](supported-resources.md)。
公有和私有的第三方資源類型都支援 Cloud Control API。
如需如何判斷特定資源類型是否支援 Cloud Control API 的詳細資訊，請參閱 [判斷資源類型是否支援 Cloud Control API](resource-types.md#resource-types-determine-support)。
如需使用資源類型的詳細資訊，請參閱 [使用 Cloud Control API 資源類型](resource-types.md)。
## 指定 Cloud Control API 的登入資料
作為代表您執行 AWS 資源操作的一部分，Cloud Control API 必須呼叫實際佈建這些資源的基礎 AWS 服務。為此，Cloud Control API 需要必要的登入資料才能存取這些服務。有兩種方式可讓您啟用 Cloud Control API 來取得這些登入資料：
+ **使用者登入資料**
根據預設，Cloud Control API 會使用 AWS 使用者登入資料建立暫時工作階段，並使用該工作階段對下游 AWS 服務進行任何必要的呼叫。此工作階段最多持續 24 小時，之後 AWS Cloud Control API 對 的任何剩餘呼叫都會失敗。
+ **服務角色登入資料**
您也可以在提出資源請求時，為 Cloud Control API 指定要在資源操作期間擔任的服務角色。除此之外，指定服務角色可讓 Cloud Control API 呼叫基礎 AWS 服務長達 36 小時。
若要使用服務角色，請指定資源操作請求的 `RoleArn` 參數。
由於 Cloud Control API 動作是 CloudFormation 服務的一部分，因此 CloudFormation 服務 () 會擔任您指定的服務角色`cloudformation.amazonaws.com`。如需詳細資訊，請參閱*AWS CloudFormation 《 使用者指南*》中的[CloudFormation 服務角色](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-servicerole.html)。
每個資源處理常式所需的許可，會在該資源類型的結構描述的 `handlers`區段中定義。如需檢視資源結構描述的詳細資訊，請參閱 。[檢視資源類型結構描述](resource-types.md#resource-types-schemas)`handlers` 區段是在[資源類型定義結構描述](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-schema.html#schema-properties-handlers)中定義。
## 使用 Cloud Control API 時，確保資源操作請求是唯一的
最佳實務是，強烈建議您指定具有建立、刪除和更新資源操作請求的等冪字符。最好為每個請求指定唯一的字符，例如通用唯一識別符 (UUID)。這類字符可確保在必須重試請求的情況下，請求可以被模糊化。
`create-resource`、 `delete-resource`和 `update-resource`操作全都採用 `client-token` 參數，可設定為冪等字符。
## 使用 Cloud Control API 時的考量事項
我們建議您在使用 Cloud Control API 執行資源操作時，將下列服務行為納入考量：
+ Cloud Control API 會個別執行每個資源操作，且獨立於任何其他資源操作。
+ 對 Cloud Control API 的單一資源操作請求實際上可能包含對佈建資源之基礎服務的多個呼叫。因此，只有部分完成時，資源請求可能會失敗，導致只有部分請求的變更會套用至資源。
+ 如果資源操作在任何時候失敗，Cloud Control API 不會將資源復原至先前的狀態。
+ 您一次只能對使用 Cloud Control API 的指定資源執行一個資源操作。不過，仍然可以透過佈建資源的基礎服務直接在 上操作資源。我們強烈建議您不要使用此方法，因為這可能會導致無法預測的行為。
# 使用 建立資源 AWS 雲端控制 API
使用 `create-resource`命令來建立資源。
## 編寫資源的所需狀態
若要讓 Cloud Control API 建立資源，您必須指定要建立之資源的*所需狀態*。所需的狀態包含您要指定的資源屬性清單，及其所需的值。
資源的屬性會在其資源類型結構描述中定義。這包括屬性是否為必要、有效值，以及其他屬性限制條件。如需檢視資源屬性定義的詳細資訊，請參閱 [檢視資源類型結構描述](resource-types.md#resource-types-schemas)。
您指定的所需狀態必須對資源類型結構描述有效。
例如，假設您想要建立具有特定名稱和 90 天保留政策[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html)的資源。首先，您必須編寫所需的資源狀態，格式為 JSON 文字。
```
{
"LogGroupName": "CloudApiLogGroup",
"RetentionInDays": 90
}
```
當您呼叫 `create-resource`命令時，您可以將所需的狀態直接內嵌傳遞為字串，或者，對於更複雜的所需狀態定義，請指定檔案位置。
following AWS Command Line Interface (AWS CLI) 命令會建立 資源，並在 `desired-state` 參數中指定除了指定日誌群組名稱之外`90`，資源的 `RetentionInDays` 屬性設為 。
```
$ aws cloudcontrol create-resource --type-name AWS::Logs::LogGroup \
--desired-state '{"LogGroupName": "CloudApiLogGroup", "RetentionInDays":90}'
```
## 追蹤建立資源請求的進度
`create-resource` 命令會傳回`ProgressEvent`物件，您可以用來監控資源建立請求的目前狀態。如需詳細資訊，請參閱[追蹤資源操作請求的進度](resource-operations-manage-requests.md#resource-operations-manage-requests-track)。
# 使用 更新資源 AWS 雲端控制 API
使用 `update-resource`命令來更新現有資源。這包括最初未使用 Cloud Control API 佈建的資源。
**重要**
我們強烈建議不要使用 Cloud Control API 來更新由其他 服務主動管理的資源。這樣做可能會導致意外的結果。例如，請勿使用 Cloud Control API 來更新目前屬於 CloudFormation 堆疊的資源。
若要更新現有資源，您必須指定資源的識別符。如需判斷資源識別符的詳細資訊，請參閱 [使用資源的主要識別符](resource-identifier.md#resource-identifier-using)。
更新資源需要變更資源屬性值。資源的屬性會在其資源類型結構描述中定義。這包括屬性是否為必要、有效值，以及其他屬性限制條件。如需檢視資源屬性定義的詳細資訊，請參閱 [檢視資源類型結構描述](resource-types.md#resource-types-schemas)。
## 編寫修補程式文件
若要更新資源，請先將更新定義為 JSON *修補程式文件中包含的修補程式操作*清單。此修補程式文件必須遵循 [https://datatracker.ietf.org/doc/html/rfc6902](https://datatracker.ietf.org/doc/html/rfc6902)中定義的標準。
每個修補程式操作都會定義特定資源屬性的單一更新。需要下列屬性：
+ `op`：操作類型。Cloud Control API 支援 RFC 6902 中定義的所有操作：`add`、`remove`、`replace`、`move`、 `copy`和 `test`。
+ `path`：資源屬性的路徑，相對於資源結構描述的 `properties`區段。
視操作而定，可能需要其他屬性。如需詳細資訊，請參閱 RFC 6902。
使用 `update-resource`命令時，您可以將修補程式文件內嵌指定為字串，或指定檔案位置。
下列範例會將[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html)名為 的資源保留政策更新`CloudControlApiLogGroup`為 90 天。
```
$ aws cloudcontrol update-resource --type-name AWS::Logs::LogGroup \
--identifier CloudControlApiLogGroup \
--patch-document '[{"op":"replace","path":"RetentionInDays","value":90}]'
```
## Cloud Control API 如何更新資源
若要更新資源，Cloud Control API 會先擷取資源的目前狀態，然後在兩個步驟程序中更新資源：
+ Cloud Control API 結合更新請求中指定的修補程式操作與資源的目前狀態，以在更新後產生資源的所需狀態。操作會依其出現在修補程式文件中的順序依序套用。序列中的每個操作都會套用至資源的目前狀態；產生的資源狀態會成為下一個操作的目標。
此時，如果出現下列情況，則整個更新請求會失敗：
+ 請求中包含的修補程式操作無效。
+ `op` 類型的修補程式操作`test`失敗。
在這種情況下，整個更新請求會失敗，而 Cloud Control API 不會更新資源。
+ 然後，Cloud Control API 會呼叫資源類型的更新處理常式來更新資源。
如果更新處理常式在任何時間點失敗，*Cloud Control API 不會將資源復原至先前的狀態。*
例如，請考慮下列已定義用來更新 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html) 資源的修補程式文件。文件包含兩個修補程式操作。第一個操作是 類型`test`，並檢查資源的保留政策是否設定為 3653 天。如果是這種情況，資源會通過測試，雲端控制 API 會繼續進行下一個操作。此操作會將目前的保留政策值取代為 180 天。如果資源的保留政策設定為 3653 天以外的值，則第一個`test`操作會失敗，而 Cloud Control API 永遠不會執行第二個`replace`操作。
```
[
{
"op": "test",
"path": "/RetentionInDays",
"value":3653
},
{
"op": "replace",
"path": "/RetentionInDays",
"value":180
}
]
```
## 追蹤更新資源請求的進度
`update-resource` 命令會傳回物件`ProgressEvent`，您可以用來追蹤資源操作請求的目前狀態。如需詳細資訊，請參閱[追蹤資源操作請求的進度](resource-operations-manage-requests.md#resource-operations-manage-requests-track)。
# 使用 刪除資源 AWS 雲端控制 API
使用 `delete-resource`命令來刪除現有的資源。無論資源最初是否使用 Cloud Control API 佈建，您都可以刪除資源。
**重要**
我們強烈建議不要使用 Cloud Control API 來刪除由其他 服務主動管理的資源。這樣做可能會導致非預期的結果。例如，請勿使用 Cloud Control API 來刪除目前屬於 CloudFormation 堆疊的資源。
若要更新現有資源，您必須指定資源的識別符。如需尋找資源識別符的詳細資訊，請參閱 [使用資源的主要識別符](resource-identifier.md#resource-identifier-using)。
下列範例會刪除名稱為 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html)的資源`CloudControlApiLogGroup`。
```
$ aws cloudcontrol delete-resource \
--type-name AWS::Logs::LogGroup --identifier CloudControlApiLogGroup
```
## 追蹤刪除資源請求的進度
`delete-resource` 命令會傳回物件`ProgressEvent`，您可用來追蹤資源操作請求的目前狀態。如需詳細資訊，請參閱[追蹤資源操作請求的進度](resource-operations-manage-requests.md#resource-operations-manage-requests-track)。
# 使用 探索資源 AWS 雲端控制 API
使用 `list-resources`命令來探索目前在 AWS 帳戶 和 中佈建的資源 AWS 區域。這包括指定資源類型的所有資源，無論它們是透過 Cloud Control API 佈建、直接透過基礎服務或其他機制 （例如 AWS CloudFormation 堆疊的一部分）。
每個資源傳回的資訊包括：
+ 資源的主要識別符。
+ 或者，它可能包含*部分或所有*資源的屬性，詳細說明資源的目前狀態。如需詳細資訊，請參閱[檢視資源類型結構描述](resource-types.md#resource-types-schemas)。
以下範例會傳回`AWS::Logs::LogGroup`資源清單。
```
$ aws cloudcontrol list-resources --type-name AWS::Logs::LogGroup
```
Cloud Control API 會傳回您帳戶中指定資源類型的資源清單。對於範例 ， 會`list-resources`傳回您帳戶中所有`AWS::Logs::LogGroup`資源的主要識別符和資源屬性，無論它們是否由 Cloud Control API 佈建。傳回的資訊類似以下內容，視您帳戶中的資源而定。
```
{
"TypeName": "AWS::Logs::LogGroup",
"ResourceDescriptions":
[
{
"Identifier": "CloudControlExample",
"Properties": '{"RetentionInDays":180, "LogGroupName": "CloudControlExample", "Arn": "arn:aws:logs:us-west-2:123456789012:log-group:CloudControlExample:*"}'
},
{
"Identifier": "AnotherLogGroupResourceExample",
"Properties": '{"RetentionInDays":90, "LogGroupName": "AnotherLogGroupResourceExample", "Arn": "arn:aws:logs:us-west-2:123456789012:log-group:AnotherLogGroupResourceExample:*"}'
}
]
}
```
下列範例會請求`AWS::Kinesis::Stream`資源清單。
```
$ aws cloudcontrol list-resources --type-name AWS::Kinesis::Stream
```
對於 Kinesis 串流，Cloud Control API 會傳回每個串流的主要識別符，以及資源屬性的*子集*。在此情況下，只有單一屬性 `Name`。然後，您可以將串流的主要識別符與 搭配使用`get-resource`，以請求資源的完整目前狀態。
```
{
"TypeName": "AWS::Kinesis::Stream",
"ResourceDescriptions": [
{
"Identifier": "MyKinesisStream",
"Properties": '{"Name": "MyKinesisStream"}'
},
{
"Identifier": "AnotherStream",
"Properties": '{"Name": "AnotherStream"}'
}
]
}
```
## 需要其他資訊的資源
某些資源需要您提供有關要列為請求一部分之資源的其他資訊。在這些情況下，您必須使用 `ResourceModel` 參數來指定這些屬性。
下表列出這些資源，以及您在清單請求期間要在 `ResourceModel` 參數中指定的屬性。
| Resources | 必要屬性 |
| --- | --- |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-documentationversion.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-documentationversion.html) | `RestApiId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html) | `RestApiId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudformation-resourceversion.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudformation-resourceversion.html) | `TypeArn` 或 `TypeName` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-customerprofiles-integration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-customerprofiles-integration.html) | `DomainName` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-customerprofiles-objecttype.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-customerprofiles-objecttype.html) | `DomainName` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-transitgatewaymulticastgroupmember.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-transitgatewaymulticastgroupmember.html) | `TransitGatewayMulticastDomainId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-transitgatewaymulticastgroupsource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-transitgatewaymulticastgroupsource.html) | `TransitGatewayMulticastDomainId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ecs-taskset.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ecs-taskset.html) | `Cluster`、`Service` 與 `ID` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-eks-addon.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-eks-addon.html) | `ClusterName` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-eks-fargateprofile.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-eks-fargateprofile.html) | `ClusterName` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticloadbalancingv2-listener.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticloadbalancingv2-listener.html) | `LoadBalancerArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticloadbalancingv2-listenerrule.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-elasticloadbalancingv2-listenerrule.html) | `ListenerArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-glue-schemaversion.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-glue-schemaversion.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudcontrolapi/latest/userguide/resource-operations-list.html) |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-glue-schemaversionmetadata.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-glue-schemaversionmetadata.html) | `SchemaVersionId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iotsitewise-accesspolicy.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iotsitewise-accesspolicy.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudcontrolapi/latest/userguide/resource-operations-list.html) |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iotsitewise-dashboard.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iotsitewise-dashboard.html) | `ProjectId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iotsitewise-project.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iotsitewise-project.html) | `PortalId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kendra-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kendra-datasource.html) | `IndexId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kendra-faq.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kendra-faq.html) | `IndexId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowentitlement.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowentitlement.html) | `FlowArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowoutput.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowoutput.html) | `FlowArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowsource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowsource.html) | `FlowArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowvpcinterface.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediaconnect-flowvpcinterface.html) | `FlowArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediapackage-asset.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediapackage-asset.html) | `PackagingGroupId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediapackage-packagingconfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-mediapackage-packagingconfiguration.html) | `PackagingGroupId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-networkfirewall-loggingconfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-networkfirewall-loggingconfiguration.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cloudcontrolapi/latest/userguide/resource-operations-list.html) |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-analysis.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-analysis.html) | `AwsAccountId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-dashboard.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-dashboard.html) | `AwsAccountId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-dataset.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-dataset.html) | `AwsAccountId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-datasource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-datasource.html) | `AwsAccountId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-template.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-template.html) | `AwsAccountId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-theme.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-quicksight-theme.html) | `AwsAccountId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-rds-dbproxytargetgroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-rds-dbproxytargetgroup.html) | `DBProxyName` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-s3outposts-accesspoint.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-s3outposts-accesspoint.html) | `Bucket` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-s3outposts-bucket.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-s3outposts-bucket.html) | `OutpostId` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sso-assignment.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sso-assignment.html) | `InstanceArn`、`PermissionSetArn`、`PrincipalId`、`PrincipalType`、`TargetId` 和 `TargetType` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sso-instanceaccesscontrolattributeconfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sso-instanceaccesscontrolattributeconfiguration.html) | `InstanceArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sso-permissionset.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sso-permissionset.html) | `InstanceArn` 和 `PermissionSetArn` |
| [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-wafv2-webacl.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-wafv2-webacl.html) | `Scope` |
# 使用 讀取資源 AWS 雲端控制 API
您可以使用資源的主要識別符，呼叫 `get-resource`命令來擷取資源的詳細資訊。如需擷取資源主要識別符的資訊，請參閱 [使用 識別資源 AWS 雲端控制 API](resource-identifier.md)。
傳回的資訊`get-resource`包含資源的結構描述，其中詳細說明資源的目前狀態，包括屬性值、支援的事件和必要的許可。如需詳細資訊，請參閱[檢視資源類型結構描述](resource-types.md#resource-types-schemas)。
下列範例會傳回名為 之`AWS::Logs::LogGroup`資源的目前狀態`LogGroupResourceExample`。對於 `AWS::Logs::LogGroup` 資源，日誌群組的名稱是其主要識別符。
```
$ aws cloudcontrol get-resource --type-name AWS::Logs::LogGroup --identifier LogGroupResourceExample
```
# 使用 管理資源操作請求 AWS 雲端控制 API
由於資源操作是非同步的，因此 `create-resource`和 等資源請求會`update-resource`傳回`ProgressEvent`物件，其中包含資源建立或更新請求目前狀態的相關資訊。
例如，資源建立請求一開始可能會傳回下列`ProgressEvent`物件。
```
{
"ProgressEvent": {
"EventTime": "2021-08-09T18:17:15.219Z",
"TypeName": "AWS::Logs::LogGroup",
"OperationStatus": "IN_PROGRESS",
"Operation": "CREATE",
"Identifier": "LogGroupResourceExample",
"RequestToken": "5f40c577-3534-4b20-9599-0b0123456789"
}
}
```
`ProgressEvent` 物件中傳回的資訊包含一個請求字符，然後您可以使用它來追蹤或取消資源操作請求。
**注意**
資源操作請求會在七天後過期。
## 列出作用中資源操作請求
使用 `list-resource-requests`命令傳回 AWS 帳戶 和 的作用中資源操作請求清單 AWS 區域。您可以依請求類型和狀態篩選清單。
資源操作請求會在七天後過期。
下列範例會傳回作用中的資源操作請求，但會篩選掉任何仍在進行的資源建立請求。
```
$ aws cloudcontrol list-resource-requests --resource-request-status-filter \
Operations=CREATE,OperationStatuses=IN_PROGRESS
```
每個資源操作傳回的資訊包括一個請求字符，然後您可以使用它來追蹤或取消資源操作請求。
```
{
"ResourceRequestStatusSummaries": [
{
"EventTime": "2021-08-09T18:17:16.591Z",
"TypeName": "AWS::Logs::LogGroup",
"OperationStatus": "SUCCESS",
"Operation": "CREATE",
"Identifier": "LogGroupResourceExample",
"RequestToken": "5f40c577-3534-4b20-9599-0b0123456789"
}
]
}
```
## 追蹤資源操作請求的進度
使用 `get-resource-request-status`命令來追蹤資源操作請求的進度。此命令會取得在初始資源操作請求期間產生的 `ProgressEvent` 物件中包含的請求字符。（您也可以使用 `list-resource-requests`命令擷取資源操作請求的請求字符。) `get-resource-request-status` 命令會傳回更新的`ProgressEvent`物件，其中包含請求目前狀態的相關資訊。
請參閱以下範例。
```
$ aws cloudcontrol get-resource-request-status \
--request-token 5f40c577-3534-4b20-9599-0b0123456789
```
## 取消資源操作請求
使用 `cancel-resource-request`命令取消目前正在處理的資源操作請求。由於您一次只能對指定的資源執行單一操作，因此在某些情況下，您可能需要取消目前的資源操作，才能讓資源可用，以便對它執行另一個操作。
取消資源請求並不保證 Cloud Control API 可以立即取消所有資源操作。相反地，Cloud Control API 將停止對資源事件處理常式進行進一步呼叫。對 Cloud Control API 的單一資源操作請求實際上可能包含對佈建資源之基礎服務的多個呼叫。因此，取消資源操作請求可能會讓請求部分完成，導致只有部分請求的變更會套用至資源。Cloud Control API 不會將資源復原至先前的狀態。
只能`IN_PROGRESS`取消狀態為 `PENDING`或 的資源操作請求。
**注意**
雖然呼叫會`CancelResourceRequest`取消 Cloud Control API 執行的操作，但不會終止可能已在下游服務上啟動的任何非同步操作。
# 使用 識別資源 AWS 雲端控制 API
每個資源類型都有定義為其*主要識別符*的屬性。對於指定 AWS 帳戶 和 中該類型的每個資源，此屬性的值必須是唯一的 AWS 區域。例如，許多資源類型包含`Name`屬性，對於該類型的每個資源都必須是唯一的。在某些情況下，主要識別符定義為多個屬性的組合，這些屬性共同形成唯一識別符。透過使用此主要識別符與資源類型結合，您可以指定要在其中執行資源操作的確切資源，例如 `update-resource`或 `delete-resource`。
此外，某些資源類型會定義*次要識別符*，也可以用來唯一識別該類型的資源。
若要判斷哪個資源屬性 （或屬性組合） 是資源類型的主要識別符，請參閱資源類型結構描述的`primaryIdentifier`屬性。結構描述也包含定義的次要識別符。如需詳細資訊，請參閱[檢視資源類型結構描述](resource-types.md#resource-types-schemas)。
## 取得資源的主要識別符
您可以使用 Cloud Control API 命令來尋找特定資源的識別符*值*。下列每個命令都會傳回包含指定資源主要識別符的`ProgressEvent`物件：
+
```
cancel-resource-request
```
+
```
create-resource
```
+
```
get-resource-request-status
```
+
```
list-resource-requests
```
## 使用資源的主要識別符
使用 Cloud Control API 命令時，您可以在其資源結構描述中指定主要識別符或任何為資源類型定義的次要識別符。您只能指定一個識別符。主要識別符可以指定為字串或 JSON；次要識別符必須指定為 JSON。
對於複合主要識別符 （即由多個資源屬性組成的一個），若要將主要識別符指定為字串，請依在主要識別符定義中*指定的順序*列出屬性值，並以 分隔`|`。
例如，資源的主要識別符定義為：
`"primaryIdentifier": [ "/properties/DatabaseName", "/properties/TableName" ]`
因此，若要將資源的主要識別符指定為字串，請使用下列格式。
`DatabaseName|TableName`
例如，指定資料庫名稱為 `MyDatabase`且資料表名稱為 的資料庫`MyTable`，您可以指定 `MyDatabase|MyTable`。
對於指定為 JSON 的複合識別符，不需要屬性順序，如下列範例所示。
```
{
"TableName": "MyTable",
"DatabaseName": "MyDatabase"
}
```
如需資源識別符的詳細資訊，請參閱 *CloudFormation 命令列界面使用者移動以進行延伸開發*中的[主要識別符](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-schema.html#schema-properties-primaryidentifier)。